Agent protocol

One controller serves the Ink and DOM clients in both local and server deployments. It assigns ownership to commands, and the execution host preserves that ownership; request arguments cannot override it. A client disconnect leaves the native provider identity and workspace intact. Permanent operator credentials and expiring user logins have separate WebSocket lifetime checks.

Subscription preparation uses a plan containing authorization metadata only. The owning host copies approved authentication files before starting a new provider process; attaching to a running session does not copy them again. See authority and users and shared accounts (source access required).

Project interchange telemetry uses a separate bounded channel. A client credential authorizes POST /v1/clients/:id/sync-progress only for its own client ID; operators read GET /v1/sync-progress. The controller filters Project/host pairs against current placement. Strict schemas allow at most 128 Project rows, 16 current files per row and 512 characters per path; control characters and invalid/non-finite percentages are rejected. This is observational metadata, not execution authority or proof of hash equality. Clients publish every second during transfer and every five seconds when idle, independently of heavy heartbeats. Telemetry failures do not stop Unison. TUI uses the same adaptive polling without loading a full snapshot or persisting progress in SQLite.

Host desired state includes Services and pending file deployments. service.reconcile/restart commands never persist plaintext secrets; a host-bound endpoint supplies effective runtime environment only to the owning agent. Heartbeats include best-effort accelerator inventory and actual Service state/health.

During inventory collection and long commands, an authority-checked five-second liveness pump uses the existing /v1/agents/:id/liveness endpoint. Its optional fresh CPU, RAM and filesystem sample has a separate metricsObservedAt; it does not advance inventory sequence or container/resource evidence. inventoryObservedAt records the required container/process observation before optional nested Docker accounting, which has an eight-second limit and reports unavailable usage on timeout. Fresh transport or host metrics cannot make stale inventory valid for resource admission or termination confirmation.

Optional nested process probes start after storage collection and overlap primary container reads. Their completed readings expire after 30 seconds before merging; expired or failed readings remain unknown. Nested Docker HTTP accounting also has a total eight-second budget and publishes no partial inventory on expiry. Required storage and process collection can still delay a cycle; the existing session observation expiry remains unchanged.

Client-agent registers file-source metadata and receives only explicitly desired FileGrants. It validates roots, paths, symlinks and limits, hashes files and opens bounded binary streams. The host applies backpressure, verifies expected size/SHA-256, fsyncs, atomically renames and acknowledges the hash. The controller stores transfer metadata/status only.

Protocol 1.0 uses HTTPS/WebSocket over outgoing connections. A host credential authorizes metrics and Docker inventory/discovery, typed commands and results. Terminal messages include session kind and account identity, never OAuth data. terminal.ready commits attachment; until then the Session stays detached. terminal.exit or terminal.error closes the viewer and returns the CLI to TUI without removing Session, Workspace or Project. Attach preparation failure likewise retains the detached Session so inventory and retries can recover it.

Only foreground provider processes prove a live managed session. Claude daemons and background PTY workers may survive after the main CLI exits and do not prove a terminal or tmux remains available. The controller joins processes by internal workspace ID, provider and session name. Two consecutive heartbeats without the foreground process move a previously running session to exited; continuation uses its saved official provider session ID.

session.shutdown is a typed command for per-session shutdown/<session-id>.json. Native SessionEnd, confirmed PTY exit or confirmed detached-process absence queues it independently of the UI. Claude /clear and /resume do not authorize full-exit cleanup. Managed configuration/container restarts preserve exit-only resources. Managed sibling launch requires approval, persists host ownership and returns command/resource IDs. Pending health defers cleanup; only explicit data paths may be deleted. An ordinary session exit retains its workspace; explicit workspace/Project deletion removes owned runtime and sidecar containers after successful cleanup. See session shutdown.

Client-agent has a separate client credential and reports runtime, tunnels and reachability. It receives only its resources, grants, forwards and workspace targets and reconciles SSH -R/-L after reconnect. Admin routes require an AdminCredential; host and client credentials cannot substitute for each other.

Offline heartbeats do not delete desired resources. Cross-host TCP uses transient controller WebSocket relay with bounded buffering/backpressure; native SSH forwards use their own transport. A successful heartbeat does not prove a terminal channel is alive, and ResourceGrant active does not prove upstream connectivity or application login.

Client SSH masters keep working channels across controller process restarts and temporary API errors. Listener changes use incremental OpenSSH control requests. An authenticated desired-state refresh renews a 120-second lease; expiry or an explicit authorization rejection closes the transports without stopping native provider sessions. The execution host reports client-route health through POST /v1/agents/:id/resource-grants/:grantId/health, authorized only for its own client-backed grants. Route health is distinct from listener reconciliation; the latter cannot turn a failed route green. Checks traverse the grant relay to the upstream, are bounded and credential-free, and expire after 60 seconds.

File acknowledgements prove size/hash delivery, not readability by the provider UID/GID or a running process's environment update. New Project grants use the Project group and explicit mode, while historical 0400 grants do not broaden automatically. A secret grant does not replace FileGrant delivery; normal state exposes references/metadata only. Manually started native tunnels are not automatically reconciled. See operations (source access required).

Host-declared Service lifecycle is executed only by the owning host-agent from its local services.d declaration. The controller supplies desired state and active-consumer count. json-v1 start returns bounded state JSON, atomically stored on the owning host and passed to health/stop through stdin. Only runtimeState and health return to the controller; script paths, PIDs/container IDs and runtime-private state do not enter wire state. on-demand starts for active grants; after revocation the agent stops only the process identified by its own saved lifecycle state.

Managed AI terminal attachment includes the immutable Agent configuration snapshot, signed session-scoped MCP identity and only the credential material referenced by that snapshot. This is available to the trusted owning host-agent, never the Project shell. Host-agent creates persistent session Unix sockets and starts the MCP child only after the provider bridge connects. Generated provider config contains socket paths, not credentials or session tokens. Built-in MCP uses its token only for /v1/mcp/tools; Project scope never comes from arbitrary tool arguments.

Session policy approvals

request_permission creates an operator decision in the existing MCP Approvals list for permissions without a typed Service mutation. Approval binds a policy document to that exact session and queues session.permission.apply; delivery updates live rules and notifies the running agent without restarting it. get_permission_status distinguishes approval from delivery. Commands are deduplicated and serialized per session/provider generation; a busy native composer leaves its command pending while other sessions continue. Native submission acknowledgement is required before delivery is confirmed.

Terminal readiness reports its selected process generation; recovering a live process from a transport error does not allocate another generation. Historical counter drift is repaired only after consecutive observations of the same container, account UID, PID, process start and execution scope. Accepted launch receipts and active replacements fence that repair. Only unchanged pending requests or already-approved requests failed specifically by that counter drift are rebound; successful deliveries and other errors retain their original scope.

withdraw_permission_request cancels only the caller's policy request. The controller retires its approval command, removes the Agent Document/binding and queues removal of the exact written exception. Host execution checks command authorization again; a runtime marker prevents old retries from submitting or rewriting a withdrawn exception. Late approval results cannot resurrect it. History records withdrawn/cancelled; withdrawalStatus separately reports pending, removed or failed. See session permissions for workflow, retry and limits.

User-scoped execution and folders

In optional server-user mode the controller derives ownership from authenticated identity, not request arguments. Commands preserve that identity through host execution. Aggregate resource reservations precede launch, and a fresh host observation precedes releasing them. Separate users cannot share a container, sidecar, HOME or account store. Server protocol and authority transfer.

Managed MCP calls also pass live method/tool policy and rate admission. Folder RPCs carry a session identity, resource ID and bounded operation; the source host reauthorizes current grants before execution and returns measured payload bytes without retaining file contents in controller history. MCP policies, folders, user Exchange.

Context tools

get_context_tools reads the current container's effective RTK OSS, sgrep, ast-grep, Repomix and Graphify selection and observed/image/latest versions. configure_context_tools creates a structured one-shot approval for apply or prepare-image, with optional complete enabled selection from rtk, sgrep, ast-grep, repomix and graphify; [] disables managed links. Retry exact approved arguments; the target cannot be changed by an agent. Durable host execution preserves live sessions. The default setup skill and context-tools guide document use, caches and limits. Operator MCP additionally exposes context_tools for private template defaults, Project defaults and prepared-image inspection/configuration.

get_context_tool_releases reads official per-release notes using a tool ID and observed fromVersion; optional toVersion limits the range. It does not install tools or make a paid Decisions call. Operator MCP context_tools supports action: "releases", and CLI uses context-tools releases TOOL_ID FROM_VERSION [TO_VERSION] for any of the four tool IDs.

Runtime guide delivery

The host writes DEVCTRL.AGENTS.MD with environment observations and enabled-tool usage. Session-private startup rules include its contents and the requirement to read the live file. Native launch configuration delivers those rules as model instructions, not a task typed into the composer. Repository-owned devctrl.md, AGENTS.md and CLAUDE.md are preserved.

For live tool changes, authorized session.files-synced commands refresh the Context tools section in each session's own checkout before native reread notification. Commands recheck live session/generation authorization; no permission scope or process environment is implicitly broadened. Successful notification does not prove the model obeyed every instruction. See runtime instructions.