Configuration

Generated from packages/envoy/cmd/dispatch/settings.go by docs/site/generators/dispatch-config.ts. Edit the source, not this page.

Dispatch’s server, envoy-dispatch, and its subcommands take the 40 Dispatch settings below from the environment. envoy-dispatch settings prints the same table from the binary you run.

The libraries Dispatch is built on read a few more variables for themselves, outside this table: HOME (where the data directory, ~/.local/share/dispatch, is, and the user envoy.json when XDG_CONFIG_HOME is unset or empty), libpq’s PG* variables (connection parameters DATABASE_URL leaves out), HTTP_PROXY, HTTPS_PROXY and NO_PROXY (outbound HTTP), SSL_CERT_FILE and SSL_CERT_DIR (the certificates Dispatch trusts), and the Go runtime’s GO* variables and TZ.

A setting with a file form can name a file that holds its value instead. When Dispatch reads that setting, the file’s trimmed contents win over the variable, and a file that cannot be read, or holds nothing, refuses startup.

envoy.json is read from two files: the user file, legion/envoy.json under XDG_CONFIG_HOME (~/.config when that is unset or empty; a path that is not absolute refuses startup), and the checkout’s file, .envoy/envoy.json in the directory Dispatch starts in, which may hold only a dispatch section: an envoy section there refuses startup, naming it and the user file it belongs in (the agents’ clients ignore it with a notice instead), and a .envoy that is a plain file counts as no checkout file. Where both set a dispatch key, the checkout’s file wins, and DISPATCH_SERVER_URL and NATS_URLS win over both. Dispatch reads envoy.natsUrls whatever envoy.enabled says, since enabled switches a session’s Envoy, not the server’s. The OpenCode-era files are not read. A user file still at ~/.config/opencode/envoy.json, with none at ~/.config/legion/envoy.json and XDG_CONFIG_HOME unset, empty or ~/.config, refuses startup, naming both paths and the move, whatever DISPATCH_SERVER_URL and NATS_URLS say; a checkout’s .opencode/envoy.json, while the checkout has no .envoy/envoy.json, is one WARN at start naming the rename. A file that carries a top-level natsUrls is refused, naming envoy.natsUrls; a JSON null at the top level, as a section or as any key’s value is refused, naming the key; and JSON that does not parse is refused naming the file, the line and the column, never the text it stopped at. These refusals stop every start, DISPATCH_NATS_DISABLED set or not.

DATABASE_URL

Postgres connection string. The server migrates the database before serving; census, backfill-block-ids, backfill-anchor-blocks, backfill-files and rebuild-refs read it too. A pool_max_conns parameter is refused.

• Required: Yes

DISPATCH_FILE_STORE_BUCKET

S3 bucket uploaded files (images, attachments) are stored in, keyed by their SHA-256; the AWS SDK finds its region and credentials itself (AWS_*, the shared config files, the task role). backfill-files reads it too. Unset, every upload’s bytes stay in Postgres, as before the bucket existed.

• Required: No

DISPATCH_AGENT_TOKEN

Shared bearer token an agent may authenticate with: one value, or several separated by whitespace while it rotates, the first the current one, all accepted. Personal tokens minted in Settings are the usual agent credential.

• Required: Yes

DISPATCH_IDENTITY

How a browser request names its person: cookie (Google sign-in, through a Cognito sign-in pool or with Google directly, then a signed session cookie) or header:<Header-Name> (tests and local harnesses only: the header names the person by email).

• Required: No
• When unset: cookie

DISPATCH_SIGNIN_ISSUER

OpenID Connect issuer people sign in through: a Cognito sign-in pool, with DISPATCH_SIGNIN_GROUP, or Google itself (https://accounts.google.com), with DISPATCH_SIGNIN_DOMAIN; Dispatch reads its endpoints from the issuer’s discovery document at startup. Google sign-in takes the issuer, client ID, client secret and exactly one of the group or the domain, or none of them, and header identity and dev sign-in refuse every one of them.

• Required: When DISPATCH_IDENTITY is cookie and DISPATCH_DEV_SIGNIN is unset

DISPATCH_SIGNIN_CLIENT_ID

Client ID of Dispatch’s confidential client at the issuer: the sign-in pool’s app client, or a Google OAuth web client.

• Required: When DISPATCH_IDENTITY is cookie and DISPATCH_DEV_SIGNIN is unset

DISPATCH_SIGNIN_CLIENT_SECRET

Client secret of that client.

• Required: When DISPATCH_IDENTITY is cookie and DISPATCH_DEV_SIGNIN is unset

DISPATCH_SIGNIN_GROUP

The pool group (cognito:groups) a person must be in to sign in through a Cognito sign-in pool; refused with Google’s issuer. Dispatch confirms the membership at least hourly, and a person no longer in it loses every browser session.

• Required: When DISPATCH_IDENTITY is cookie, DISPATCH_DEV_SIGNIN is unset and DISPATCH_SIGNIN_DOMAIN is unset

DISPATCH_SIGNIN_DOMAIN

The Google Workspace domain whose people may sign in with Google, a lowercase domain name such as example.com; it needs DISPATCH_SIGNIN_ISSUER https://accounts.google.com, and a Google web client whose OAuth consent screen is Internal. Name the organization’s primary domain, which Google puts in hd for every account of the organization: a secondary domain admits nobody, and a member whose address is on a secondary domain signs in under that address. A person signs in when their Google ID token’s hd is this domain and Google has verified their email; Dispatch confirms that at least hourly, and a person no longer in it loses every browser session.

• Required: When DISPATCH_IDENTITY is cookie, DISPATCH_DEV_SIGNIN is unset and DISPATCH_SIGNIN_GROUP is unset

DISPATCH_IDENTITY_HEADER_TRUSTED

Set to 1 to acknowledge header identity, which is for tests and local harnesses only; without it a header-identity server refuses to start.

• Required: When DISPATCH_IDENTITY is a header

DISPATCH_LISTEN_HOST

Host the server binds; an IPv6 host may be written with or without brackets.

• Required: No
• When unset: Every interface

DISPATCH_PORT

Port the server binds.

• Required: No
• When unset: 8766

XDG_CONFIG_HOME

Directory whose legion/envoy.json is the user envoy.json, which DISPATCH_SERVER_URL and NATS_URLS fall back to; set but empty, it is ~/.config too, and a path that is not absolute refuses startup.

• Required: No
• When unset: ~/.config

DISPATCH_SERVER_URL

The origin people open in a browser and the sign-in callback origin (<origin>/auth/callback): an absolute http(s) URL with no path. Set, it overrides envoy.json; set but empty, it refuses startup.

• Required: No
• When unset: dispatch.serverUrl from envoy.json

NATS_URLS

Comma-separated NATS server URLs. Set, it overrides envoy.json; set but empty, it refuses startup.

• Required: No
• When unset: envoy.natsUrls from envoy.json

ENVOY_ALLOW_REMOTE_NATS

Set to 1 to let Dispatch reach a NATS server that is not on this machine; without it Dispatch refuses one, and every deployment sets it.

• Required: No

NATS_NKEY_SEED

Nkey seed of the NATS user Dispatch connects as; unset, it connects with no credential. A set but unusable seed refuses startup.

• Required: No
• File form: NATS_NKEY_SEED_FILE

ENVOY_NATS_SOCKS5_PROXY

SOCKS5 proxy, as host:port, that every NATS connection Dispatch makes goes through, each server’s host name handed to the proxy unresolved; unset, Dispatch dials NATS directly. A set proxy needs ENVOY_ALLOW_REMOTE_NATS=1, since the proxy chooses the server. A deployment that reaches NATS through a tailnet sidecar’s SOCKS5 server (tailscaled’s TS_SOCKS5_SERVER) sets it.

• Required: No

DISPATCH_NATS_DISABLED

Set to 1 to run without NATS: no event is published, and the agent conversation relay and webhook redelivery are off.

• Required: No

ENVOY_URL

Base URL of the Envoy listener Dispatch delivers mentions and messages through and reads live sessions from.

• Required: No
• When unset: http://127.0.0.1:9020

ENVOY_TOKEN

Bearer token Dispatch sends on every Envoy listener call; unset, it sends none.

• Required: No

DISPATCH_REPO_PROJECTS

Comma-separated owner/repo=KEY mappings seeded at startup; a mapping saved in the dashboard wins.

• Required: No

DISPATCH_DEFAULT_PROJECT

Project an external issue from an unmapped repository is created in; it must already exist.

• Required: No

DISPATCH_APP_CLIENT_ID

GitHub App client ID, which names the App in the JWT its private key signs. Set, the App comes from the DISPATCH_APP_* variables instead of ~/.local/share/dispatch/app.json.

• Required: No

DISPATCH_APP_PEM_B64

Base64-encoded GitHub App private key, which signs every App call: the web app’s GitHub reads, the architecture import and webhook redelivery are off without one.

• Required: No

DISPATCH_APP_ID

The GitHub App’s numeric ID.

• Required: No

DISPATCH_APP_SLUG

The GitHub App’s slug.

• Required: No

DISPATCH_APP_NAME

The GitHub App’s display name.

• Required: No

DISPATCH_GITHUB_API_BASE

GitHub API origin the App calls; tests point it at a fake. redeliver-webhooks reads it too.

• Required: No
• When unset: https://api.github.com

DISPATCH_SIGNING_KEY

HMAC key that signs session cookies and seals the refresh tokens Dispatch stores; changing it signs everyone out.

• Required: No
• When unset: A key kept in ~/.local/share/dispatch/signing-key, created on first start

DISPATCH_INSECURE_COOKIE

Any value drops the Secure attribute from Dispatch’s cookies, for browsers that reach it over plain http.

• Required: No

DISPATCH_OIDC_ISSUER

OIDC issuer whose projected service-account tokens authenticate as agents.

• Required: When DISPATCH_OIDC_AUDIENCE is set

DISPATCH_OIDC_AUDIENCE

Audience those service-account tokens must carry.

• Required: When DISPATCH_OIDC_ISSUER is set

DISPATCH_AGENT_SECRETS_URL

Base URL of the secrets broker’s API, an absolute http(s) URL with no path; set, the credential-request pages are on.

• Required: No

DISPATCH_AGENT_SECRETS_TOKEN

Bearer token Dispatch sends the secrets broker.

• Required: When DISPATCH_AGENT_SECRETS_URL is set
• File form: DISPATCH_AGENT_SECRETS_TOKEN_FILE

DISPATCH_WEB_DIST

Directory of the built dashboard the server serves.

• Required: No
• When unset: The packages/dispatch/web/dist directory found from the binary’s location

DISPATCH_ASSET_STORE_BUCKET

Bucket holding immutable assets from prior dashboard builds. Unset, Dispatch serves only its local dashboard files.

• Required: No

DISPATCH_DEV_SIGNIN

Set to 1 on a loopback-only local server to sign anyone in by email at /auth/_dev/signin without the sign-in issuer; refused alongside any DISPATCH_SIGNIN_* setting, DISPATCH_SIGNIN_DOMAIN included.

• Required: No

DISPATCH_TEST_HOOKS

Set to 1 to mount the end-to-end tests’ hook routes; never in a real deployment.

• Required: No

DISPATCH_TEST_SETTLE_DELAY

Document settlement delay for an end-to-end test process; a positive Go duration. Set only with DISPATCH_TEST_HOOKS=1.

• Required: No
• When unset: 2s