Self-hosting

License

CE is published under the LiveContext Sustainable Use License 1.0. You may use, copy, modify, and redistribute it for free, including in production and for your organization's internal business. What the license forbids is offering it to third parties, hosted or embedded, to compete with LiveContext's paid versions. Read the LICENSE file in the repository for the exact terms.

Cloud vs Community Edition

Both run the same workflow engine. The differences are about how you run and operate it:

Requirements

• Docker Engine 24 or later with Compose v2, or Docker Desktop with Linux containers.
• 4 GB of RAM minimum, 8 GB recommended, and several GB of free disk for images and data.
• A linux/amd64 (x86-64) machine. ARM64 images depend on the release: check that the release you install publishes linux/arm64 images before using Apple Silicon, Raspberry Pi, or other ARM hardware.
• For the npm launcher: Node.js LTS with npm. For the repository install: Git.
• For AI features: your own provider key, or a connected LiveContext Cloud account.

Install

Choose one method. Do not run both on the same machine: they use the same container names and ports.

Option 1: npm launcher (local install)

Run this from the folder where you want to keep the configuration:

npx livecontext@latest

The launcher pulls the images, starts the stack, and prints the app URL (normally http://localhost:3000). From the same folder, manage it with npx livecontext@latest status, logs, down, and update. Configuration lives in ./livecontext: copy livecontext/.env.example to livecontext/.env to change settings. The optional add-ons below need Option 2.

Option 2: Docker Compose (local or server)

1. 1
   Get the code and create your configuration file
   bashCopy

   git clone https://github.com/livecontext-ai/livecontext-ce.git
   cd livecontext-ce
   cp docker/.env.ce.example .env

2. 2
   Edit .env before the first start
   On a server, set your own DB_PASSWORD, MINIO_ROOT_USER, and MINIO_ROOT_PASSWORD. Leave the encryption settings empty: the first start generates the keys and keeps them. Do not change database credentials or encryption keys on an existing install without a backup and a migration plan.
3. 3
   Start the stack
   bashCopy

   docker compose up -d
   docker compose ps

   The first start downloads several GB and prepares the database. Wait until livecontext is healthy, then open http://localhost:3000 (or the port set in FRONTEND_PORT).
4. 4
   Create the first account
   The first person to register becomes the install's administrator and goes through the setup wizard.

The stack runs PostgreSQL, Redis, MinIO (S3-compatible file storage, plus a one-time job that creates its bucket), the tools bridge, the LiveContext backend, and the web app. Code execution runs inside the backend; no separate sandbox service is needed.

Running it on a server, NAS, or VPS

The browser must reach two ports: the web app (FRONTEND_PORT, 3000 by default) and the backend (BACKEND_PORT, 8080 by default). Tell the install its public addresses in .env, without a trailing slash, so that email links and OAuth callbacks point at the server rather than at localhost:

PUBLIC_BASE_URL=http://192.168.1.50:3000
GATEWAY_PUBLIC_URL=http://192.168.1.50:8080

For internet access, use HTTPS with a reverse proxy (Caddy, Traefik, nginx). A simple setup uses two hostnames: one proxied to port 3000, one to port 8080 with WebSocket upgrades, for example PUBLIC_BASE_URL=https://app.example.com and GATEWAY_PUBLIC_URL=https://api.example.com. Then run docker compose up -d again. Register <GATEWAY_PUBLIC_URL>/api/credentials/oauth2/callback as the redirect URL with each integration provider whose account you connect through OAuth.

Configuration reference

All settings go in the .env file at the repository root. Compose reads it on every command. Main variables (names and purpose; the example file has the defaults):

The backend reads these at startup: run docker compose up -d after changing them.

Email (SMTP)

Nothing is required to run, but without a working relay every email is lost, including the password reset link, which is the only way back in for a locked-out administrator. Set MAIL_HOST and MAIL_PORT (587 on a real relay), set both MAIL_USERNAME and MAIL_PASSWORD or neither, and use a MAIL_FROM address your relay accepts. If your relay uses a certificate from a private certificate authority, mount that CA (see the next section) instead of turning TLS off. CE never emails workspace invitations: it uses copyable invite links instead.

Behind a TLS-intercepting proxy

If a corporate proxy or antivirus intercepts TLS, the setup wizard detects it during the cloud connection and offers a one-click way to trust that proxy's certificate. To make it permanent, put the proxy's root CA (PEM) in a folder, mount it as ./extra-ca:/app/extra-ca:ro on the livecontext service, and set NODE_EXTRA_CA_CERTS to that file on the bridge service.

Optional add-ons

Both are off by default, need extra memory and disk, and require the repository install. Put the settings in .env so every start, update, and stop keeps them.

To enable both, use one combined value, COMPOSE_PROFILES=renderer,browser-agent, together with both settings. Then run docker compose up -d.

First-run setup wizard

The first administrator goes through a five-step wizard before reaching the app. Other users are sent straight to chat.

1. 1
   Cloud connection (recommended)
   Connect a LiveContext Cloud account, or skip. Linking unlocks cloud-hosted models, the marketplace, community skills, and fresh catalogs (see below). Skipping keeps the install fully self-contained on your own keys.
2. 2
   AI providers
   Paste API keys for the providers you want: Anthropic, OpenAI, Google, Mistral, DeepSeek, xAI, Perplexity, Z.AI, Qwen, Moonshot, or MiniMax.
3. 3
   CLI providers
   Set up the coding-agent CLIs (Claude Code, Codex, Gemini CLI, Mistral Vibe) that run through the bridge. Verify checks that the CLI is installed and signed in, and then makes it available to administrators right away.
4. 4
   Platform credentials
   Configure credentials for the integrations you plan to use (for example Gmail or Slack).
5. 5
   Done
   The install is marked as set up, once, on the server. Refreshing or changing browser does not bring the wizard back.

Models on a self-hosted install

See Models & providers for reasoning effort, the admin model catalog, and model categories, which work the same on CE.

Linking to a cloud account (optional)

CE runs fully on its own. An administrator can link it to a LiveContext Cloud account in the wizard or later in Settings > Cloud. The Connection tab has Connect to Cloud and Disconnect; the Bundles tab shows the sync status of the Model catalog, the Integrations catalog, and Skills. Linking unlocks:

• Cloud-hosted models, billed to the cloud account instead of your own keys.
• The marketplace: browsing, installing, and publishing Applications.
• Community and global skills shared by the platform.
• Model and skill updates between releases (see the next section).

Any cloud plan can link an install, the Free plan included. The cloud account must first finish its setup (email verification code and profile): Connect to Cloudtakes you through it before it returns to your install. What runs on the cloud's own keys needs a paid plan on the cloud account: cloud-hosted models, integrations through the cloud's credentials, and web search through the cloud. Without one the install stays linked, keeps the marketplace, skills, and bundle updates, and uses its own keys.

Once linked, two switches decide what runs through the cloud:

When either switch is on Cloud, the cloud account's plan also governs the install (see Plans & billing). If the cloud is unreachable, the install keeps running; only the cloud-dependent features pause.

Keeping models, integrations, and skills fresh

Catalogs arrive as signed bundles. Each bundle is checked against a trusted signing key before it is applied, and a bundle never overwrites your own edits, custom models, or custom APIs.

Updating

CE never updates itself. Settings > Information shows the running version, edition, commit, and build date (also reachable from About in the user menu). When a newer release exists, the card shows Update available (or Security update for a security fix) with a How to update button and the release notes.

1. 1
   Back up first
   Back up your data, keys, and configuration (see Backups).
2. 2
   Run the update from your cloned folder
   bashCopy

   git pull
   docker compose pull
   docker compose up -d

   Run git pullfirst: the Compose file pins the release's image version, so pulling images without updating the repository gets the same version again. Your data is kept, and database migrations run automatically on startup. With the npm launcher, run npx livecontext@latest update instead.

After an update, a one-time What's new panel describes the newest change. It ships inside the image and makes no network request.

Signing in and adding people

CE uses built-in email and password sign-in. The first person to register becomes the administrator. Once the setup wizard is completed, public registration closes. An administrator then adds people in one of two ways:

• Invite link: invite by email, then share the copyable link. The person registers through it and joins with the invited role, even while registration is closed.
• Reopen registration: let anyone create an account without an invitation.

See Organizations & roles for workspaces and roles.

What CE includes and leaves out

Backups

Your data lives in Docker volumes, not only in the cloned folder. A database-only backup without the keys and the file storage is not a complete recovery plan. Back up all of these together, from the same stopped snapshot:

The actual volume names carry a project prefix (livecontext-ce for the repository install, livecontext for the npm launcher): check them with docker volume ls. Also keep .env, the Compose file, any overrides, and the catalog-seeds folder. Stop the stack with docker compose stop before exporting the volumes, and restrict access to the backup: it contains secrets.

Test a restore on a separate machine: same project name, same image versions, then check sign-in, a saved credential, and a stored file.

Troubleshooting

Start with docker compose ps and docker compose logs --tail=100 livecontext frontend from the cloned folder. None of the fixes below needs docker compose down -v.

Related pages