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 service.

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 dorkos

Required

Optional

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.

Wi-Fi access

server.lanAccess (default false) is the Let devices on my Wi-Fi in switch in Settings → Remote access. On a Mac, other devices on the same network can open DorkOS at this computer's .local name, with no restart. It needs a login, and it stays off while DORKOS_HOST or DORKOS_ALLOW_INSECURE_BIND is set, because either already decides where DorkOS listens. See Securing your instance.

Relay Configuration

Relay is the messaging layer that lets agents reach you on Telegram, notify each other, and connect to external platforms. It is on by default. You can turn it on or off without a terminal: switch Agent messaging in Settings › Advanced › Tools, or choose Turn on chat apps on the Connections page, then restart DorkOS when it asks. The environment variable below wins over that switch whenever it is set. See the Relay Messaging guide for setup details.

Scheduled Tasks Configuration

A scheduled task runs an agent job on a timer (like "every night at 2am"), on its own, without you keeping a terminal open. See the Scheduled tasks guide for setup details.

Keep awake

DorkOS keeps your computer from falling asleep while agents work, then lets it sleep as usual. Change it in Settings → Tools → Sleep. See Sleep and wake for what it can and cannot stop.

Heartbeats

Whether your agents wake up on their own to check their work. Each agent's own HEARTBEAT.md says how it wakes; this switch turns it off for all of them at once.

Activity

How long the Activity feed keeps its history. The record behind it keeps every action forever, whatever this says. See The record.

A2A Gateway

The A2A gateway lets agents built by other people, on other systems, send work to the agents here — anything that speaks Google's Agent-to-Agent protocol. Agent messaging (Relay) has to be on for it to do anything.

It is off until you turn it on, and there are two ways to do that. In DorkOS, open Settings → Advanced → Experiments and flip "Let outside agents reach yours". On a server you run headless, set the environment variable instead — that wins over the setting either way, and the switch says so rather than pretending it decides.

It is still early alpha. Only turn it on when you know what is on the other side of the door.

Telling auto mode about DorkOS's own tools

Most DorkOS tools carry a safety level DorkOS checks before the tool runs. Auto mode in Claude Code cannot see that check, so it used to stop and ask you about calls DorkOS had already decided — two questions for one decision. DorkOS now tells it which level the call passed, and it asks you less often.

This covers the tools that carry a declared safety level. DorkOS's other tools — the ones it also offers as named capabilities, such as config_get, memory_write, list_capabilities and the marketplace_* tools — are checked a different way and say nothing to auto mode, so it keeps asking about those exactly as it did before.

The note only ever says what DorkOS itself decided, and only one thing: which of DorkOS's three safety levels the tool sits at. It never carries anything from the tool's arguments, its output, or your conversation, and it cannot let an agent do anything it could not do already — Claude Code is still free to ask you about anything, any time. Codex and OpenCode have no way to be told, so this changes nothing for them.

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.

Memory

Each of your agents keeps a small file of notes — things it learned that are worth keeping — and reads it at the start of every conversation it joins. The file lives beside the agent, on this machine, and you can open it in any editor.

Rooms

A room is a conversation more than one agent can be in. When you post, every agent the message addresses answers — and because an answer is itself a message, agents can end up replying to each other. This setting is where that stops.

You do not have to edit the file for these. Settings → Advanced → Room limits has the switch and all four numbers, and a single room can be given limits of its own from the panel beside it — open a room, choose Members, then Automatic replies. A room you have not touched follows what you set here.

Room files

A room can own files that everyone in it works on together. See Files a room owns for what that gets you. These settings decide whether rooms may have files at all, how long an untouched copy is kept, and how big things may get.

Most people never change these. The defaults are sized for documents and small projects.

Two of the size limits behave differently from the rest. The file and total-size limits are written down for each room when its files are first set up, so a room keeps the limits it was made under, and raising or lowering them later never makes an existing room's files suddenly illegal. The ROOM.md limit is read fresh every time, so changing it takes effect on every room's next turn.

Welcome back

When you come back after a few hours away, the agents that got something done while you were gone can post a line about it in your team channel. The rule is news, not noise: an agent with nothing new to say says nothing, and only a few post at all.

A note can also end with one thing the agent wants you to decide — "want me to open the PR?". That part is on to start with, and it is the one piece of this that costs anything: there is no way to know an agent has a next step without asking it, and asking runs it for a turn. Only the agents that already left you a note are asked, and each of them only once. The switch says all of this next to itself, and turning it off stays off.

Both switches are in the app, at Settings → Preferences → Welcome-back notes and Next-step offers; they change welcomeBack.enabled and welcomeBack.offersEnabled below. The two numbers are file-only for now. See When you come back after being away for what the notes look like.

Notifications

DorkOS can play a sound, or raise a notification from your browser, when an agent needs you. The idea is that an interruption should mean something. You get a knock when an agent stops and is waiting on your answer, a quiet chime when the last thing waiting on you is done, and nothing the rest of the time.

You set all of this in the app, at Settings → Notifications. Your answers are saved with DorkOS rather than with one browser, so a sound you turn off on your laptop is off on your phone too. Your agents can read these settings, but only you can change them. An agent that could turn the knock off could stop you hearing that it is waiting.

The first time a notification would help, DorkOS shows a small card asking your browser for permission. It asks once. Whichever button you press, the card is done.

One sound changed. The chime that played every time a turn finished is now off to start with. When you have a few agents running, a chime every turn tells you nothing. If you had that chime on before, you keep it: DorkOS carries your old choice over the first time you open the app.

That last setting is the one that reaches your pocket. When an agent stops and waits on you for longer than this, DorkOS sends a notification to every browser you have added under Settings, Notifications, and a message to any chat app your agents can start conversations in. Answer in any of those places and the rest go quiet.

DorkOS only does this for things that are actually blocked on you: an agent waiting for an answer, a scheduled task waiting for your approval, or a session that stopped on an error. News, like a turn finishing, never follows you around.

Two things have to be true for it to reach you. You need at least one device added, a chat app connected, or both. And a phone only works if its browser can receive notifications, which means opening DorkOS there over a secure connection.

On a phone, open DorkOS using your tunnel address (see Tunnel Setup), then choose "Add to Home Screen." It installs like an app: full screen, with its own icon, no browser bar. On iPhone this step is not optional — it only shows notifications from an app installed this way, never from a browser tab. Once it is installed, open Settings there and add the phone under Notifications, and it joins the list above.

Connections

Connections is where your agents reach outside services (Gmail, Slack, and so on). Most of that is set up in the app, not here. The one piece that lives in the config file is the list of remote MCP servers you want DorkOS to offer as connectable services.

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:

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.

Where an extension's tab shows

ui.panelTabs holds where each extension's right-panel tab shows, one entry per tab you changed. You change it from the panel (Hide here, Show here) or in Settings → Extensions, so there is rarely a reason to edit it by hand. A tab with no entry follows the extension's own default, or shows everywhere.

Letting an extension run inside DorkOS

An extension is code, in two places: some of it runs on your computer with the same reach DorkOS has, and the rest runs on the DorkOS page in your browser, signed in as you. Neither is a small thing to hand out, so DorkOS asks you about each extension once, and runs none of it until you answer.

You will see it the first time: the extension shows up in your Activity inbox, and in Settings → Extensions with a note that it is waiting for you, with a Turn it on button. Click it once and you are done. Not now in the inbox turns nothing off; it just stops asking until the extension changes version. Editing that extension, testing it, and reloading it all work from then on with nothing further to click, and turning the extension off and on again does not ask you again. If you change your mind, Stop it on the same card takes the permission back and stops the extension straight away. Your inbox then treats it like Not now: it asks again only when that extension changes version or comes from somewhere else.

Some extensions come inside a plugin you install from the marketplace. Those show up in Settings → Extensions too, and ask the same way.

Your yes is for one copy of an extension: the one in that folder, from that plugin. Two things ask again, because in both the code has changed hands rather than been edited by you: reinstalling an extension you removed, and a different plugin bringing an extension with the same name. Updating a plugin keeps your yes for the extensions it still brings. Editing an extension you already allowed never re-asks.

If you install the same plugin into several projects, you only say yes once. DorkOS remembers where it installed the plugin from, and every copy from that same place counts as the one you allowed. The newest copy runs everywhere, so a project that still has an older copy doesn't hold the others back. A copy that arrived some other way, like inside a repository you cloned, still asks on its own, even if its files claim to come from the same place. So does a copy whose plugin files changed after DorkOS installed it, for example by a git pull, or one holding a shortcut to files somewhere else: Settings → Extensions says so on its card. If you say yes to a changed copy, you are saying yes to its files as they are now, and any further change asks again. Only code DorkOS fetched from a branch or a tag of that place counts, never a pull request.

Right after you turn on an extension, the inbox may ask once more: "Next time, trust everything from dork-labs/marketplace?" Say Yes and extensions DorkOS installs from there turn on without asking. You can see and remove these in Settings → Extensions → Trusted sources. If you remove one, the extensions from it that are on now keep running exactly as they are, but newer versions and anything new from that place won't run until you say yes. Only you can add or remove a trusted source; your agents can't.

Extensions that ship with DorkOS never ask. You already installed DorkOS. DorkOS tells its own extensions apart by where their files sit, not by the name inside them, so a folder in your project cannot claim to be one.

Your answer lives in extensions.approvedToRun, and the copy it applies to lives in extensions.approvedSources. Your agents can read the first but cannot write either, which is the point: an agent that could add an extension to that list could approve any code at all. DorkOS writes one entry itself: for an extension one of your agents builds with create_extension, unless you chose Careful. That entry names the new folder and the permissions it asks for today, so a copy from somewhere else, or a later version that asks for more, still waits for you. See Settings your agents cannot change.

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. Using more than one runtime at once 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.

If you have more than one Claude account, the runtimes.claudeCode settings say which one your work runs on. A Claude account is a folder that holds that account's chat history and its own sign-in. It is usually ~/.claude, and a second one might be ~/.claude2. Point defaultAccount at a folder and your next chat runs and bills there, unless the agent or the chat itself names another account. Write the folder's full path, like /Users/you/.claude2. Leave it null and nothing changes: DorkOS uses whatever your shell already set, or ~/.claude. List your accounts under accounts and give each one a name you'll recognise, like the client you bill it to. Nothing outside DorkOS changes either way. Your shell, your aliases, and a plain claude all keep working exactly as before.

You do not have to edit this file. Open Settings and go to Runtimes: you can add your accounts there, name them, and choose the one in use. Once you have more than one, the account also shows in the status bar at the bottom of a new session, so you can switch before you send.

You can also say which model a new chat should start with, and how hard it should think. Each runtime has its own pair of settings — defaultModel and defaultEffort — because a model name only means something to the runtime that offers it. Leave them null, which is how they ship, and each runtime keeps picking for itself, exactly as before. Set one and every new chat on that runtime starts there; chats you already have keep what they are running with. Effort is one of none, minimal, low, medium, high, max, or xhigh. OpenCode has a model setting but no effort setting: OpenCode gives no way to ask for more or less thinking, so DorkOS does not pretend to offer one. If you edit the file by hand, only add settings that exist. A setting DorkOS has never heard of, like runtimes.opencode.defaultEffort, is left alone and skipped: it stays in your file, and nothing reads it, so it will not do what you hoped. Settings is the safer place to change any of this.

Claude Code chats keep their agent running between messages. Your next message reaches an agent that is already awake instead of one that has to start from scratch, so replies from the second message on come back about four times faster. That is runtimes.claudeCode.persistentSession. New setups start with it on; if you have been running DorkOS for a while, an upcoming update turns it on for you.

Changing it applies to the next message you send in each chat — nothing you have open changes underneath you. That is true in both directions, with one wrinkle worth knowing: a chat whose agent is already running keeps it until that agent goes away on its own, which happens after five quiet minutes, when the chat is closed, or when you restart DorkOS. An agent that has been sitting idle is shut down automatically, and you will not notice — your next message simply picks the conversation up where it left off. DorkOS keeps a limited number of these running at once and gives back the one you have used least when it needs room.

How many agents can run at once is sized to your computer. That is runtimes.claudeCode.maxWarmProcesses. Left empty, which is how it ships, DorkOS allows one per 2 GB of memory: never fewer than 12, never more than 32. A 48 GB machine gets 24. Set a number to pin it. When every one of them is busy, a new message does not fail: it waits for one to finish, and the chat or room says it is waiting. If nothing finishes for 45 minutes, it stops waiting and says why.

What it costs is memory — up to about a gigabyte per waiting agent. If your machine is tight on it, turn Warm agents off in the Control Center (⌘⇧L, or Ctrl+Shift+L) and every message goes back to starting its own agent. Nothing about what your agents may DO changes either way: the same program runs with the same permissions, and every action is checked the same way.

The switch used to sit in Settings under Experiments and moved to the Control Center when it stopped being an experiment; dorkos config set runtimes.claudeCode.persistentSession false does the same thing from a terminal. Once you turn it off it stays off — your agents cannot turn it back on for you. One more thing worth saying plainly: if you had turned this off yourself while it was an experiment, the update that turns it on will turn yours on too. DorkOS has no way to tell an off you chose from the off it shipped with — they are the same word in the same file.

And you can say how much a new chat may do before it checks with you. That is runtimes.defaultTrustStop, and it takes one of three words: ask (stop before changing anything), act (get on with the work, stop for the risky parts), or autonomy (never stop). It ships as autonomy: a new chat edits files and runs commands without stopping to ask, and everything it does is recorded in Activity. Set it to ask if you want to approve each change first, or to null to let each runtime start where it used to, which is asking first. One setting covers every runtime, because those three words mean the same thing whichever agent you are talking to; each runtime works out its own equivalent. If you want something different for just one of them, set defaultTrustStop inside that runtime's own block and it wins there.

With autonomy, every new chat starts with the approval prompts turned off, so agents act without stopping for your OK each time. They still ask when something genuinely needs your call, and still follow anything you have told them to check with you about. Settings shows a quiet note while that is on, so you can always find it. Chats you already have keep what they are running with, whatever you change here. This setting is for the chats you open yourself: scheduled runs, chat apps, and rooms have their own settings and their own, stricter rules.

Runtime environment settings

DorkOS passes a selected set of environment variables to Claude Code, Codex, OpenCode, and their setup commands. It preserves normal home folders, command lookup (PATH), Git and SSH settings, proxy and certificate settings, and DO_NOT_TRACK. Supported model sign-ins are included when the command needs them. Binary lookup, installation, and hardware checks do not receive model keys automatically.

The runtimes.environment.inherit lists let the owner add exact names for custom tools. These lists start empty, including after an upgrade. Agents cannot change them through DorkOS tools. Put names in the config, never secret values. For example, merge this into your existing runtimes block:

{
  "environment": {
    "inherit": {
      "claudeCode": ["ACME_BUILD_TOKEN"],
      "codex": [],
      "opencode": []
    }
  }
}

This passes ACME_BUILD_TOKEN from the environment that starts DorkOS to Claude Code and its helper commands. It does not create the variable or read it from your project. Use only names you intend that runtime and its tools to receive. Each list allows at most 128 names, up to 128 characters each. Duplicate names, including case variants, are rejected. Server-only names such as MCP_API_KEY, NANGO_ENCRYPTION_KEY, and all DORKOS_ names cannot be added.

When upgrading: custom variables that agents used to inherit need an explicit entry here. This includes GH_TOKEN, custom model credentials, private registry settings, and NODE_OPTIONS if your setup needs them. Standard Claude, Codex, and supported OpenCode model credentials keep working without an entry. Claude's Bedrock, Vertex, and Foundry environment modes pass their matching credentials when their mode flag is enabled. If you choose a mode only in Claude's settings file, add any environment credentials it needs explicitly. Other Claude cloud modes and custom Codex or OpenCode model settings also need exact-name entries for their environment variables. A known custom Claude mode refuses to start until its enabled mode flag is explicitly allowed.

Restart DorkOS after changing its environment or inheritance lists so every running agent uses the new settings. Existing warm agents and the OpenCode background process keep their current environment until they stop. Removing a name does not erase a value already received by a process.

This protects against accidental inheritance, not access by another process running as your operating system user. Allowed proxy, SSH, and model settings can themselves carry credentials. An allowed variable is available to that runtime's tools.

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.

It also keeps up on its own while DorkOS is running. When an agent writes a new skill into .agents/skills/ during a session, it shows up in your other coding tools within a few seconds — no command to run and no restart. Most tools read that folder directly, so they see it the moment the file lands; Claude Code reads .claude/skills/ instead, so DorkOS puts a link there for you. One caveat, and DorkOS says it when it applies: Claude Code only notices new skills in a folder that already existed when the session started. If DorkOS had to create .claude/skills/ for this project, restart any Claude Code session you have open.

Deleting a skill is the one thing this does not follow. DorkOS adds links while you work and never removes them on its own, so a skill you delete leaves a dead link behind. dorkos harness sync --check lists them and dorkos harness sync --fix clears them out.

Some packages ship hooks: commands your coding agent runs on its own, before or after it does things. Installing a package never puts those in place on its own. DorkOS shows you each command and when it would run, and waits for you to say yes. It remembers your answer per package and per project, and asks again if a later version of the package wants to run something different, or wants to run the same thing at a different moment.

Running dorkos harness sync --fix yourself follows the same answers. It sets up everything else the package brought, holds its hooks back, and prints each command it did not install. If DorkOS cannot read your settings file at all, it says so and holds every package's hooks back rather than guessing. To install them, run dorkos harness sync --fix --allow-hooks <package>, which saves your answer in the same list. dorkos harness hooks --list shows every package you have decided about, and dorkos harness hooks --revoke <package> forgets one so DorkOS asks again.

dorkos harness sync --check now lists everything else in your .claude/ folder too, so nothing in it goes unmentioned. Your rules (.claude/rules/), your subagents (.claude/agents/), your MCP servers (.mcp.json), the hooks you keep to yourself in .claude/settings.local.json, and any hooks a skill declares in its own front matter each get a line saying they stay in Claude Code — and, for every other agent you run, where that agent would keep the same thing. Nothing new is written for any of them: the list tells you what does not travel yet and why. Some of it already travels — Cursor reads .claude/agents/ itself, and Cursor, OpenCode and Copilot all read .claude/skills/ — so those are listed as kept rather than dropped, including the skills you marked Claude-Code-only. And where a skill's name would break an agent's own naming rule, the line says which rule, instead of promising it works.

Your agent's profile has a Skills page that shows all of this without a terminal. It lists every skill in the agent's folder — the ones you wrote, the ones a package brought, and the ones your coding tools keep in their own folders — with a small tag per tool saying what that tool does with each: reads it, has a copy, out of date, or can't see it. Where a tool can't see something, the page gives you the same sentence dorkos harness sync prints, word for word. When files are out of date, a line at the top offers to fix them, and before you press it, it names every file the fix would delete and why each one is going. Afterwards it lists them again, so nothing disappears without being said.

It reads your other tools' folders too, so a project that never used Claude Code is not handed an empty list. Skills you keep in .opencode/skills/, .cursor/skills/, .gemini/skills/, .github/skills/ or .codex/skills/ each get a line saying which tools read them where they are and which do not, and the Skills page says to move one to .agents/skills/, where every tool can read it — it is a sentence, not a button, and nothing is moved for you. And if your MCP servers are declared in opencode.json, .codex/config.toml or .cursor/mcp.json rather than .mcp.json, you get one line saying how many are in there and that DorkOS only passes on the ones in .mcp.json. It counts them and reads nothing else, so nothing from those files ever gets printed or stored.

If you wrote your own hooks file — .codex/hooks.json or .cursor/hooks.json, say — DorkOS never overwrites it and never deletes it. It names the file, leaves it exactly as you left it, and tells you where to put those hooks instead: .claude/settings.json, the one file it reads hooks from and copies out to every agent you run. The single exception is a .codex/hooks.json holding nothing but a bare list of events, which is what older versions of DorkOS wrote there and Codex never read; that one it replaces with a file Codex does read.

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.

Session cookies are signed by Better Auth. Production deployments should set the BETTER_AUTH_SECRET environment variable so sessions survive server restarts.

Standing permissions (removed)

The approvals section is gone. Its settings (approvals.standingGrants, approvals.trustWindowMinutes and approvals.standingGrantsVoidBefore) are removed from your config file the first time the new version starts. Always allow on a request card replaced standing permissions: it is a permission setting for one agent and one action, changed on the Permissions page. See Always allow.

Agent permissions

What your agents may do on their own, what waits for your yes, and what they cannot do at all — across twelve areas (Rooms, Tasks & schedules, Other agents, Messages, Chat connections, Tools & packages, Extension tools, Own chat, DorkOS settings, Safety limits, Permissions, Reach & secrets) plus Files & commands, how often an agent stops to check with you while it edits files and runs commands. See the Permissions guide.

These are changed on the Permissions page (Settings → Permissions, or an agent's own Permissions page), never here, so that every change DorkOS makes is recorded in the history. (An edit made straight to an agent's settings file is recorded too, as changed outside DorkOS.) PATCH /api/config and dorkos config set refuse any permissions key and say where to go instead.

Choosing a preset sets all twelve areas AND moves runtimes.defaultTrustStop, the global Files & commands stop: Trusted to autonomy, Careful to ask. (Balanced and Full power, from earlier versions, still read: Balanced moves it to act, Full power to autonomy.) Per-runtime stops (runtimes.claudeCode.defaultTrustStop and its siblings, documented under Runtimes above) are left alone by a preset and show up as changes on top of it.

DorkOS keeps four more values here; leave them alone. permissions.upgradeSweptVersion records which version last carried your old settings across on upgrade. permissions.trustedStoresAppliedAt records when DorkOS first let your agents message each other across projects. permissions.sharedAppsAppliedAt records when DorkOS shared each connected app no agent could use yet with every agent, and permissions.sharedAtUpgrade lists those apps, so the one-time note can name them. Each happens once: if you turn one off afterwards, it stays off.

If DorkOS ever has to replace a damaged config file with a fresh one, it keeps your Careful preset, the areas and actions you set to Ask or Blocked, and any Files & commands stop you set to Ask or Act. A fresh file would otherwise start you on Trusted.

Each agent's own differences live in its .dork/agent.json, under permissions (areas, actions, and its own filesAndCommands stop).

Full autonomy

At Full autonomy, a conversation's agent no longer stops for your approval before each action. It still asks you when something genuinely needs your call, and still follows anything you have told it to check with you about. What changes is the approval prompt that used to halt each action, not the agent's judgment. Choosing it is like choosing any other level: there is no extra confirmation.

The same goes for any other setting that will not stop to ask. Some agents cannot pause mid-turn to ask permission, so their middle setting ("Act") edits files and runs commands in your project without checking with you.

You can also make Full autonomy where every new chat starts, in Settings under the defaults for new sessions, or right after you change a chat's setting — a quiet line offers it there for a few seconds. From then on new chats start with the approval prompts off, and Settings keeps a note saying so with a link to change it back. Scheduled runs follow the same level. A task you create without picking a level starts at whatever you chose here, worked out for the agent that will run it; that is Full autonomy unless you changed it. If you set it to null, a task starts where scheduled runs have always started — able to edit files, stopping for anything riskier. Picking a level on the task itself always wins. Chat apps and rooms still have their own settings and their own, stricter rules, and a task file on disk can never hand itself the never-ask level — that is refused whatever your default says.

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. See Your DorkOS Account for the full walkthrough.

Set DORKOS_CLOUD_CREDITS=0 to turn DorkOS credits off on a server. Anything set to run on credits then stops and says so, instead of running on another sign-in. The variable can only turn credits off, never on.

Set DORKOS_CLOUD_URL to point at a non-production cloud (defaults to https://dorkos.ai). Credits, balance and plan calls follow it too. To send only those somewhere else, set DORKOS_CLOUD_API_URL. 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.

Linking this computer again with the same DorkOS account can bring back the apps it connected through its earlier link, as long as that link was not removed from the account. If it was removed, or you link a different account or a different computer, connect those apps again.

Uploads

Files you attach in a chat or the workbench are stored under .dork/.temp/uploads/ in that project's working directory. Files you attach in a room are kept with DorkOS itself rather than in any project, because a room isn't tied to one — a channel can be about several projects, or none.

Either way the limits below apply to both:

Your profile

Tell DorkBot what kind of work you do, and every agent on this machine knows who it works for. DorkBot asks once, with a card in the sidebar. Your answer is saved here and shared only with your own agents. It is local-only; never included in any telemetry payload.

Telemetry

DorkOS sends us nothing unless you turn it on. Two anonymous channels are available, both off by default: a daily heartbeat and marketplace install counts (no prompts, code, paths, or session content). DorkOS shows a first-run notice explaining them, and you can turn them on any time with dorkos telemetry enable or the Privacy & Data settings tab. DO_NOT_TRACK=1 keeps everything off no matter what the settings say. Crash reporting is separate and also stays off until you turn it on. See the full telemetry contract for the exact payload.

Experiments

Some features are still being proved out and are not yet ready to be the default. Those wait in Settings → Advanced → Experiments, off until you turn them on, each one saying plainly what it gives you and what it costs.

Every experiment ends the same two ways: it becomes the normal behaviour and leaves the list, or it goes away. So the list is meant to be short, and an empty one means nothing is waiting on you.

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.

Next Steps

Shared browser experiment

Settings → Advanced → Experiments lists Shared browser, off by default. People can change this in Settings. Agents can read it but cannot change it.

The choice applies to all users of this installation without sharing their profiles. Enabling is currently refused before any settings are written. It does not download a browser or skip safety checks. Browser use and safe stopping are not yet available through this setting.

Spaces experiment

Settings → Advanced → Experiments lists Spaces, off by default. While it is off, nothing about spaces shows in the app, and the app refuses requests that reach a space. Your space connections stay saved, so turning it back on finds them where you left them. Your own channels and #team are not spaces and work the same either way. Agents can read this setting but cannot change it.

spaces.official.url names one official space by its link: the space's own /c/... link, or its short address. A link to a whole server does not count. That one space shows in the switcher and can be joined even while Spaces is off. Every other space stays hidden, and so do starting and hosting spaces. It is empty by default, which means there is no official space and nothing changes. The DORKOS_OFFICIAL_SPACE_URL environment variable overrides it. Agents can read this setting but cannot change it.

Chat from the web experiment

Settings → Advanced → Experiments lists Chat from the web, off by default. It is early: it needs your own DorkOS in the cloud, which is not available yet. While it is off, the Chat from the web section in Settings → DorkOS account is hidden, and this computer never connects to the cloud for it, even if you linked it before. Linking, pausing and unlinking happen only in the app on this computer, never from another device. Linking, resuming and allowing more ask for your password for this computer again. Agents can read this setting but cannot change it.

Docs experiment

Settings → Advanced → Experiments lists Docs, off by default. Turn it on, and a markdown file open in the canvas can link to another one. Type [[ and pick a doc from the list, or write a doc's title or file name between double brackets, like [[Launch plan]]. To change the words the link shows, add | and your own words: [[Launch plan|the plan]]. A link with a heading, like [[Launch plan#Goals]], opens Launch plan too.

Click a link while reading to open that doc in the canvas. While editing, Cmd-click it (Ctrl-click on Windows and Linux). A link to a doc that does not exist yet looks different from the others. It starts working the next time DorkOS reads the folder's docs: when you create or rename a file in the Files panel, when you save a doc whose title changed, or when you come back to the DorkOS window or open a doc again after half a minute. A link to a heading in the same doc, like [[#Goals]], does not open.

Links find the .md files in the folder your chat works in and every folder inside it, skipping hidden folders and folders such as node_modules. In a very large folder, the [[ list holds only the docs nearest the top: it stops after 2,000 docs, 2,000 folders, or 8 folders deep. A link to a doc past that is still looked for across the whole folder. If even that takes too long, the link says the folder is too big to check, rather than calling the doc missing. When two docs share a name, the one nearest the doc you are writing in wins. Agents can read this setting but cannot change it.

Chats with one agent

Settings → Advanced → Experiments lists Chats with one agent read like a DM, off by default. Turn it on, and talking to one agent looks like talking to a teammate: the agent's face and name at the top, its replies with its face, name and time, and a message box like a channel's. Everything the chat shows today stays: replies as they are written, tool steps, thinking and to-dos. Clicking the agent in the sidebar, Message on its card, its profile, the New menu and the agent in Cmd+K all open this same chat.

The model, account, permissions and context move out of the chat. To get to them, turn on Show sessions on the same page. The chat's header then shows a session chip with how full its context is, and clicking it opens the working session behind your chat, exactly as chats look today. Both settings apply to everyone using this DorkOS. Agents can read them but cannot change them.