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.

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.

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.
• Preserve WebSocket upgrades.
• Back up PostgreSQL and test restores.
• Keep Setup Server, PostgreSQL, and the connector gateway off the public network.