Architecture
The domain model is SESSION → WORKSPACE → COMPUTE. Devctrl manages where Claude, Codex and Antigravity sessions run, their access, state and continuation. It does not replace the agents with an agent framework.
New Git-backed coding sessions own an immutable checkout record separate from the physical workspace. The host creates a unique branch/index/working directory in the existing persistent sessions mount before provider launch. Relative Git worktrees share objects where both Git versions support them; independent clones preserve isolation on older versions. Session working directories, configuration delivery, artifact cleanup and S3 recovery use that ownership record. Physical container start/rebuild still uses the workspace base. Legacy sessions are not moved. See per-session checkouts.
TUI (Ink) ── SSH forward / HTTPS ──┐
Web / static PWA ── HTTPS + WSS ──┼─ gateway / controller → SQLite + encrypted keyring
Desktop (Tauri) ─── HTTPS + WSS ──┤
│ │
│ authenticated agent channels
│ │
└──────────────── execution host / compute adapter
│
Project container (workspace)
├─ Claude session
├─ Codex session
└─ shell / scoped MCP brokers
apps/tui/src/app.tsx and its screens are shared by Ink and React DOM. Both clients use the controller API; static HTML does not execute a server-side dashboard PTY. A remote controller, gateway and tunnel can operate without a local component. The legacy Docker Desktop stack remains supported: if the laptop is the authority, sleeping it makes that console unavailable, while sessions on remote hosts continue. Local files and services require an online client-agent regardless of controller placement.
Standalone installation additionally provides devctrl tui remote: a small local SSH launcher runs the same Ink bundle inside the server controller container. This optional terminal transport needs local Python and SSH, without a local Docker stack or repository. It is distinct from running a local TUI renderer against the API, and does not provide laptop folder synchronization. The local launcher stores only destination metadata until an optional local module is installed; browser access and server workloads remain independent of it. devctrl web remote opens the server gateway. devctrl client install pulls the public prebuilt AMD64/ARM64 client image, enrolls a Project-scoped credential and synchronizes selected local folders through outgoing SSH to this same authority. It creates no second controller. devctrl host install local explicitly adds a separate host-agent with a separate credential and Docker socket, sharing the outgoing client transport. The file-only module never receives that socket. See local modules.
The controller is the single authority for identity, ownership, desired state, grants and history. Local access uses a private operator credential without a separate login. Server invitation mode enables application users, independently of SSH users. Authority migration uses drain, fencing and handover rather than starting another writer on copied SQLite state. Permanent operator transport credentials and expiring user logins have separate WebSocket lifetime checks.
Named-user state reads select owned inventory and history before decoding entity bodies, then apply the final private-by-default authorization projection. Latest run/job lookups are batched. The shared interface reuses unchanged JSON branches between polls instead of comparing two serialized snapshots. Large catalog bodies load lazily under a shared cache/admission budget. Snapshots contain recent continuation summaries and links to bounded history pages. Journal serialization, flushes, cold reads, retention and standalone backups run in a bounded worker; the main thread remains the sole metadata writer. Result payloads reach durable storage before result-index, acknowledgement-receipt and command-retirement metadata commit together. Signal handling drains this work before closing SQLite. See audit remediation and operating limits.
Control Room reuses the same session/workspace lifecycle for a dedicated, repository-free administrator session. Its internal Project and session have an explicit purpose and stay outside ordinary development views. Only the registered managing session receives server-wide MCP tools; every call rechecks current authority and uses the existing API handlers, policies and audit journal. The operator credential stays inside the controller. Named-user and public-link sharing are disabled for this privileged session. Paired messengers and reviewed voice input are optional client interfaces to it. The shared Control Room chat requests bounded native conversation pages through the existing authenticated controller/host WebSocket channel. Reads do not attach the PTY or send model prompts. User input follows the existing terminal transport with owner-scoped, sanitized delivery receipts; visible native replies confirm the conversation independently of transport acceptance. Claude subscription voice uses a separate temporary official-CLI dictation context on the chosen execution host, then returns a reviewed draft to the same chat. Codex subscription dictation is not exposed by this integration; an eligible Claude source can prepare text for either target. Optional external transcription requires explicit configuration and is never an automatic fallback.
| Layer | Code and responsibility |
|---|---|
| Shared interface | apps/tui/src, apps/tui/web: screens, focus, dialogs, routing and renderer adapters |
| Optional desktop client | apps/desktop: the shared DOM build, native window and credential-free OS page links; a fixed-operation SSH helper discovers/checks connections and optionally installs a fresh server, then the UI connects directly to its gateway |
| API and desired state | apps/controller/src/app.ts, store.ts, server-identity.ts, server-authorization.ts |
| Execution | apps/host-agent/src: reconciliation, durable commands, inventory and MCP brokers |
| Runtime | packages/runtime/src: Docker exec, tmux, account preparation and supported native resume |
| Local sources | apps/client-agent/src: explicitly enrolled SSH links, file sources and Exchange sync |
| Optional providers | packages/*-provider-kit, packages/provider-*: capability contracts and independent adapters |
See features and limitations, server users and the shared UI.
In local operator mode, Docker Desktop runs the controller, one-shot CLI processes, interactive TUI and long-lived client-agent. Each TUI embeds its API/terminal client and usage-reset timers in one Node process; it does not start a separate CLI daemon. The TUI and client stop together, while remote providers remain under tmux. The main stack needs no macOS background daemon or inbound management port. The optional S3 read gateway is a separate native process under a user LaunchAgent and listens only on loopback. On an execution server, host-agent manages Docker Engine and /var/lib/devctl.
The control plane (CLI/TUI → controller ↔ host-agent/client-agent) carries desired state, inventory, heartbeats, commands and actual state. Cross-host TCP currently relays bounded chunks through outgoing host-agent WebSockets at the controller; payloads are neither retained nor inspected. A fixed source proxy connects to a grant-specific Unix socket, so no host TCP listener or firewall exception is needed. The controller authorizes grantId, and the destination agent receives the saved ResourceEndpoint as a fixed target. Direct host-agent transport can be added without changing grants or aliases.
Resource history consumes those server-side observations independently of UI
polling. Bounded SQLite samples and hourly rollups retain real host/workspace CPU,
RAM and disk I/O evidence. A separate authorized, paginated API serves Dashboard
timelines without adding history to /v1/state. Counter resets and gaps remain
unknown; shared containers do not acquire a fabricated per-session allocation.
See resource history.
Managed disk sizes are separate from cumulative disk I/O. One bounded host-side worker measures allocated blocks in actual managed bind sources, caches results and publishes project/container totals with session HOME breakdowns. UI requests never walk the filesystem. Shared checkouts are deduplicated; partial, stale and unavailable values remain explicit. Image virtual sizes and external services are excluded. See managed disk usage.
An independent host-side worker asks supported detached working sessions for brief progress snapshots, every 15 minutes by default. The controller owns per-user policy, durable attempt receipts and the existing input reservation; the runtime verifies native process identity and captures only a completed correlated side answer. A snapshot is separate from lifecycle, task completion and Dashboard activity. Client disconnects do not stop scheduling.
A Project represents a repository and may own several managed containers. workspaceId is the immutable identity of a physical container for persistence, Docker labels, grants, mounts and reconciliation. TUI and web select a container before starting a session and expose containers as a navigation level. Explicit cross-repository reuse requires the same group, compatible runtime/access policies and the same owner. Different server users never share containers, sidecars, homes or storage. See container selection.
Project containers carry devctl.workspace.id, not a session ID, because one container may hold several sessions. /v1/state joins workspaces[].id with sessions[].workspaceId. Long-running managed sibling workloads also carry devctl.session.id; host-agent persists ownership and cleanup strategy in /var/lib/devctl/managed-workloads.json. A provider helper process alone is not evidence of a live interactive session or tmux.
TCP endpoints can describe Project runtimes, hosts, clients, Docker services/networks or remote TCP services. ResourceEndpoint describes availability; ResourceGrant separately holds the internal runtime subject, Project alias, mode and desired/actual state. TcpForward connects endpoints and bind policy. An offline endpoint does not remove desired entities.
Docker discovery normalizes Compose/Dokploy labels, networks, aliases and ports to project/service:port; it does not require the Dokploy API. A service grant creates an isolated fixed-target proxy on the Project and target networks. Whole-network membership is a separate dangerous docker network connect mode. Optional HTTP gateways can use consumerPort and injectProjectIdentity: the per-grant proxy overwrites X-Devctl-Project-Id with the container's immutable Project identity. This is transport identity for object-level gateway policy, not a substitute for an allowlist or an arbitrary caller credential.
For client resources, the session uses endpoint.port unless metadata.consumerPort explicitly overrides it. metadata.relayPort is only the reverse tunnel port on the execution host. For example, a gateway on 18767 tunneled through 37320 remains available to the session at gateway.devctl.internal:18767. Grant creation and route reconciliation follow the same rule.
Account binding belongs to the Session. Starting a container does not enumerate accounts. Provider/account profiles determine UIDs; sessions using one profile may share a UID but receive separate host-backed homes. Opaque account stores use CLAUDE_CONFIG_DIR or CODEX_HOME. The official CLI performs login. Mode 0700 protects against ordinary sibling processes, but root in a devcontainer can read its bind mounts; protection from root requires separate containers or namespaces.
Admin, host and client credentials are distinct and bound to type/identity. SSH authenticates transport; application credentials authenticate entities. Secrets use AES-256-GCM with a separate persistent master key rather than the admin token.
A Service is a separate shared infrastructure runtime. Placement is a tagged union: pinned hosts do not migrate, while scheduled placement receives a host from the scheduler. desiredState, runtimeState, health and restartRequired are independent. Managed Services use Docker on an isolated service network. Ordinary external services are not managed by devctrl; host-declared services may explicitly use a bounded local json-v1 lifecycle from services.d, executed only by the owning host-agent. Service endpoints publish ordinary ResourceEndpoints, keeping Project access on the same fixed-target proxy model.
Environment profiles contain non-secret values and secret references. Public precedence is global/host/project/session; the internal runtime binding sits between Project and Session without exposing a user-facing Workspace reference. Services use global/host/service. System-managed variables apply separately.
Client file sources exist only inside explicitly mounted /client-files/... roots of the Docker client-agent. FileGrants specify source and destination. Transfers are snapshots/copies, not network filesystems. Bounded binary streams use backpressure; the controller routes PassThrough and stores metadata/status, never file contents. The host verifies size/hash, fsyncs and atomically renames. The deployed copy remains on the execution host, while the source remains on the client. Managed file byte work uses bounded per-grant lanes, while inventory freshness remains tied to actual collection.
Opaque managed downloads preserve the source bytes, including already-compressed archives. The agent file-transfer GET and server Exchange download GET disable HTTP compression at the route level; managed host downloads request identity encoding and reject an unexpected Content-Encoding before checking size and SHA256. This source correction has actual HTTP regression coverage and requires matching controller/host deployment. The source also separates bounded transfer work from inventory and client heartbeats. Existing total transfer budgets remain hard; actual bytes renew only bounded idle time, and queued TTL is captured against local monotonic time. Source validation is separate from deployment. FileGrant delivery still does not prove that a running provider can read or has loaded the delivered file.
FileGrant synced proves delivery, not provider readability or loading environment variables into a running process. New Project grants default to 0640; delivery uses directory ownership root:19999 with mode 2750 and group-readable files. Historical explicit modes do not change automatically. Encrypted Secrets and Files are separate copies with separate rotation. A provider can remain alive while SSH terminal transport is offline. A manually started SSH tunnel is not managed or reconnectable merely because a ResourceGrant exists. See operations (source access required).
New managed-file and FileGrant identifiers are bounded opaque hashes of their exact identities. Long paths and different paths that sanitize to the same text do not collide. Reattaching an existing exact source preserves its legitimate saved identifiers; existing grants and queued revocations are never silently renamed or truncated. Metadata, grants and revocation commands are validated before persistence or removal. An invalid legacy entry requires explicit repair.
Host command readers isolate malformed persisted commands into durable failed results before dispatch. The result retains a payload hash and bounded structural diagnostics, without copying arguments or credentials. It does not prove that an older attempt had no effects or that a requested cleanup succeeded. Unrelated valid commands keep their identities, ordering and authority fences. A failed command poll yields to full host reconciliation instead of starving inventory.
.devctl.yaml may declare Project → Service dependencies. manual grants access without starting the Service; ensure-running raises its desired state. Unavailable required dependencies degrade health without stopping the Project container.
Agent Packs extend bundles with provider-neutral Skills, short documents/rules and MCP catalog entries. .devctl/skill-sources.json registers local directories and HTTPS Git repositories; ./devctl skills sync imports versioned contents into the controller catalog. Import alone does not expose a Skill to sessions: global, runtime-template, Project and session bindings determine an immutable launch snapshot. New containers mount a host-managed skills root at /run/devctl/skills; $DEVCTL_SKILLS_PATH and native provider links expose it to the session. Skills are separate from bidirectional Exchange. Provider adapters materialize snapshots in native config.
Generated DEVCTRL.AGENTS.MD describes the controlled Docker environment, observed CPU/RAM/process limits and network boundary, detected executables, enabled context tools, runtime paths, grants and aliases. Session-private DEVCTL.RULES.md includes the guide and requires reading its live version. Claude receives it through --append-system-prompt-file; Codex uses its managed profile's model_instructions_file. A live update queues a generation-fenced reread notification rather than restarting the provider. Shared-container tool updates refresh each session's checkout without copying another repository's permissions. Repository-owned instructions remain separate. See runtime instructions.
Session Settings and Launch Profiles are existing controller entities exposed by shared React navigation, not another configuration subsystem. Settings follows Project → repository → agent → session: repository/provider defaults retain global/tracked/local precedence, while selecting a session identifies only the exact restart target. Launch Profiles saves a new-session recipe; it grants no access and its CPU/RAM values guide placement. User snapshots include operator-managed global defaults and base template metadata for inspection, with edits restricted to the user's own scopes. See session configuration.
The MCP data path is AI agent → devctl-mcp-bridge → session Unix socket → host-agent broker → built-in MCP / sandboxed external MCP. It does not give the Project a host-agent API. Durable session sockets use short opaque host aliases to stay below Linux AF_UNIX path limits. The controller decrypts only the selected server/profile credential for the trusted broker; provider config and agent shell do not receive it. Built-in tools derive scope from signed session identity. Mutations require persisted approval unless an applicable existing permit authorizes them.
External stdio MCP requires a pinned image@sha256 and runs in an ephemeral Docker sandbox with no mounts, host filesystem, Docker socket or network, a read-only root, dedicated UID and bounded resources. Networked external MCP uses HTTP with a fixed catalog URL and trusted authentication bridge.
Network and MCP access history uses a separate indexed metadata journal in the existing controller database. Egress gateways emit bounded structured stdout; an independent host collector reads recent records and forwards a bounded retry outbox. Actual Docker endpoint observations distinguish Project/DinD network origins, never an arbitrary session in a shared container. Managed MCP brokers and built-in tools record exact authenticated session scope. The controller resolves ownership and deduplicates source IDs, serves separate paged history/server-side address summaries and exports resumable JSONL or WebSocket feeds. It reuses Events retention/stream settings; ordinary state snapshots contain no history dump. Proxy records are HTTP/CONNECT visibility, not a packet log of direct traffic blocked by the isolated bridge. No URL paths, credentials, MCP arguments or result bodies are retained. Access history.
The local admin MCP separately exposes typed skills_* operations for sources, Git updates, sync and bindings. They run native devctl on the operator machine with source-directory access and are not session tools. TUI Skills uses the same manager through a bounded IPC bridge; source directories are not mounted in the controller or TUI. skills_catalog and skills_sources expose exact catalog/registry metadata.
The optional native S3 read gateway uses the operator machine's AWS CLI credential chain. An explicit bucket allowlist, client endpoint and Project grant expose a stable TCP alias and separately delivered bearer token, never AWS credentials or presigned URLs. It supports bounded list/head/get operations. Client-agent repairs transport after reconnect, but access still requires the source machine, route and token; an active ResourceGrant alone does not prove S3 responds.
Decisions API (source access required) is optional and uses independently installed provider packages. Enabled purposes include bounded operator advice, approval-risk review, changelog importance and delegated-model routing where the native provider supports it. Settings, per-project/provider budgets, history and API-equivalent cost estimates share controller state; unconfigured or failed evaluations do not invent a verdict or block ordinary session work. Actual subscription savings are not measured. Provider-native limitations and accounting rules remain explicit in the provider documentation.
Long-running managed sibling containers are separate from MCP sandboxes and DinD. Host-agent creates them with explicit mounts and ownership labels. Session shutdown.json defines cleanup for restart or full completion; see session shutdown for retention and validation.
The same manifest also supports reviewed live task cleanup. A ready-only
operation binds the exact manifest hash and selects only readyForCleanup
entries. It preserves the session and manifest, restricts file deletion to its
non-root-owned TMPDIR through pinned directory handles, and rechecks DinD owner
and stopped state without forced removal. Host siblings and shared checkout
paths are excluded from live cleanup. Successful cleanup invalidates cached
workspace disk measurements.
Native SessionEnd, confirmed PTY exit and two consecutive missing-process observations can queue durable session cleanup. Claude /clear and /resume are conversation switches, not full process exits. Ordinary exit retains the persistent workspace container. Explicit workspace/Project deletion processes authorized manifests first, then removes owner-matched runtime, DinD and egress containers; unfinished siblings defer deletion. Volumes, account stores and retained configuration require separate storage decisions. Cleanup has no global prune or automatic tracker of every agent-created file.
Independent devctrl and Project runtime upgrades
toolchain upgrade updates installed Claude/Codex CLIs inside selected running containers without replacing them or stopping provider processes. New sessions resolve the latest release, install it from a host-prepared cache when necessary and launch an immutable versioned executable. Session launch versions, currently installed container versions and image labels are separate observations.
Optional context tools reuse the same durable host command queue, container update lock, version observations and official changelog review. User-private template defaults are snapshotted into Projects; containers can override the selection. RTK OSS, sgrep, ast-grep, Repomix and Graphify artifacts are downloaded or compiled once per host/release/architecture/build specification without Project mounts or credentials. Live publication changes only managed executable links; immutable wrappers keep version-specific assets available to running tools. Image preparation creates a cached overlay over an inspected base, separately from container replacement. Optional observations do not delay primary inventory or terminal attachment. Graphify additionally retains checkout-local graph policy: explicit Git storage and manual, post-commit or pre-push code refresh. A shared dispatcher checks each native worktree's policy; existing hooks and ignore rules are preserved. Automatic refresh runs inside the development container, never on the host, and does not invoke semantic model extraction.
toolchain rebuild-image prepares immutable runtime images separately. It may update management components when their source fingerprints differ; --build-only preserves Project containers and sessions. Existing containers are reused unless replacement is explicitly requested. Queue wait is part of step duration, and persisted operation scope binds ↻ UPDATING markers to the selected Projects and containers. See reuse checks and diagnostics.
Provider packages
External API/SDK implementations live in packages/provider-*, loaded through versioned manifests. Compute, cloud VM, Git, Decisions, public tunnel and managed service are separate capability contracts; none redefine agent/session identity. Missing packages leave durable history intact. See provider packages.
Shared terminal/browser application
The native Ink entrypoint and static React DOM entrypoint compile the same
apps/tui/src/app.tsx and screens. Platform adapters own input, layout, operator
state/actions and terminal transport. The browser calls the controller API through
an authenticated remote gateway; it does not run a server dashboard PTY. See
universal UI for build, deployment and authorization boundaries.
Terminal clients attach directly by managed session ID over the authenticated WebSocket, without fetching the full state snapshot. The controller resolves the current workspace and process name, checks ownership or sharing, and sends the authorized display label. Explicit workspace/name parameters from older clients remain supported and must match that session exactly. Public session links use a separate metadata allowlist for the display label, repository basename, state, native model/effort, short parent goal and active-child count. This header updates on the same authorized terminal channel without exposing account identities, runtime paths, grants or private child records. See shared sessions.
Terminal attachment reports fixed terminal.progress stage identifiers from the
host over the authenticated terminal channel. The controller binds each stage to
its host and stream, strips arbitrary payload fields, and ignores stages after
terminal.ready. The CLI worker and browser adapter render the same React
opening panel with per-step elapsed times. Native Ink stays mounted so wizard
state survives a failed attach. Input is held until readiness; early terminal
output is buffered up to 1 MiB. Cancelling a pending browser socket-ticket lookup
cannot create a late socket; cancelling during controller preparation prevents
opening a host terminal. Cancelling an attach closes its transport, preserving the
persistent provider process. Startup transport waits are bounded at 120 seconds.
Session policy requests reuse MCP approvals and canonical Agent Documents.
request_permission is never authorized by an autonomous Run permit; operator
approval binds the document to the requesting session and queues a durable
session.permission.apply command. The host writes private live rules as the
session UID, then notifies the provider to reread them. Delivery status and
operator retries are shared by TUI/web; see session permissions.
Server authority and optional application users
The standalone controller can be the remote authority for both terminal and browser clients, independent of a local laptop. Controller identities are common to both modes: local access automatically selects one operator, while server invitation mode enables multiple users; physical workspaces/accounts keep immutable ownership and cross-user container reuse is forbidden. Aggregate per-user/per-host launch admission and verified cgroup placement are separate from measured resource use. Existing local operator mode is preserved. See implemented scope, setup and limitations and the target architecture and migration plan (source access required). Controller transfer uses drain/fence, host acknowledgements and reviewed epochs; copying the active database never authorizes a second writer.
Memory admission and placement
Controller requests share a bounded resident cache and protected operation
reservations. Admission checks both total V8 heap usage and old-generation usage
against their own limits. The --max-old-space-size setting limits the old
generation; transient young-generation allocations are not charged against that
limit a second time. If generation statistics are unavailable, admission falls
back to the conservative total-usage check. Genuine pressure still returns a
retryable CONTROLLER_MEMORY_PRESSURE response before accepting a mutation.
Workspace placement uses the selected workspace's memory limit, which can be lower than its repository default. Measured host memory already includes running containers. The scheduler reserves additional memory for queued starts, subtracts their observed consumption, and releases that reservation when a command leaves the queue. A failed start does not reserve memory indefinitely. These placement checks do not replace per-user aggregate quotas or enforced container limits.
Live access policies and folders
MCP Policies intersects group/repository/session restrictions with the immutable launch allowlist and admits managed calls against durable rate counters. Folders uses owner-scoped grants, source-host file RPCs and bounded measured payloads. Gateway attachment is live; native binds reserve a dedicated container and require verified Docker/kernel flags. Neither feature introduces another account system or bypasses controller ownership. Server Exchange reuses that file transport for browser/native transfers without a laptop mirror.
Permission notifications execute independently from long host work and serialize per session/generation. Withdrawal retires the original command and session policy binding, then removes the exact written exception; cancelled results cannot re-authorize it. History and written-rule cleanup status remain durable.
Shared agent subscriptions
An account grant creates a separate user-owned profile pointing to one subscription pool. The host prepares only authorization JSON before a new provider starts; it never shares the source account store, transcripts or a physical container. Official quota observations update the common pool and user projections. Revocation prevents new starts; existing provider attach is unchanged and cleanup waits for process absence. Workflow and boundaries (source access required).
Frozen sessions
Projects supports Freeze / Thaw (Shift+F), independently of Hide and Detach. The server saves the last terminal screen, stops the exact agent process, retains native history and the original account/profile, and resumes through the existing durable launch path. Frozen has its own tab; empty Frozen, Hidden and Quota tabs are omitted. Temporary compute requires a verified encrypted S3 archive and recovery index. See Freeze and thaw for recovery and storage boundaries.