Configuration

The default Docker Compose stack needs no configuration and stays on loopback. Use compose.env only for deployment topology and bootstrap secrets, then use Setup Server for sign-in, provider apps, and deployment options.

Compose environmentCopy Anchor Link

Copy the template only when you need overrides:

cp compose.env.example compose.env

Include it in every Compose command:

docker compose --env-file compose.env up -d

compose.env is gitignored. Keep it out of source control and unapproved backups.

Image versionsCopy Anchor Link

For reproducible deployments, pin an AgentConnect release:

AGENTCONNECT_VERSION=vX.Y.Z

Published application and migration images currently target linux/amd64.

Local portsCopy Anchor Link

AGENTCONNECT_BIND_ADDRESS defaults to 127.0.0.1 for Web, Control Plane, and Relay. PostgreSQL, the connector gateway, Setup Server, and the local Logto overlay remain loopback-only in the supplied Compose files.

Network and public URLsCopy Anchor Link

Containers use Docker service names internally. Browsers, daemons, provider callbacks, and links use these public origins:

Do not add a trailing slash.

For a remote daemon or network deployment, replace these defaults with reachable origins. Use HTTPS for browser and callback origins, and wss:// for the daemon-facing Relay URL. A reverse proxy must preserve WebSocket upgrades for both Control Plane and Relay connections.

Set the final public URLs before creating GitHub or Slack Apps. Setup derives their callback manifests from these values. If the URLs change later, recreate Setup Server with the same environment and Compose overrides before updating the provider Apps. For the base stack:

docker compose --env-file compose.env up -d --force-recreate setup-server

After updating the provider Apps, recreate the runtime services with the same environment and Compose overrides:

docker compose --env-file compose.env up -d --force-recreate control-plane relay web

Do not publish a no-auth stack or its default secrets. Compose is a single-host topology, not an HA deployment.

Setup ServerCopy Anchor Link

Setup Server provides the browser-based AgentConnect Setup surface at http://localhost:8091. It is included in the base stack and always binds to loopback.

Use it to:

• bootstrap Logto sign-in;
• create, adopt, check, or clear provider Apps;
• store provider credentials without returning saved secret values; and
• enable or disable the preset agentconnect agent.

Saved changes are loaded when services start. Apply them with:

docker compose restart control-plane relay web

If Compose runs on another host, forward Setup Server instead of exposing it publicly:

ssh -L 8091:127.0.0.1:8091 operator@host.example

Then open http://localhost:8091 locally.

For the initial administrator and Logto Cloud or external Logto OSS setup, continue with Sign-in.

Preset agentCopy Anchor Link

New organizations receive a built-in agentconnect agent by default. In Setup, open Options, clear Enable preset Agents, and save. This prevents future provisioning and backfills; it does not delete agents that already exist.

Database and bootstrap secretsCopy Anchor Link

PostgreSQL 18 stores data in the agentconnect_postgres-data volume. docker compose down preserves it; docker compose down --volumes deletes it.

Replace these defaults before any network exposure:

Generate a separate value for each secret:

openssl rand -hex 32

Rotating AGENTCONNECT_API_KEY_PEPPER invalidates existing daemon and personal API keys. Back up PostgreSQL before non-throwaway use.

Secret storageCopy Anchor Link

Secrets shown as write-only in AgentConnect or Setup still need encryption at rest. The default SECRET_CIPHER=none stores them as plaintext in PostgreSQL. Use HashiCorp Vault Transit for a production or network-exposed deployment.

Create a Transit key and a policy that can encrypt and decrypt with it:

vault secrets enable transit
vault write -f transit/keys/agentconnect-cp

path "transit/encrypt/agentconnect-cp" {
  capabilities = ["update"]
}

path "transit/decrypt/agentconnect-cp" {
  capabilities = ["update"]
}

Pass the Vault settings to both Control Plane and Setup Server so they use the same cipher root:

# compose.vault.yaml
services:
  control-plane:
    environment: &vault
      SECRET_CIPHER: vault-transit
      VAULT_ADDR: ${VAULT_ADDR}
      VAULT_TRANSIT_KEY: ${VAULT_TRANSIT_KEY:-agentconnect-cp}
      VAULT_TRANSIT_MOUNT: ${VAULT_TRANSIT_MOUNT:-transit}
      VAULT_TOKEN: ${VAULT_TOKEN}
  setup-server:
    environment: *vault

Use a policy-scoped token rather than a Vault root token, then recreate both services:

docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
  up -d --force-recreate control-plane setup-server

After taking a database backup, encrypt values that were previously stored as plaintext:

docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
  exec control-plane node dist/secrets/rewrap-cli.js

The command is resumable and can also be rerun after rotating the Transit key. Vault workload identity is supported through VAULT_JWT_ROLE, VAULT_JWT_PATH, and VAULT_AUTH_MOUNT instead of VAULT_TOKEN.

File transfer and the object storeCopy Anchor Link

Console file transfer needs an S3-compatible object store. With one, a person can attach any file to a Playground message, and the console can download workspace files of any size up to the store's limit. Bytes go straight between the browser or daemon and the store on short-lived signed URLs; the Control Plane only signs them and never sees file contents. Without a store, only images can be attached, and workspace downloads go through the Control Plane, up to 8 MiB per file.

Signed URLs must be https://, and browsers and daemons reach the store directly, so the store needs an HTTPS origin they trust.

Bundled store (HTTPS overlay)Copy Anchor Link

The compose.logto.https.yaml overlay, which puts the stack and Logto sign-in behind Caddy HTTPS, also runs a RustFS object store. Caddy serves it on its own HTTPS port, and a one-shot object-store-setup service creates the agentconnect bucket, its lifecycle rules, and a CORS rule for the console origin on every start. Add these to the overlay's .env:

AGENTCONNECT_OBJECT_STORE_HTTPS_PORT=1445
AGENTCONNECT_OBJECT_STORE_ACCESS_KEY=agentconnect-store
AGENTCONNECT_OBJECT_STORE_SECRET_KEY=<random-password>

The overlay refuses to start while any of the three is missing. Use all three Compose files in every command:

docker compose --env-file .env \
  -f compose.yaml -f compose.logto.yaml -f compose.logto.https.yaml \
  up -d

Check the store through Caddy:

curl -k https://<host>:1445/health

Browsers and daemons follow download links to that port, so they must trust the Caddy CA for it as well as for the console. The repository's Caddy HTTPS guide covers the whole overlay, including exporting and trusting the Caddy root certificate.

External bucketCopy Anchor Link

To use your own bucket instead, set AC_FILE_TRANSFER in compose.env to a one-line JSON document:

AC_FILE_TRANSFER='{"version":1,"endpoint":"https://s3.example.com","region":"us-east-1","bucket":"agentconnect","forcePathStyle":true,"credentials":{"source":"static","dir":"/run/secrets","accessKeyIdKey":"file_transfer_access_key_id","secretAccessKeyKey":"file_transfer_secret_access_key"}}'

Mount the key files into the Control Plane with an override:

# compose.file-transfer.yaml
services:
  control-plane:
    secrets:
      - file_transfer_access_key_id
      - file_transfer_secret_access_key
secrets:
  file_transfer_access_key_id:
    file: ./secrets/file-transfer-access-key-id
  file_transfer_secret_access_key:
    file: ./secrets/file-transfer-secret-access-key

docker compose --env-file compose.env -f compose.yaml -f compose.file-transfer.yaml \
  up -d --force-recreate control-plane

The bucket also needs:

• A lifecycle rule that expires objects tagged ac-cache=pending under <prefix>/src/ (or src/ with no prefix) after 2 days. Until it exists, the Control Plane refuses transfers and logs the rule to add. The chart README has the document and the commands for AWS and MinIO.
• A CORS rule admitting the console origin for GET and PUT, with the content-type, x-amz-checksum-sha256, and x-amz-tagging headers.
• Permissions for the key pair: s3:PutObject, s3:PutObjectTagging, and s3:GetObject under <prefix>/src/*/transfer/, and s3:GetLifecycleConfiguration on the bucket.

Private certificate authoritiesCopy Anchor Link

A GitLab or Gitea instance presenting a certificate from a private authority needs that authority's bundle readable at a file path that exists inside each process, including the agent sandbox. Point every runtime at it:

A path that exists only on the host is not enough: an agent runs in a sandbox with its own filesystem view, so the bundle has to be mounted there too and the variables have to survive into the sandbox environment. Set them where the sandbox image and its environment are configured, not only on the host.

Git and code-host API requests from agent sessions leave through the daemon's credential proxy, which verifies the instance with these same authorities, so the daemon process needs them even when its sessions run elsewhere.

The Relay never dials the instance — it only receives webhook deliveries — so it needs no bundle and no outbound access.

Production checklistCopy Anchor Link

• Pin release images.
• Configure OIDC sign-in and an API Resource.
• Replace every default secret and enable encrypted secret storage.
• Set a connector encryption key if you use connectors, and back up its volume.
• Put Web, Control Plane, Relay, and Logto behind HTTPS.
• Give file transfer an HTTPS object store with its lifecycle rule, or leave it off.
• Preserve WebSocket upgrades.
• Back up PostgreSQL and test restores.
• Keep Setup Server, PostgreSQL, and the connector gateway off the public network.