# Architecture
Source: https://dorkos.ai/docs/concepts/architecture

How DorkOS connects your browser to your coding agent, in plain language





# Architecture [#architecture]

DorkOS looks the same whether it's running as a website or tucked inside Obsidian, and it works with Claude Code, Codex, or OpenCode without you changing a thing. That's the whole idea: one cockpit, any agent, any place you happen to be working.

## The big picture [#the-big-picture]

Three things talk to each other:

```
Your browser  ->  DorkOS  ->  Your coding agent
```

You open DorkOS in a browser tab (or inside Obsidian). It shows you your sessions, lets you send messages, and streams back what your agent is doing in real time. Underneath, DorkOS swaps out which agent it's talking to (Claude Code, Codex, or OpenCode) without you having to reconfigure anything. That swap is the headline trick: pick a runtime per project, and the interface doesn't change under you.

## Two ways to run it [#two-ways-to-run-it]

**As a website.** This is the default, and the one most people should use. DorkOS runs a small server on your machine and you open it in any modern browser. Multiple browser tabs (or people) can watch the same session at once.

**Inside Obsidian.** DorkOS also ships as an Obsidian plugin that runs in the same process as your notes, no separate server involved. This mode is early and still getting hardened, so treat it as a preview rather than a finished surface: expect rough edges, and prefer the web cockpit if you want the most polished experience.

Both modes read the same sessions from disk, so a session you started from the terminal shows up in whichever one you open next.

## Why this matters to you [#why-this-matters-to-you]

Two things fall out of this design that are worth knowing:

* **You can change agents without losing your setup.** Switching a project from Claude Code to Codex (or back) doesn't mean starting over. DorkOS talks to each agent through the same interface, so your sessions and workflow carry over. Note that multi-agent coordination features (agents messaging each other, discovering one another across a project) are newer and still being proven out in real use.
* **Your sessions live in ordinary files, not a hidden database.** Each coding agent keeps its own session history on disk in its own way. That means restarting DorkOS never loses a conversation, since DorkOS is just reading files that were already there. It also means you can't accidentally "delete" a session from inside DorkOS: it's gone only if the underlying files are gone.

<Callout type="info">
  Because DorkOS reads sessions straight from disk, a session you start with the Claude Code CLI
  shows up in DorkOS too, and vice versa.
</Callout>

## For the curious [#for-the-curious]

This page keeps things at the "how do I think about this" level. If you want the engineering detail, the docs below go deeper.

<Cards>
  <Card title="Sessions" href="/docs/concepts/sessions">
    How sessions are created, stored, and kept in sync across clients.
  </Card>

  <Card title="Architecture (developer reference)" href="/docs/contributing/architecture">
    Interfaces, service layout, and message-flow internals, for anyone reading the source.
  </Card>

  <Card title="SSE Protocol" href="/docs/integrations/sse-protocol">
    The streaming event protocol behind the real-time updates you see.
  </Card>
</Cards>