Install Envoy with Docker Compose, generate the server configuration from environment variables, and verify the setup screen.

Installation

Goal

Bring up a local Envoy deployment with Docker Compose: a control plane serving the web UI and API on port 3003, and a separate executor container that runs task subprocesses.

Envoy ships as a single compiled binary per customer build (produced with bun build --compile), packaged into a Docker image together with the web UI assets and any bundled task and job template YAML. The same image runs both the control plane and the executor; the container command decides the role.

Prerequisites

Docker with the Compose plugin
A checkout of the Envoy repository (the Compose file builds the image from the repository root)
Two secrets you generate yourself:
- an encryption key used to encrypt connector configurations at rest
- an executor key shared between the control plane and the executor

Steps

1. Export the required secrets

The Compose file reads ENVOY_ENCRYPTION_KEY and ENVOY_EXECUTOR_KEY from your shell environment (or a .env file next to docker-compose.yaml):

export ENVOY_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export ENVOY_EXECUTOR_KEY="$(openssl rand -hex 32)"

ANTHROPIC_API_KEY is optional; when set, it enables the built-in AI assistant.

2. Start the stack

docker compose up --build -d

This starts two services:

Service	Container	Role
`control-plane`	`envoy-control-plane`	Web UI, REST API, scheduler, state store. Publishes port `3003`.
`executor`	`envoy-executor`	Runs task subprocesses. Registers with the control plane over HTTP using the executor key.

Both containers mount ./data at /app/data (shared files for file-based connectors) and a named volume cp-state at /app/state (server database and generated configuration).

3. Understand the generated configuration

On first start the entrypoint script generates envoy-server.yaml at the path given by ENVOY_CONFIG_PATH (in the default Compose file: /app/state/envoy-server.yaml, on the persistent volume). Generation only happens when the file does not already exist and ENVOY_ENCRYPTION_KEY is set. Selected variables the entrypoint understands:

Variable	Default	Purpose
`ENVOY_PORT`	`3000` (Compose sets `3003`)	Control plane HTTP port
`ENVOY_STORE_TYPE`	`sqlite`	Server state store: `sqlite`, `mssql`, or `postgres`
`ENVOY_DB_PATH`	`/app/envoy-server.db`	SQLite database path (Compose sets `/app/state/envoy-server.db`)
`ENVOY_EXECUTOR_TYPE`	`local`	`http` makes the control plane dispatch runs to remote executors
`ENVOY_CALLBACK_URL`	—	URL executors use to call back to the control plane (required for `http`)
`ENVOY_LOG_STORE`	`file`	Where run logs are stored (Compose sets `db`)
`ENVOY_RETENTION_DAYS`	`30`	Run retention window
`ENVOY_APP_NAME`	`Envoy`	Branding: application name shown in the UI
`ENVOY_AUTH_TOTP_REQUIRED`	—	Set `false` to disable mandatory two-factor authentication

Once the file exists, edits to it win over environment variables — the entrypoint never regenerates or overwrites it. For the full schema, including MSSQL/PostgreSQL state stores, OAuth providers, secrets backends, and Litestream replication of the SQLite store, see Server configuration.

Verify it worked

Open http://localhost:3003. A fresh deployment redirects to the /setup screen, which asks you to create the administrator account. Continue with First-time setup.

To check the containers instead:

docker compose ps
docker compose logs control-plane

The control plane log ends with either Starting Envoy directly... or Starting Envoy with Litestream replication... from the entrypoint, followed by server output.

Other topologies

The repository also contains Compose files for remote single-host deployments behind a TLS proxy and for an Azure-style stack with MSSQL and Azure Key Vault. Those are production topologies, not quickstart material — see Docker deployment and Azure deployment. Per-customer images (binary name, branding, bundled catalog) are produced by the build pipeline described in Customer builds and catalog.

First-time setup — create the admin account and sign in
Server configuration — every envoy-server.yaml key
Control plane and executors — how the two roles cooperate