Deploy Your Server

Larkup can run the retrieval and chat API locally or deploy it to a cloud provider. Open Settings → Larkup Server to manage both paths.

Launch and test locally

Open Larkup Server

Go to Settings → Larkup Server. When the server is stopped, select Launch server.

Larkup Server settings with the local server stopped — Larkup Server before the local API is launched

Copy the connection details

After launch, the page shows the local endpoint, server API key, SDK connection action, test action, and interactive API reference.

Running Larkup server with endpoint and API key controls — A running local server with connection actions

The app assigns an available workspace port starting at 8080. A generated standalone server uses 8080 by default.

Verify the API

Use Try it, open API reference, or run:

larkup test --endpoint http://localhost:8080

Deploy from the Web UI

Select Deploy to choose Vercel, Hetzner, Azure, AWS, GCP, DigitalOcean, or another available target.

Deployment provider menu in Larkup Server settings — Choose a cloud target from Larkup Server settings

Vercel

Choose Vercel

Select Deploy → Vercel from the server page.

Provider settings

Paste your Vercel token and a project name, then verify the connection.

Vercel token and project name form — Vercel provider settings

Server configuration

Confirm the embedding model, then choose the AI chat runtime for this deployment. It uses the Project provider by default and can be overridden with OpenAI, DeepSeek, Google, Mistral, Cohere, or Vercel AI Gateway. Review the environment values, including the server API key.

Embedding model, AI chat runtime, and environment variables — Server configuration for a Vercel deployment

Local LanceDB files are not durable on a serverless deployment. Use Pinecone, LanceDB with S3 compatible storage, or another persistent provider when the deployed server includes the knowledge base.

Deploy

Select Deploy Server. Larkup opens the Cloud deployments tab when the request is accepted, where you can follow the provider status and open the API endpoint.

VPS and other cloud targets

Choose the provider from the same Deploy menu. For an SSH target, provide the host, user, authentication method, and required environment values. Larkup builds the server, launches it through Docker, and returns the deployed endpoint.

Put a reverse proxy such as Caddy or Nginx in front of a public VPS endpoint to provide HTTPS and a custom domain.

Deploy from the CLI

Generate a portable artifact:

larkup deploy docker --out ./deployment
larkup deploy vercel --out ./deployment

Start locally or create the agent server target:

larkup deploy local
larkup deploy agent
larkup deploy agent --start

After deployment, verify the endpoint:

larkup test --endpoint https://your-server.example.com \
  --api-key "$LARKUP_API_KEY"

Before going live

Set a strong server API key.
Use persistent storage for the deployed knowledge base.
Add the model, embedding, and storage credentials required by your configuration.
Keep secrets in the deployment provider rather than source control.
Test the health, query, chat, and API reference endpoints.

The generated output is a standard Node.js server and includes a Dockerfile and vercel.json.

Create a chat assistant for your website in minutes

Once your server is running, open Settings → Larkup Server → Connections → Chat Widget → Customize.

Customize the appearance

Set the title, welcome message, placeholder, accent colour, position, and dark mode. Save, then restart the local runtime or redeploy to publish the update.

Chat widget appearance form with a live preview — Chat widget appearance settings with a live preview

This is what it looks like running on a page:

Chat widget open and answering a question on a demo site — The widget open on a live site

Embed it

The same page gives you a ready to copy script using your server’s URL:

<script
  async
  src="https://your-agent.example.com/widget.js"
  data-api-key="YOUR_SERVER_API_KEY"
  data-position="bottom-right"
  data-theme="light"
></script>

The generated server owns /widget.js and /chat, so the widget works the same locally, in Docker, and after deployment. It renders inside a Shadow DOM to keep its styles separate from the host site. Individual embeds can override the generated defaults:

<script
  async
  src="https://your-agent.example.com/widget.js"
  data-api-key="YOUR_SERVER_API_KEY"
  data-title="Sales questions"
  data-primary-color="#0ea5e9"
  data-position="bottom-left"
  data-theme="dark"
  data-class="fixed z-50"
></script>

data-class is applied to the widget’s outer mount. The chat interface itself is intentionally isolated, so host Tailwind classes cannot accidentally break the embedded UI.

Security

data-api-key is readable by every visitor to the page. Use a scoped, low-privilege retrieval key for a browser widget, or put a small authenticated proxy in front of the Agent server for production sites. Never embed an admin, ingest, model-provider, sandbox, or Marketplace credential in client code. The same key is available behind a reveal/copy control in the Larkup Server screen only for the current browser session. Use it server side for production calls, where the key stays private.

React

Load the same script once in a client component:

'use client';

import { useEffect } from 'react';

export function SupportWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.async = true;
    script.src = 'https://your-agent.example.com/widget.js';
    script.dataset.apiKey = process.env.NEXT_PUBLIC_LARKUP_WIDGET_KEY!;
    document.body.appendChild(script);
    return () => window.LarkupWidget?.destroy();
  }, []);

  return null;
}

Prefer a proxy or a purpose-made retrieval key rather than exposing a general server key through a NEXT_PUBLIC_* variable.

Getting Started

Use Cases

Developer Guide

Deploy Your Server

Launch and test locally

Deploy from the Web UI

Vercel

VPS and other cloud targets

Deploy from the CLI

Before going live

Create a chat assistant for your website in minutes

Customize the appearance

Embed it

Security

React

​Launch and test locally

​Deploy from the Web UI

​Vercel

​VPS and other cloud targets

​Deploy from the CLI

​Before going live

​Create a chat assistant for your website in minutes

​Customize the appearance

​Embed it

​Security

​React

Launch and test locally

Deploy from the Web UI

Vercel

VPS and other cloud targets

Deploy from the CLI

Before going live

Create a chat assistant for your website in minutes

Customize the appearance

Embed it

Security

React