Configuration
Environment variables and configuration options for DorkOS
Configuration
DorkOS works out of the box. Most people never open this page again after their first session: no ports to pick, no files to edit, nothing to tune. This page exists for the day you need to change one specific thing, a port conflict, a tunnel so you can check on an agent from your phone, a different AI provider.
The one setting worth knowing on day one is ANTHROPIC_API_KEY, and the Installation guide already walks you through setting it. Everything below is reference: skip to the section you need and ignore the rest.
DorkOS reads settings from three places, in this order: CLI flags (what you type when you start DorkOS), environment variables (settings you export in your terminal, or put in a .env file next to where you run DorkOS), and the config file at ~/.dork/config.json (DorkOS writes this itself; you rarely need to touch it by hand). If a setting appears in more than one place, the first one found wins. For example, to try a different port for one run without changing anything permanent:
DORKOS_PORT=5000 dorkosSetting order: CLI flags win first, then environment variables, then ~/.dork/config.json, then
DorkOS's built-in defaults.
Required
Prop
Type
Optional
Prop
Type
Reference
Everything below is deep reference. Most people never touch it, it's here for the day you need it.
Tunnel Configuration
DorkOS supports ngrok tunnels (a service that gives your local machine a public URL) for remote access from any device. See the Tunnel Setup guide for full details.
Prop
Type
Always set TUNNEL_AUTH when exposing DorkOS publicly via a tunnel. Without it, anyone with the
tunnel URL can access your sessions.
Relay Configuration
Relay is the messaging layer that lets agents reach you on Telegram, notify each other, and connect to external channels. See the Relay Messaging guide for setup details.
Prop
Type
Tasks Configuration
Tasks runs agent jobs on a schedule (like "every night at 2am"), on their own, without you keeping a terminal open. See the Task Scheduler guide for setup details.
Prop
Type
A2A Gateway
The A2A gateway exposes your DorkOS agents to external A2A-compatible clients (other agent frameworks, orchestrators, or tools that speak Google's Agent-to-Agent protocol). Requires Relay to be enabled.
Prop
Type
Mesh
Mesh is always on. It scans your projects for agent-capable directories and builds a discoverable registry without any additional configuration. See the Agent Discovery guide for details on registration and access control.
Extensions
Extensions add UI, commands, and behavior to DorkOS. Core extensions ship with DorkOS and appear in Settings → Extensions under a "Core extensions" section, each with an enable or disable toggle. Extensions you install yourself appear under "Installed extensions". Toggling in the UI is all most people need. The underlying state lives in ~/.dork/config.json under the extensions key.
DorkOS records only your deviations from each extension's default state, across two lists:
Prop
Type
An extension absent from both lists uses its default: ships-on extensions stay on, ships-off extensions stay off. To turn a ships-on extension off, add its id to disabled; to turn a ships-off extension on, add its id to enabled.
Adding a ships-on extension's id to enabled does nothing, since it's already on. To disable it,
add the id to disabled instead.
Runtimes
DorkOS runs three agent runtimes: Claude Code (the default), Codex, and OpenCode. The runtimes block in ~/.dork/config.json controls which ones are available and how their binaries are found. Running multiple runtimes side by side is shipped, but still getting real-world mileage, so treat multi-runtime setups as an area to watch rather than a fully settled feature. See the Runtimes guide for connecting and choosing runtimes.
Prop
Type
DorkOS stores credentials by reference, never as plaintext in config.json. The top-level
providers block maps a provider id to a reference: keychain:<id> (your operating system's
built-in password manager), env:<VAR> (a process environment variable), or file:<name> (a
DorkOS-owned encrypted secret store). The reference resolves to a real key at each runtime's
startup, and a broken reference fails loudly instead of quietly sending an empty key. Claude
reads providers.anthropic; OpenCode reads the provider selected by
runtimes.opencode.provider. Codex never receives its key via a subprocess environment
variable, so runtimes.codex.credentialRef feeds the delegated codex login path instead. Net
effect: your API key never sits in a plain text file waiting to be read.
Harness Sync
Harness Sync projects your .agents/ definitions and installed marketplace plugins out to every agent harness. By default, installing or uninstalling a marketplace plugin re-runs this projection automatically.
Prop
Type
Local login
DorkOS runs with no login by default: no login screen, no user concept, instant start. Turning on local login creates an owner account (email + password) that is required to use the instance. The first registered user becomes the owner; further sign-ups are rejected until a future invites release reopens registration.
Prop
Type
Session cookies are signed by Better Auth. Production deployments should set the BETTER_AUTH_SECRET environment variable so sessions survive server restarts.
Cloud link
Linking this instance to a DorkOS account lets the account see and manage it. Run dorkos cloud login to link (it prints a code to approve in your browser, and works even with no browser on the same machine), dorkos cloud status to check the link, and dorkos cloud logout to unlink. Local login and the cloud link are independent: either can exist without the other.
Prop
Type
Set DORKOS_CLOUD_URL to point at a non-production cloud (defaults to https://dorkos.ai). While linked, the instance checks in with the cloud on startup and every 15 minutes. If the account revokes the instance, the next check-in clears the local token and the instance is unlinked.
Uploads
Uploaded files (from chat, workbench, or anywhere else you attach a file) are stored under .dork/.temp/uploads/ in your working directory, with limits you can adjust:
Prop
Type
Telemetry
DorkOS shares a little anonymous data by default. Two channels are on: a daily heartbeat and marketplace install counts, both genuinely anonymous (no prompts, code, paths, or session content). DorkOS shows a first-run notice and sends nothing on that first run, and you can turn it off any time with dorkos telemetry disable, DO_NOT_TRACK=1, or the Privacy & Data settings tab. Crash reporting is separate and stays off until you turn it on. See the full telemetry contract for the exact payload.
Prop
Type
Two environment variables turn everything off no matter what these settings say: DO_NOT_TRACK
and DORKOS_TELEMETRY_DISABLED. Set either to 1 and DorkOS sends nothing. dorkos telemetry status shows each channel and any override; DORKOS_TELEMETRY_DEBUG=1 prints the exact payload
to your terminal instead of sending it. See the telemetry page.
Config Directory
DorkOS creates ~/.dork/ on startup for configuration and state storage. Structured logs are written to ~/.dork/logs/dorkos.log, one JSON entry per line.
Use dorkos config path to print the path to your config file, and dorkos config list to view all active settings.