Environment variables

Last published : Nov 09, 2026
The environment variables Knowledge Worker Agent reads. Set them where it starts, for example in the workspace image. Changes apply the next time it starts.
On/off variables accept 1, true, yes, or on for on, and 0, false, no, or off for off, in any case. Durations accept a number of seconds, such as 120, or a value such as 90s, 30m, or 720h. A variable set to a blank value counts as not set.
Some defaults depend on whether the workspace has moved its files into one folder. Where they differ, the table gives both. For more information, see Move files into one folder.
Related information
Reference

Server

Variable Default Description
KWA_HOST localhost Address the server listens on. localhost listens on 127.0.0.1 and ::1, where the platform connects. Don't set 0.0.0.0: anyone who can reach the server can use it as its owner.
KWA_PORT 8765 Port the server listens on.
KWA_HOME ~/Knowledge_Worker_Agent The folder that holds everything Knowledge Worker Agent keeps, once the workspace has moved its files into one folder. Before the move, the earlier locations are used.
KWA_DB_BACKUP On Save a snapshot of the database at startup. Off turns snapshots off.
KWA_LOG_FILE Before the move: /tmp/chat-logs/chat.log. After: .system/logs/knowledge-worker-agent.log in KWA_HOME File that receives a copy of the log. off, none, or - turns the copy off.
KWA_LOG_MAX_BYTES 52428800 (50 MiB) Size at which the log file is rotated. 0 turns rotation off.
KWA_MIGRATE Off Move the workspace's files into one folder at startup. dry-run reports what would move and changes nothing. on moves the files. undo moves them back.

opencode

opencode is the agent that Knowledge Worker Agent runs for each chat. For the memory it uses in each mode, see Workspace requirements.
Variable Default Description
KWA_OPENCODE_BIN Found on PATH Path to the opencode binary.
KWA_OPENCODE_AUTO_UPDATE On At startup, install the opencode version this release is pinned to, replacing any other version. Off keeps the binary it finds, and installs one only if none works.
KWA_OPENCODE_INSTALL_DIR ~/.opencode/bin Where opencode is installed.
KWA_OPENCODE_STARTUP_TIMEOUT 90s How long to wait for a chat's first output before treating it as stuck. 0 or less turns the limit off.
KWA_OPENCODE_MCP_CONFIG_PATH opencode's opencode.json File where connectors are saved.
OPENCODE_CONFIG_DIR Before the move: opencode-platform, next to the opencode configuration folder. After: .system/config in KWA_HOME Folder that central configuration writes to. This is opencode's own setting, so its name doesn't change.
XDG_CONFIG_HOME ~/.config Base of the opencode configuration folder, opencode.

Central configuration

Variable Default Description
KWA_PROJECT_ID Not set The workspace's project ID in assignment.jsonc. Required for central configuration.
KWA_CONFIG_REPO_URL Not set The configuration repository: a Git URL, or the path of a folder. Required for central configuration.
KWA_CENTRAL_CONFIG Off Put the workspace under central management: assigned model providers replace the built-in ones, and the built-in connector catalogue isn't installed.
For how to use them, see Set up central configuration.

Model providers

Variable Default Description
GOOGLE_VERTEX_PROJECT None Google Cloud project for Google Vertex AI. Required to use Vertex AI. ANTHROPIC_VERTEX_PROJECT_ID is read when this isn't set. Without either, the Vertex AI check reports "no Vertex project is configured". When GOOGLE_CLOUD_PROJECT isn't set, Knowledge Worker Agent sets it to this project, which keeps each Vertex AI request from waiting on a Google Cloud lookup that can't answer outside Google Cloud.
GOOGLE_VERTEX_LOCATION global Google Cloud location for Google Vertex AI. CLOUD_ML_REGION is read when this isn't set.
KWA_GCLOUD_BIN gcloud on PATH The Google Cloud CLI, used for Google Vertex AI sign-in.
KWA_GITHUB_CLIENT_ID opencode's client ID GitHub OAuth client ID for GitHub Copilot sign-in.

Connectors

Variable Default Description
COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN Not set A GitHub token for the GitHub connector, used when no token is saved under Accounts.
KWA_OBSIDIAN_AUTO_INSTALL On Install the Obsidian connector at startup when it's missing.
KWA_OBSIDIAN_VAULT Before the move: ~/ObsidianVault. After: ObsidianVault in KWA_HOME The Obsidian vault the connector reads and writes.

Chats and features

Variable Default Description
KWA_AUTO_TITLE On Name new chats automatically.
KWA_SCHEDULED_TASKS On Run scheduled tasks.
KWA_SCHEDULED_TASKS_INTERVAL 1m How often to check for scheduled tasks that are due. 0 turns the checks off.
KWA_PROJECT_AUTO_SYNC On Pull new commits into projects backed by a repository.
KWA_PROJECT_AUTO_SYNC_INTERVAL 5m How often to check those projects. 0 turns the checks off.
KWA_WORKSPACE_HEARTBEAT On Keep the workspace from going idle while the assistant works. For more information, see Workspace heartbeat.

Workspace hygiene

Variable Default Description
KWA_HYGIENE_ENABLED On Offer idle chats for review, and remove empty chats.
KWA_HYGIENE_REVIEW_AFTER 720h (30 days) How long a chat is unopened before it's offered for review.
KWA_HYGIENE_SNOOZE 720h (30 days) How long Keep for now keeps a chat out of the review.
KWA_HYGIENE_EMPTY_AFTER 24h How long an empty chat is kept before it's removed.

Dictation

Variable Default Description
KWA_VOICE On Offer dictation. Any value that isn't recognized also turns it off. Dictation is only offered where the engine and model are installed.
KWA_VOICE_BIN /usr/lib/knowledge-worker-agent/whisper/whisper-server The speech engine. Older images have it under /usr/lib/sds-chat/whisper/, where it's still found.
KWA_VOICE_MODEL /usr/share/knowledge-worker-agent/whisper/ggml-small.en-q8_0.bin The speech model. Older images have it under /usr/share/sds-chat/whisper/, where it's still found.
For the resources dictation uses, see Dictation in Workspace requirements.

Sharing

Variable Default Description
KWA_GUEST_PORT 8766 Port for shared chats, on 127.0.0.1 only. off, false, no, or 0 turns sharing off. If the port is taken, sharing is off.
KWA_ARTIFACT_PORTS 8770-8799 Ports for shared files, one per file, on 127.0.0.1 only: a port, or a range of up to 1,000. off, false, no, or 0 turns sharing files off. Files already shared stop opening until it's back on.
KWA_PREVIEW_PORT 8769 Port on 127.0.0.1 where HTML files in the Files panel run their scripts. off, false, no, or 0 turns their scripts off.

Set by SecurSpaces

The platform sets these. Don't set them yourself.
Variable Used for
STRONG_NETWORK_WORKSPACE_ID Links to the workspace, such as Open folder in VS Code, and shared chat links.
STRONG_NETWORK_WORKSPACE_APPS_DOMAIN The same links.
STRONG_NETWORK_DOMAIN The link to the platform's Git integrations page.
OWNER_FULL_NAME, OWNER_EMAIL The workspace owner's name and email. The assistant knows who it works for, and the new chat screen greets the owner by name.
KWA_ORGANIZATION_ID, KWA_REGION The workspace's organization and region.

For development only

Variable Description
KWA_GUEST_ORIGIN The origin that shared chats must come from, instead of the one derived from the workspace.
KWA_SIDECAR_SOCKET Another socket for the workspace's app routes, such as a test double.

Earlier names

Every setting that starts with KWA_ had another name in earlier releases. The earlier names still work for now, and a later release stops reading them.
  • When both names are set, the KWA_ name wins.
  • At every start, the log lists each earlier name in use, for example: ⚠ Settings with old names, which a later release stops reading: COPILOT_WEB_PORT (now KWA_PORT). SecurSpaces still sets some earlier names, so this warning is expected for now.
Earlier name Name now
COPILOT_WEB_HOST, COPILOT_WEB_PORT KWA_HOST, KWA_PORT
COPILOT_DB_BACKUP KWA_DB_BACKUP
COPILOT_LOG_FILE, COPILOT_LOG_MAX_BYTES KWA_LOG_FILE, KWA_LOG_MAX_BYTES
OPENCODE_BIN KWA_OPENCODE_BIN
OPENCODE_AUTO_UPDATE, then COPILOT_AUTO_UPDATE KWA_OPENCODE_AUTO_UPDATE
OPENCODE_INSTALL_DIR KWA_OPENCODE_INSTALL_DIR
OPENCODE_STARTUP_TIMEOUT KWA_OPENCODE_STARTUP_TIMEOUT
OPENCODE_MCP_CONFIG_PATH KWA_OPENCODE_MCP_CONFIG_PATH
OPENCODE_GITHUB_CLIENT_ID, then COPILOT_GITHUB_CLIENT_ID KWA_GITHUB_CLIENT_ID
GCLOUD_BIN KWA_GCLOUD_BIN
SDS_PROJECT_ID, SDS_CONFIG_REPO_URL, SDS_CENTRAL_CONFIG KWA_PROJECT_ID, KWA_CONFIG_REPO_URL, KWA_CENTRAL_CONFIG
SDS_ORGANIZATION_ID, SDS_REGION KWA_ORGANIZATION_ID, KWA_REGION
COPILOT_OBSIDIAN_AUTO_INSTALL, COPILOT_OBSIDIAN_VAULT KWA_OBSIDIAN_AUTO_INSTALL, KWA_OBSIDIAN_VAULT
CHAT_AUTO_TITLE KWA_AUTO_TITLE
SCHEDULED_TASKS, SCHEDULED_TASKS_INTERVAL KWA_SCHEDULED_TASKS, KWA_SCHEDULED_TASKS_INTERVAL
PROJECT_AUTO_SYNC, PROJECT_AUTO_SYNC_INTERVAL KWA_PROJECT_AUTO_SYNC, KWA_PROJECT_AUTO_SYNC_INTERVAL
SDS_WORKSPACE_HEARTBEAT KWA_WORKSPACE_HEARTBEAT
SDS_HYGIENE_ENABLED, SDS_HYGIENE_REVIEW_AFTER, SDS_HYGIENE_SNOOZE, SDS_HYGIENE_EMPTY_AFTER KWA_HYGIENE_ENABLED, KWA_HYGIENE_REVIEW_AFTER, KWA_HYGIENE_SNOOZE, KWA_HYGIENE_EMPTY_AFTER
SDS_VOICE, SDS_VOICE_BIN, SDS_VOICE_MODEL KWA_VOICE, KWA_VOICE_BIN, KWA_VOICE_MODEL
SDS_CHAT_GUEST_PORT, SDS_CHAT_GUEST_ORIGIN KWA_GUEST_PORT, KWA_GUEST_ORIGIN
SDS_SIDECAR_SOCKET KWA_SIDECAR_SOCKET

Legacy settings

These settings are replaced by KWA_HOME, and have no new name. They're still read for now.
Setting Was used for
COPILOT_WORKSPACE Base folder for chats, projects, and scheduled tasks.
COPILOT_DB_PATH Database file for chats and settings.
SDS_CONFIG_CACHE_DIR Where the configuration repository is cloned and cached.
COPILOT_OBSIDIAN_INSTALL_DIR Where the Obsidian connector is installed.
COPILOT_HOME, COPILOT_GITHUB_PAT_PATH Folder and file for the GitHub token saved under Accounts.
  • Before the move into one folder, they say where the files are, as before. The release image sets COPILOT_WORKSPACE and COPILOT_DB_PATH for this reason.
  • A value equal to the earlier default, such as COPILOT_WORKSPACE=/home/developer, is ignored after the move.
  • Any other value is kept. That location isn't moved, and the dry run says so.