Runtimes

A runtime is the AI program that powers an agent: its brain. DorkOS ships with four: DorkOS, Claude Code, Codex, and OpenCode, and you can use more than one at once. Every chat lands in the same list, streams through the same chat, and uses the same tool approvals and status bar. The tools an agent uses are written to [the record](/docs/guides/audit-trail

Only using Claude Code? Nothing changes for you, and you can stop reading here. The rest of this page explains the other choices and their setup.

With a single registered runtime, DorkOS looks exactly as it always has. The status-bar chip is a quiet identity mark, not a picker. Runtimes that are registered but not set up yet show up in the picker as "Needs setup" entries with a clear next step, never as dead options.

Connect a Runtime

DorkOS runs its own agent without another CLI. Claude Code, Codex and OpenCode each need their CLI and a sign-in. The app checks their setup and tells you what's missing.

Set up the DorkOS runtime

Open Settings → Runtimes → DorkOS and choose Set up or Change source. Choose what pays for model requests:

• Your API key: choose a service, request format, endpoint and model. Enter your key here; the app stores an encrypted reference. Anthropic subscription tokens are refused.
• Local model: enter your running model server's HTTP loopback address and model name. No key is needed. Ollama and LM Studio can serve compatible models.
• DorkOS credits: link this computer to a DorkOS account. There is nothing else to set up: DorkOS picks the model for each new chat. To choose one yourself, open the DorkOS card's Model row. Chosen by DorkOS hands the choice back. If your account has no model DorkOS can use, the chat stops with a message instead of paying some other way.

For a custom or local model, enter its context limit and maximum reply size in tokens. The request format must match the service: Anthropic Messages, OpenAI Chat Completions or OpenAI Responses. Save, then choose DorkOS in an agent's Runs on row or when starting a new chat.

A chat keeps the inference source and request format it started with, including after a restart. Changing runtime settings applies to new chats. A missing source stops the chat with an error. An existing API key is tied to its endpoint; changing the endpoint requires a matching key.

The DorkOS runtime can read project instructions and skills, use the app's tools, and delegate coding work to a separate builder. Tool approval follows the selected permission mode. Its model history is stored separately from the visible chat. Chat forks, question cards and media attachments are not offered by this runtime yet.

Set up a coding runtime

npm i -g opencode-ai && opencode auth login

Run the commands in your terminal, then check the runtime picker in the chat status bar:

• A runtime whose checks pass is selectable immediately.
• A runtime that's installed but missing something shows a "Needs setup" entry. Selecting it opens a panel listing each dependency check, with a copyable install or auth command and a Check again button. Think of it as DorkOS holding your hand instead of just failing quietly.
• A known runtime that isn't installed at all appears under "Add a runtime" with the same guided setup.

Environment variables passed to agents

DorkOS no longer passes its whole server environment to coding agents or their setup commands. It keeps the operating system settings they need, supported model sign-ins, and privacy choices such as DO_NOT_TRACK. Server secrets, including database passwords and Connections encryption keys, stay out of that inherited environment.

Custom tools may need a variable that DorkOS does not pass automatically. You can allow its exact name for one runtime in your config file. Values stay in the environment that starts DorkOS. See runtime environment settings for the format and upgrade steps.

This reduces accidental exposure. It does not isolate agents from your operating system account. An agent with shell or file access may still reach your files, credentials, or other processes.

Choose a Runtime

Runtime selection works at three levels. An explicit per-chat choice wins over the agent's runtime. The agent's runtime wins over the config default.

For One Chat

Before the first message, the runtime chip in the status bar is a picker. Click it and choose. Once the chat starts, the runtime is fixed for that chat's lifetime, and the chip becomes a read-only mark.

You can also launch directly onto a runtime with the ?runtime= URL parameter:

/session?runtime=opencode

For an Agent

Open the agent's profile and tap the Runs on row, which holds the runtime, the model and the effort together. This writes the runtime field into the agent's .dork/agent.json. Every new chat launched from that agent inherits it. Existing chats keep the runtime they started with.

As the Default

Set the fallback runtime for chats that don't specify one:

dorkos config set runtimes.default opencode

See the Configuration reference for the full runtimes block.

Choose an Account

If you use more than one Claude account, you can pick which one a chat runs on, and so which one it bills. With only one account, none of this shows up, because there is nothing to choose.

This is for Claude Code only. Codex and OpenCode each use the one sign-in on this computer, and DorkOS doesn't support several accounts for them.

Add Your Accounts

Open Settings and go to Runtimes. On the Claude Code card, under Runs on, choose Add account, pick the account's folder and give it a name you'll recognize. You can also edit the settings file by hand (see Configuration).

DorkOS also looks for Claude account folders on this computer that you haven't added yet. They appear in a group called Found on this computer, each with its folder and when it was last used. Choose Add to add one, or Dismiss to stop seeing it. A folder that looks like it belongs to a company or school account is marked managed by an organization. DorkOS never adds a folder until you click Add.

This computer's own Claude sign-in (usually the ~/.claude folder) is your main account. DorkOS calls it Main (this computer's sign-in) everywhere it names an account. With two or more accounts, it gets its own row in the list, with its usage. It has no remove button, because it is the computer's own sign-in rather than something you added. If you add its folder as an account yourself, that row takes its place. When a row is marked in use, that's the account new chats run on. If the server was started pointing at a folder no row stands for, a line above the list names that folder, and no row is marked.

DorkOS credits

DorkOS credits are an inference source for DorkOS and an account choice for Claude Code.

When this computer is linked to a DorkOS account, DorkOS credits is one more choice in the same places you pick an account: the Default account list under Runs on, an agent's Runs on, the account chip before a chat's first message, and Continue on another account. A chat set to DorkOS credits runs on them and nothing else. If DorkOS can't reach your credits, the chat stops and says so, with Retry and Use your Claude Code sign-in. It never quietly runs on your own sign-in instead. When a scheduled task, an agent's reply or a room turn stops this way, you get a notification, so it never fails without anyone knowing.

Some projects have their own Claude Code sign-in in their .claude/settings.json. Those can't run on credits, so the chat stops with Don't use credits in this project beside Use your Claude Code sign-in. That adds a project limit without credits, which you can remove in Settings → Runtimes.

Anything a chat runs, such as a project's hooks or the commands an agent runs, can read the credits key while the chat runs on credits, just as it could read your own API key. Only use credits in projects you trust.

If you link a DorkOS account while Claude Code has no sign-in at all, DorkOS sets new Claude Code chats to run on credits and tells you once, with Change and Undo all. If you sign in to Claude Code later, DorkOS offers once to switch back. Turning credits off is remembered, and a sign-in that has expired is never replaced with credits. A computer linked before credits were a choice keeps everything as it was, and gets one offer you can turn down.

An agent runs on credits only when you pick that for it in the app. If an agent's own settings file asks for credits, its row says so and offers Allow; until then it uses your default. Project limits can keep credits out of a project, but they never choose credits.

Codex and OpenCode on credits

Codex and OpenCode don't have account lists, so each one has a single choice: its own sign-in, or DorkOS credits. The choice shows as Runs on on its card in Settings → Runtimes, and as its switch under Use credits for, but only once DorkOS credits serve that runtime. Until then neither place shows it. If a runtime is set to credits and credits can't run it for now, its row stays so you can switch it back.

• Codex: the choice applies to new chats. A chat already going stays on whatever it started on. Codex can't search the web on DorkOS credits. On credits, Codex doesn't use your own Codex settings in ~/.codex: its MCP servers, its global AGENTS.md and its profiles stay out of credits chats. The tools DorkOS gives an agent still work.
• OpenCode: the choice moves all of OpenCode, chats already going included. You can't switch while OpenCode is in the middle of a reply, so nothing it's doing is cut off. On credits, OpenCode offers the models your DorkOS account lists.

On credits, neither one uses your own Codex or OpenCode sign-in or keys, and DorkOS never changes your own Codex or OpenCode settings. If DorkOS can't reach your credits, the chat stops and offers a way back to your own sign-in:

• Codex: Start a new chat on your Codex sign-in. A chat that started on credits can't move, so this switches Codex back and opens a new one.
• OpenCode: Use your OpenCode sign-in. This switches all of OpenCode back, not just that chat, then sends the message again.

Anything a credits chat runs, such as an MCP server or a command the agent runs, can read the credits key while it runs, just as it could read your own key. Only use credits in projects you trust.

With two or more accounts, each account has a color, and its dot wears that color everywhere in the app. To change it, click the account's dot in Settings and pick one of 8 colors, or Default. Main's dot works the same way.

For One Chat

With two or more Claude accounts, the status bar at the bottom of a chat shows an account chip. It has the account's color dot, its name, and two small bars for its 5-hour and weekly limits.

Before the first message, click the account chip and pick an account. It applies to that chat only, and the choice locks once the first message sends.

After that, the chip tells you how the account is doing:

• Amber, with words, when the account is close to a limit: "Acct 3 · 91% of week".
• Red when the account is out: "Acct 4 · out until Tue 3pm", or "Acct 4 · back in 47 min" when the 5-hour limit ran out.
• Amber when only one model is out, such as "Acct 3 · Opus out until Tue 3pm". The account still has room for other models.

Click the chip to see each limit, when it resets, and how long ago that reading was taken. If the chat is working on a flow task, the popover names the task too.

See Which Account a Chat Uses

With two or more Claude accounts, each Claude Code chat in the sidebar has a small dot in its account's color, just before its name. Hover over the dot to see the account's name. The chat's header shows the same dot and name.

For an Agent

Open the agent's profile and tap Runs on, then pick an account the same way you'd pick a model. The row shows where the choice came from: green when the agent just follows your default, amber when you set something else here. One tap on that chip puts it back to following your default.

Settings → Runtimes lists every agent billing somewhere other than your default, next to the ones running on a different runtime or model. An agent pointing at an account this machine doesn't know about shows up in amber, in Settings and in the sidebar's Needs-attention group, and bills to your default until you fix it.

As the Default

Set which account new chats bill to when neither the chat nor the agent names one, at Settings → Runtimes → Claude Code under Default account.

Watch Your Usage

You don't have to send a message to see where you stand. As soon as you open a chat you've already used, the status bar shows its usage and context numbers. This works for every runtime and any number of accounts. With two or more Claude accounts, the account chip carries the usage numbers instead, and shows your usage even before the first message.

Usage belongs to the account, not the chat. Every chat on the same account shows the same numbers, and they change together.

The numbers come from the last time DorkOS read them. Their popover or tooltip says when, such as "as of 12 min ago". A reading more than about an hour old looks a little faded. A limit whose reset time has passed reads reset.

Settings → Runtimes shows usage bars for every runtime that reports them, even with one account. Claude Code shows its 5-hour and weekly limits, and Codex shows its weekly limit too. OpenCode only reports what it spends, so its card shows one line instead, like "$4.20 spent this month". With two or more Claude accounts, each account's row has its own bars.

When Usage Runs Out

Every account has usage limits. When a chat's account runs out, the chat can't go on until the limit resets, or, for some Claude Code chats, until you move the work to another account. This applies to every runtime, with any number of accounts.

A notice appears above the message box, such as "Acct 4 is out of usage until Tue 3pm." When the 5-hour limit ran out, it says how long to wait instead: "Acct 4 is out of usage · back in 47 min." With one account, or on Codex or OpenCode, the notice names the runtime rather than an account, like "Codex is out of usage until Tue 3pm."

On a Claude Code chat that can move, the notice usually has two buttons: Continue on another account… and Wait for reset. Otherwise it offers only Wait for reset. Until the limit resets or you move the work, the message box is paused: "Paused until you continue or the account resets". If DorkOS doesn't know when the limit resets, the message box stays open.

The notice is red while the chat needs you, including when only one model is out. It turns grey once there is nothing you need to do: while you wait, after the reset, and after the work has moved.

With two or more Claude accounts, the sidebar shows the same thing in words, in place of the chat's time:

• "out · needs you" in red, while the chat waits for you to choose;
• "out · waiting for reset" once you chose to wait;
• "out · handing off" while the work moves to another account.

The header badge shows the same words. On a narrow window, the header shortens "out · waiting for reset" to "out · waiting". Once the work has moved on, the old chat goes back to looking normal.

If something goes wrong when you choose a button, the notice says why in a line of its own, or "Couldn't do that. Try again." when there is no reason to give.

Continue on Another Account

Only Claude Code chats can continue on another account, and only ones you started in DorkOS, or that an agent started for you. Any other chat can only wait for its reset, such as one started by a schedule, from Telegram or Slack, or in the terminal. So can every Codex or OpenCode chat. An agent in a room or channel moves to another account on its own; see Rooms.

To move on, choose Continue on another account… on the notice, or click the account chip and choose it there. It only shows while the chat is out of usage. A list opens with your other accounts, each with how much of its week is left and when it resets, like "28% left · resets Sun". An account that is out too can't be picked.

Pick one and choose Continue on followed by its name, like Continue on Acct 2. DorkOS starts a new chat in the same folder, on the account you picked, with a summary of this one. The chat itself does not move: the old chat stays where it was, and the new one picks up the work. On a flow run, flow picks the task up in the same folder and branch from where it last saved its progress.

Without flow, every other account is listed, the one with the most usage left first. With flow installed, flow may shape the list:

• one account may be marked recommended;
• your main account may show dimmed, because flow keeps it in reserve (you can still pick it);
• accounts you keep out of flow are not listed.

If no account can take the work, the list says "No other account can take this work right now."

Wait for the Reset

Choose Wait for reset and the notice turns grey, such as "Waiting for Acct 4 · back in 1h 12m", or "Waiting for Acct 4 · back Tue 3pm" when the reset is more than a day away.

On a chat that could move to another account, the notice also has a Continue automatically when it resets checkbox. Tick it and the chat picks up again on its own when the limit resets. Only Claude Code chats can do this. Codex and OpenCode chats, and any chat that can only wait, never continue on their own: you choose when to carry on.

When the reset comes, the notice says "Acct 4 has reset." with a Continue button that picks the chat up where it left off. If DorkOS can't confirm the reset, it says "Acct 4 should have reset by now." instead. The same words appear if the reset time passes while the notice still waits for you, and the message box opens again so you can just send a message.

Once the limit is over, the notice goes away and leaves a one-line note in the chat where the work stopped:

• "Resumed after reset at 4:02pm" after a reset;
• "Acct 4 ran out · moved to Acct 2 at 2:14pm" after the work moved (the new account's name opens the new chat);
• "Opus ran out · continued on Sonnet at 4:02pm" after a switch to another model;
• "Acct 4 ran out · continued here at 4:02pm" when you kept going in this chat before the reset.

Other Things You Might See

• "All accounts are out." Every account you could use has run out. The notice names the one that comes back soonest, like "Soonest back: Acct 2, Sun 9am", and the only choice is Wait for reset.
• "Opus is out on Acct 3 for this week." Only one model ran out. Choose Keep going on Sonnet, same account to carry on with a different model. The notice may also offer Continue on another account… and always offers Wait for reset.
• "This task continued on Acct 2." The work moved to a new chat. Choose Open it → to go there. The message box here stays shut, so you don't split the work by accident. To keep using this chat anyway, choose Continue here anyway. That choice lasts for this limit only; if the account runs out again later, the notice asks again.

On a Flow Run

If flow is set to Hand off automatically, the notice counts down for 10 seconds before moving the task: "Moving this task to Acct 2 in 10s…". The message box reads "Paused until the task moves or the account resets". Choose Move now to skip the wait, Choose account… to pick a different account, or Wait for reset to stay. On a flow run, the notice then says "Moving this task to Acct 2…" until flow reports the move, and after that it says the task continued elsewhere.

Choosing Wait for reset on a flow run hands the wait to flow. Flow holds the run, and picks it up again at the reset only when Continue automatically when it resets is on.

If DorkOS can't reach flow, the notice says "Flow could not be reached, so this was not changed."

Let Flow Share the Work

The /flow plugin can spread its work across all your accounts, so a task keeps going when one account runs out. Use all your accounts walks through setting it up. This section only covers where its settings live in the app.

Install the flow plugin from the Marketplace. The first time, your Activity inbox asks "Turn on Flow?": choose Turn it on, once. Settings → Extensions shows the same choice. After that, Settings has a Flow tab under Add-ons. With two or more Claude accounts, the account list in Settings → Runtimes points to it: "Flow uses these accounts for your work. Choose how in Settings → Flow."

The Flow tab lists your accounts grouped by runtime. Give each one a role:

• Main is your own everyday account. Keep 50% for me sets how much of its weekly limit flow leaves alone, and Use it all in the last N hours before it resets lets flow spend the rest just before the week resets.
• Rotation accounts are ones flow may use freely.
• Kept out accounts are never used by flow, unless you list repositories under Only for these repos. Then flow uses it only for those.

On your first visit, a short notice explains the three roles. If you have a Main account but nothing in rotation, the tab says "Nothing is in rotation yet, so flow only uses your main account."

Two more settings apply to every account. When an account runs out is either Hand off automatically (flow moves the task to another account) or Ask me (flow waits for you to choose). Cross-runtime fallback is an Off or On choice, and starts on Off.

See the Runtime

Every chat wears its runtime openly:

• Chat list: rows carry a small runtime mark next to the title.
• Chat status line: the runtime chip names the active runtime whenever it isn't your usual one, and before the first message so you can still change it. A DorkOS chat doesn't show it there. Otherwise it's one row in the Chat details panel behind the ⋯, where you can pin it to keep it in view. The model works the same way: it shows only once you pin it.
• Agent profile: the Runs on row names the runtime, and agent cards badge it.

Local Models with OpenCode

OpenCode reaches Ollama and any OpenAI-compatible endpoint through its own service configuration. Set it up once with opencode auth login, or in OpenCode's config file, and the models appear in DorkOS automatically.

Models That Can't Do the Job

A cloud gateway like OpenRouter offers hundreds of models, and not all of them can run a chat. The model menu says so before you pick, rather than after:

• Models that can't use tools sit under their own heading, Can't do agent work. They can hold a chat, but they can't read your files or run commands. They stay in the menu — if you went looking for one, you should be able to find it.
• Models that make images carry a note on the card. They work, but DorkOS can't display a generated image yet, so a picture-making model looks like it answered with nothing. This note goes away once DorkOS can show generated images (DOR-1663).

If you pick a model your runtime can't run, DorkOS tells you straight away instead of saving the choice and failing on your next message.

What to Expect

Most people never hit the differences below. This section is the deep reference for anyone comparing runtimes closely, so it gets more technical than the rest of the page.

The runtimes are not identical, and DorkOS doesn't pretend they are. Surfaces that depend on runtime capabilities, like the cost strip, permission modes, and plugin commands, adapt to the active runtime instead of showing controls that don't work.

What each runtime keeps running after a reply, and what happens to it, is on Work That Runs After a Reply.

Known limitations, stated plainly:

• Runtime is fixed per chat. A chat's runtime is chosen when it starts and never changes. To switch runtimes, start a new chat.
• Codex asks before it changes things, as much as the level you pick says. When Codex wants to do something its level does not allow, it stops and shows a card in the chat, and the step runs only if you approve it. The permission picker has three levels for Codex:
  • Ask first (the default): Codex reads files and runs read-only commands without asking, and so are tools their own server marks read-only. Anything else stops on a card first. A step you approve can reach beyond this project.
  • Workspace write: Codex changes this project and temporary folders freely. It asks before it reaches further or goes online.
  • Full access: Codex can change anything on this machine, network included. It never stops to ask.
• You can steer Codex mid-reply. A message you send while Codex is replying joins that reply, instead of waiting for the next one.
• Codex keeps background commands running after it replies. When one finishes, the chat picks up again on its own: Codex reads the result and carries on. It does this only after a reply that ended normally. If you stopped the reply, the chat shows the result and waits for you. A command that never ends, like a dev server, never wakes the chat. After three pickups in a row with no message from you, the chat waits for you. In a room, a finished command shows in the chat and the room carries on at its next turn. You can stop one from the task bar above the chat box. DorkOS stops one still running four hours after its reply, and stops them all when DorkOS shuts down.
• If you deleted or archived a Codex chat in Codex itself, the next message in DorkOS starts a fresh one and says so. The chat's history in DorkOS stays.
• The older way to run Codex is still there. Set runtimes.codex.transport to exec in ~/.dork/config.json and restart DorkOS. Codex then runs one process per reply: it cannot ask before a step, take a message mid-reply, summarize the chat when asked, or keep anything running after it replies.
• Only Claude Code's auto mode knows about DorkOS's own tools. When an agent calls a DorkOS tool, DorkOS tells Claude Code which safety level that tool sits at and that the call already passed DorkOS's own check, so auto mode stops asking about things that were already decided. Codex and OpenCode have no way to be told, so they keep asking as they always have. The note never lets an agent do anything it could not do already.
• Only Claude Code says which background tasks are housekeeping. Some of what an agent runs is work it started for itself, to stay oriented, rather than anything you asked for. Claude Code marks those, and DorkOS keeps them out of the task bar's count above the chat box, so that count only moves for work you are waiting on. You can still see them: open the task bar's detail panel with the arrow at its right edge, where they are listed with a count. They still appear in the chat itself, like any other background task. One that fails is always shown like any other failure. Codex and OpenCode do not mark their tasks, so every task they report is counted.
• All three runtimes get the DorkOS tools. Whichever one an agent runs on, it gets the same set — including the canvas and the browser: putting a document up, opening a file or a diff, pointing the Browser tab somewhere, reading the console and the network log, taking a screenshot, and using the page. One difference stays, and it is about consent rather than capability: an agent reaching in from outside the DorkOS app has no way to ask you first, so the one action that writes to your machine — applying a Shape — is refused there and answered with a sentence saying to do it in the app instead.
• OpenCode starts lazily. DorkOS manages a small local OpenCode server behind the scenes and starts it on first use. The first OpenCode turn after a server start can take a couple of seconds. Every turn after that is immediate.

Next Steps