Skip to content
Codex
Documentation GitHub
Agent

Process Model

Status: Design landing Reference epics: INK-825 ADRs: ADR-016, ADR-020, ADR-021

The process model describes how the Inklings application is partitioned across OS processes — what runs where, how they talk, and what invariants the boundaries enforce.

Three processes

Section titled “Three processes”

Inklings runs as three processes, each with a distinct role.

  • Tauri host. The Rust application. Owns the UI webview, the local database (inklings.db), filesystem access, the task-runner, the permission system, sync, and all workspace-domain logic. This is the only process the user sees as “the app.”
  • Python sidecar. One long-running Python process, spawned by the Tauri host at application start. Hosts the agent runtime (see Agent Core System), the MCP server (see MCP System), provider SDK clients (see LLM System), and the memory clients.
  • Wasmtime sandbox. One or more short-lived Wasmtime instances, spawned on demand to execute a specific sandboxed task (typically a Python snippet via the CPython-in-Wasmtime executor). Each instance is scoped to one call; it does not persist between calls.

That is the full list. There is no separate agent-harness process. There is no DSPy optimizer running as a separate OS process — DSPy runs in-process inside the sidecar as the LLM programming layer (see LLM System). There are no per-subagent OS processes. A subagent is a subgraph in the sidecar (see Agent Core System), not a new process.

One sidecar, one agent host

Section titled “One sidecar, one agent host”

The sidecar is singular. Every conversation, every scheduled task, every subagent run happens inside this one Python process. Runs are distinguished by thread_id, not by process identity.

Concurrency inside the sidecar is cooperative — the agent graph is async, tool calls are async, and multiple thread_ids can be in-flight concurrently. The sidecar’s responsibilities:

The sidecar does not own the database. It does not own the user’s filesystem. It does not enforce permissions. All of those are in Rust, reached through MCP.

Wasmtime as capability, not runtime

Section titled “Wasmtime as capability, not runtime”

The Wasmtime sandbox is where untrusted or derived code runs — typically Python snippets executed by the CPython-in-Wasmtime MCP tool. It is a capability the agent reaches through tooling, not a runtime the agent lives in.

The agent does not run inside Wasmtime. The sidecar does not run inside Wasmtime. Only the specific piece of code the agent asked to execute runs inside Wasmtime, for the duration of that call. When the call returns, the instance is torn down.

This framing matters because of how it constrains reasoning:

  • Whatever runs in Wasmtime cannot touch the database, the filesystem, or the network except through host functions the sandbox explicitly exposes.
  • The sandbox inherits the caller’s capability set at call time; it does not have standing of its own.
  • Any write the sandbox produces is a proposed write and flows through the Submit Boundary like any other agent write.

See Sandbox Execution for the domain semantics and MCP System for how the executor is exposed as a tool.

IPC surface (narrowed)

Section titled “IPC surface (narrowed)”

The Tauri host and the sidecar communicate over two channels, and no more.

  • Sidecar IPC. A small, typed command surface. The host tells the sidecar to start a turn on a thread, resume an interrupted turn, cancel a turn, or stream output. The sidecar tells the host when a turn emits output, when a turn interrupts, and when a turn completes. This surface is narrow on purpose: it does not carry tool calls, permission checks, or domain writes.
  • MCP. The sidecar reaches the Tauri host’s capabilities — workspace reads, workspace writes, permission checks, memory reads and writes, sandbox execution — through the in-process MCP bridge described in MCP System. This is also what lets external MCP clients (Claude Desktop, Cursor) reach the workspace.

These two channels are the full IPC surface. Anything else — the RLM framing, the agent harness contract, direct database access from the sidecar, a Rust-side agent loop calling back into Python — is not part of the model.

IPC payloads are small: start/resume commands reference thread_id and deltas, not full conversation history. Streaming output is incremental text plus typed events (tool call started, tool call returned, interrupt raised). Tool calls do not traverse the sidecar IPC surface at all — they go through MCP, which is hosted in the sidecar.

Process lifetimes

Section titled “Process lifetimes”
  • Tauri host. Lives for the lifetime of the application. Exit shuts down the sidecar and any in-flight Wasmtime instances.
  • Sidecar. Started on application launch. Restarted on crash. A restart does not lose state: conversations and threads are checkpointed in inklings.db, which is owned by the host, so the sidecar reconnects through MCP and resumes.
  • Wasmtime instance. Started per sandbox call. Torn down when the call returns or when its budget (time, memory, fuel) is exceeded.

There are no long-lived agent processes beyond the sidecar. There is no pool of pre-spawned subagent processes, because subagents are not processes.

Database access

Section titled “Database access”

inklings.db is owned by the Tauri host. The sidecar does not open the database file directly. Every read and write the agent performs — workspace content, conversations, memory, checkpoints — goes through the MCP surface, and Rust handlers on the host side execute the SQL.

This is true even for the LangGraph checkpointer: the sidecar’s checkpointer implementation reads and writes through an MCP tool, not through a direct SQLite connection. The reason is not theoretical — it is so that only one process has write access to the database, and all writes go through code that knows about sync, the event log, and the Write Effect Coordinator.

There is no agents.db. Agent state is a table family inside inklings.db, alongside conversations and workspace content.

Crash and recovery

Section titled “Crash and recovery”

The process model makes crash recovery trivially local.

  • Sidecar crash. The host detects the sidecar has exited, spawns a new one, and informs the UI. Any in-flight turn is left at its last checkpoint; when the user sends the next message (or the task-runner fires), the turn resumes normally. No cross-process state needs to be reconciled, because the sidecar owns no persistent state.
  • Wasmtime crash or timeout. The MCP tool call returns an error. The agent graph sees a failed tool call; the planner node decides what to do (often: report to the author, raise a deviation, or try a different approach). No other state is affected.
  • Host crash. On restart, the host replays conversation and thread state from inklings.db, spawns a fresh sidecar, and the application resumes. Any scheduled tasks that would have fired during downtime are handled by the task-runner’s catch-up policy (see Scheduling System).

Why this shape

Section titled “Why this shape”

Narrowing the IPC surface is what makes the agent surface describable as a system rather than as a cross-process state machine. The alternative — a Rust agent harness driving a Python optimizer, or a Python runtime talking to a Rust dispatcher — made every new agent capability a negotiation across the boundary. Every memory surface, every tool, every subagent pattern had to decide which side it lived on.

The current shape removes that negotiation: tool bridge is MCP, agent host is the sidecar, domain owner is the Tauri host, sandbox is a capability. Nothing else is on either side of the IPC line.

What this page does not do

Section titled “What this page does not do”

Was this page helpful?