---
title: "Architecture · intentic docs"
description: "How intentic fits together: the thin platform, the sandbox daemon, direct browser control, durable state, agent execution, child agents and remote runners."
url: "https://intentic.dev/docs/architecture/"
updated: "2026-09-15"
---

Learn

# Architecture

intentic separates account discovery from agent control. A thin platform tells your browser where the sandbox is; the browser then drives the sandbox daemon directly. The daemon on that machine owns the code, credentials, conversations and work.

**On this page (10 sections)**

- [The two product tiers](#the-two-product-tiers)
- [The platform](#the-platform)
- [The sandbox](#the-sandbox)
- [The direct command path](#the-direct-command-path)
- [The execution model](#the-execution-model)
- [Isolation, state and recovery](#isolation-state-and-recovery)
- [Shape is different from state](#shape-is-different-from-state)
- [Compute can move without moving control](#compute-can-move-without-moving-control)
- [Capabilities and extensions cross different boundaries](#capabilities-and-extensions-cross-different-boundaries)
- [The lifecycle](#the-lifecycle)

## The two product tiers

### The platform

The platform is an account and discovery plane: the web shell, sign-in, subscription state, invitations, and the public address a sandbox announces when it boots. It does not proxy ordinary agent turns, inspect a workspace, or hold a credential that can drive a self-hosted sandbox.

There are explicit custody exceptions, not hidden ones. A **hosted** sandbox still takes commands directly from your browser, but intentic controls the machine lifecycle because it rents that machine. The optional free trial sends its trial turns through platform-owned model accounts, and the iOS notification relay forwards pointer-only notifications to Apple. Neither is the ordinary command path.

### The sandbox

A sandbox is a long-lived workspace environment, normally one Docker container plus durable volumes. It can hold many conversations and run many agents at once; it is not one disposable container per chat. The program inside it is the **daemon**: one API and event source for every browser, terminal, agent runtime and automation attached to that workspace.

| The daemon owns | What that includes |
| --- | --- |
| **Agents** | Provider accounts, harness selection, detached turns, questions, permissions, transcripts and usage. |
| **Workspace** | Repositories, files, search, terminals, dev servers, previews, worktrees, diffs and landing. |
| **Connections** | Capabilities, secrets, connected devices, extensions, VPNs and browser profiles. |
| **Unattended work** | Schedules, webhooks, listeners, workflows, loops, watches and restart recovery. |

The deployment engine bundled in the image is deliberately **not a third product tier**. It is one tool an agent may run to reconcile infrastructure, just as it may run a test runner or database client. Infrastructure it creates does not become part of the account platform or the sandbox control plane.

## The direct command path

Every sandbox connection starts outbound. Its tunnel process dials the reachability hub, and the browser uses the resulting address; nothing needs to dial into your laptop or server. The platform may revoke the grant or forget the address, but it cannot use the grant to act as you.

Google is the first proof, not the credential carried forever. The daemon verifies the ID token against Google's keys, binds the owner on first use, then exchanges it for a sandbox-signed session whose signing secret never leaves the box. Membership and role are checked again on each request, so removing a member also ends the authority of an already-open session. Programs use separately scoped, revocable control tokens instead of pretending to be a browser.

## The execution model

A **conversation** is the durable unit you see on the fleet board. A **turn** is one run inside it. Before a turn starts, the daemon resolves four independent choices: provider, connected account, model, and [harness](https://intentic.dev/docs/models/)— the agentic loop that plans and calls tools. Runtime capabilities are declared per provider-and-harness pair, so the UI never offers a control that the selected runtime would silently ignore.

*One conversation can fan out without losing one supervision model*

Parent conversation

registry · transcript · questions · review · land

Runtime subagent

Created inside the current harness. It shares the parent turn's provider and working tree.

Full child agent

Created by intentic's meta-harness. It gets its own conversation, provider, worktree and placement.

Execute in this sandbox

Execute on a connected runner

The two child shapes share one roster but not one isolation model. A harness-native subagent is part of its parent's turn. A full child agent is an ordinary isolated conversation that may use a different provider or outlive the parent turn. The same concurrency, lifetime and depth settings govern both: native limits are passed into the harness, while the daemon enforces full-child limits at the spawn door. A parent may answer a full child's factual question, but only a person may approve that child's permission or plan card. [Parallel agents](https://intentic.dev/docs/parallel-agents/#when-an-agent-delegates) covers the supervision mechanics.

Turns are detached from the HTTP request that starts them. Frames receive sequence numbers, persist into the transcript, and can be replayed before a client rejoins the live stream. A journal records in-flight work across daemon restarts, which is why closing a tab is harmless and why an interrupted update can be reported or resumed instead of disappearing.

## Isolation, state and recovery

A normal chat may work in the shared tree. An isolated conversation instead gets one git worktree per repo, with that composition mounted at `/work` for the turn. Parallel agents therefore see the paths every project instruction already names while editing different branches. Landing is the single door back: it applies the conversation's delta to the main tree without moving main's commit history.

| Layer | Holds | Lifecycle rule |
| --- | --- | --- |
| `/work` | Repos and workspace configuration | Agent-visible and mounted from a named volume, so updates and rebuilds keep it. |
| `/history` | Git history, transcripts, checkpoints, identity and durable daemon records | Outside the workspace mount, so a command in the workspace cannot erase the recovery record. |
| `Container image` | The daemon, runtimes and approved environment overlay | Replaceable. An update recreates it from the run contract while the two volumes stay put. |

## Shape is different from state

A sandbox has a reproducible *shape* and irreplaceable *state*. The shape is derived on demand as a deterministic [`sandbox.toml` definition](https://intentic.dev/docs/sandbox-definitions/): the workspace remote, repository remotes, connection shapes, secret names, the approved overlay source, and non-default agent settings. The workspace is a repository too, so the way a sandbox works — its skills, personas, automations and designs — is part of its shape rather than something only a backup can move. Credentials, identity, transcripts and unpushed work never enter the file. That makes the definition reviewable, comparable for drift, and safe to use as a fleet template.

A bundle is the other door: definition plus the state that no source can reproduce. Applying a definition is preview-first and lands beside existing entries; restoring your own bundle is a continuity operation. The distinction preserves consent: an overlay from a shared definition becomes a proposal for the target owner, while an overlay returning in that owner's own bundle may be restored as already approved.

## Compute can move without moving control

A [runner](https://intentic.dev/docs/remote-runners/) is the same sandbox image in an execution-only mode on another computer. It has no browser owner, public hostname or independent workspace. It dials the parent sandbox over one outbound socket, receives an isolated turn, checks out that conversation's branches, and streams the ordinary agent events back.

The parent remains the system of record: conversation status, transcript, interactive cards, branch mirror, diff and landing all stay there. The runner contributes CPU, memory, disk and a warm toolchain. It starts with the parent's image and approved overlay; a settings-only sandbox definition keeps its agent settings comparable and synchronisable. Child agents can be placed across ready runners automatically, while an explicitly placed conversation stays on the machine chosen when it was created.

## Capabilities and extensions cross different boundaries

A [capability](https://intentic.dev/docs/capabilities/) is a declared connection the daemon knows how to enforce: a provider account, MCP server, database, SSH host, VPN, browser identity or connected computer. Its credential is stored inside the sandbox and its effects are shown before approval. A connected device enforces its own folder and action switches locally, so the sandbox cannot widen the grant it was given.

An [extension](https://intentic.dev/docs/extensions/) adds product surfaces: views, file renderers, commands, settings, background processes or capability cards. Its manifest is the contract, installation is pinned to an exact commit, and trusted code or an environment change requires owner approval. Skills and agent plugins are context loaded by an agent runtime; extensions are code loaded by intentic.

## The lifecycle

1. 1

 Choose where the sandbox lives

 Use a device you own, or a machine we host. Every route boots the same sandbox image from the same run contract.
2. 2

 The sandbox connects out

 It opens its own outbound tunnel and announces the resulting address. No inbound port, router rule or platform-to-sandbox connection is needed.
3. 3

 Bind on first use

 Your browser presents a fresh Google proof directly to the daemon. The daemon verifies it, binds the first owner, and mints its own renewable session.
4. 4

 Start a detached turn

 The daemon resolves the provider, account, harness, permissions, workspace and placement, then acknowledges the run. Reloading the page does not stop it.
5. 5

 Review and land

 An isolated conversation returns as a cumulative diff. Landing applies it to the main workspace as uncommitted changes; your commit remains the review boundary.

## Related pages

- [Parallel agents](https://intentic.dev/docs/parallel-agents/): worktrees, child agents, review and landing.
- [Sandbox definitions](https://intentic.dev/docs/sandbox-definitions/): the reproducible shape of an environment.
- [Remote runners](https://intentic.dev/docs/remote-runners/): moving execution to another machine without moving control.
- [Sandbox API](https://intentic.dev/api/): the callable contract exposed by the daemon.

More in Learn

[Previous ← The worksite](https://intentic.dev/docs/worksite/)[Next Glossary →](https://intentic.dev/docs/glossary/)