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

Relay Configuration

Relay is the messaging layer that lets agents reach you on Telegram, notify each other, and connect to external platforms. 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.

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

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 → Rooms 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.

Connectors

Connectors let 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.

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 Settings → Extensions with a note that it is waiting for you, and an Allow it to run button. Click it once and you are done. 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.

Two things do ask again, because in both the code has changed hands rather than been edited by you: installing an update to an extension, and reinstalling one you removed. Editing an extension you already allowed never re-asks.

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. Your agents can read it but cannot write it, which is the point: an agent that could add its own extension to that list would be approving its own code. 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. 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.

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; a path starting with ~ will not work here. 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 at most twelve of these running at once and gives back the one you have used least when it needs room.

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 null, which means every runtime starts where it always did — 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.

Choosing autonomy is the one that asks you first. DorkOS will not save it until you have read what Full autonomy means and confirmed it, and it writes down that you did — after that, 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, integrations, and rooms have their own settings and their own, stricter rules.

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.

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 yourself is the one exception: that command is you asking for everything on disk to be projected, so it installs hooks without a prompt, including ones you turned down earlier.

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

These settings let you answer one approval once instead of every time, for one agent doing one named thing, for a set number of hours. They are off to start with, and turning them on needs local login to be on too — without a sign-in, DorkOS cannot tell you apart from an agent running on the same machine.

Switching either one off ends every permission you have open, right away. It stays ended: turning the setting back on later never brings an old permission back, however you switch it, and whether or not DorkOS was running at the time. Granting a permission again is always a fresh decision you make.

DorkOS keeps one more value in this section, approvals.standingGrantsVoidBefore. It writes that one itself to remember when you last switched standing permissions off, and it is what stops an old permission waking up later. Leave it alone — editing the config file by hand here can bring back a permission you meant to end.

Full autonomy

Turning a conversation up to Full autonomy asks you to confirm what that means first. The agent no longer stops for your approval before each action, so it is a setting you cannot notice in time to undo — which is why it asks twice. 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.

So does 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. DorkOS confirms before turning that on too, in the words of the setting you picked rather than borrowing the ones above. A read-only setting is left alone: it never asks because there is nothing to ask about.

If you tick Don't show this again in that dialog, DorkOS writes down the date and stops asking you to confirm — one answer covers all of it. Settings → Security shows the date back with a Reset button; resetting brings the dialog back the next time you reach for a setting that won't stop for approval. Resetting also turns off any Full-autonomy default for new chats — that note is what let new chats start with the approval prompts off, so it goes when the note does. Nothing about a conversation you already have changes either way; only the confirmation comes back.

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. Either way DorkOS asks you to confirm what it means once, at the moment you choose it, and writes down that you did. 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; if you never chose one, it starts where scheduled runs have always started — able to edit files, stopping for anything riskier. Picking a level on the task itself always wins. Integrations 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.

Reset takes effect everywhere within about half a minute. A browser tab you left open reads your settings from a copy it refreshes every 30 seconds, so a tab open at the moment you reset can still skip the dialog once before it catches up. Nothing is lost by that — it only means the confirmation returns a few seconds later on that tab than on the one you pressed Reset in.

This is a confirmation for you, not a lock against your agents. It makes sure a person cannot arrive in Full autonomy without having been told what it means. It is not a defence against a program on your machine calling the API directly — that is what standing permissions and local login are for.

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.

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

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 during setup. 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 → 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