Runtimes

A runtime is the coding agent that powers a session. DorkOS ships with three: Claude Code, Codex, and OpenCode. Chat with any of them in one place. Every session lands in the same list, streams through the same chat, and uses the same tool approvals and status bar.

Only using Claude Code? Nothing changes for you, and you can stop reading here. The rest of this page is for anyone who wants to add Codex or OpenCode to the mix.

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

Each runtime needs two things: its CLI installed somewhere your computer can find it, and a login. DorkOS checks both for you and tells you exactly what's missing.

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.

Choose a Runtime

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

For One Session

Before the first message, the runtime chip in the status bar is a picker. Click it and choose. Once the session starts, the runtime is fixed for that session'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 session launched from that agent inherits it. Existing sessions keep the runtime they started with.

As the Default

Set the fallback runtime for sessions 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've registered more than one Claude account (see Configuration), you can send a chat's work, and what it bills, to a specific one. This only shows up once DorkOS knows about more than one account — with just one, there's nothing to choose.

For One Chat

Before the first message, open the runtime chip in the status bar and pick an account. It applies to that chat only: the menu says so, and the choice locks once the first message sends. The menu also names what "Default" would actually charge, so leaving it alone is still a choice you can see.

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.

See the Runtime

Every session wears its runtime openly:

• Session 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 always before the first message so you can still change it. Otherwise it's one row in the Session panel behind the ⋯, where you can pin it to keep it in view.
• 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 provider 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 session. 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 conversation, 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.

Known limitations, stated plainly:

• Runtime is fixed per session. A session's runtime is chosen when it starts and never changes. To switch runtimes, start a new session.
• Codex has no interactive approvals. Instead of pausing on each tool call, Codex gates everything upfront through a sandbox: a restricted environment that limits what the agent can touch. The permission mode picker maps directly onto Codex's sandbox levels: Read only (default), Workspace write, and Full access. You choose the sandbox before the work starts, not the tool call while it's running.
• Codex sessions don't survive a server restart in the session list. Codex has no way to list its own past sessions. After a DorkOS server restart, earlier Codex sessions no longer show up in the list. Resuming a known session still works, for example by opening its URL directly.
• 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