Interactive Terminal Driver

​

The nine tools

​

Prerequisites

​

Configuration

agents:
  default:
    provider: openai-codex
    model: gpt-5.5
    skills:
      terminal:
        enabled: true
        worker:
          maxSessions: 4
          idleTtlMs: 1800000          # reap idle sessions after 30 min
          ringBytes: 1048576          # per-session output ring (1 MiB)
          stuckMs: 60000              # no-progress > 60s ⇒ "stuck" ⇒ escalate
          maxConcurrentAttentionTurns: 2
        defaults: { cols: 120, rows: 40, scrollback: 5000 }
        allow:
          # A no-network shell, locked down (least-privilege).
          - id: bash
            match: { path: /usr/bin/bash }     # canonical binary (realpath/hash-pinned)
            scope:
              filesystem: workspace            # only the session workspace is writable
              network: none                    # deny-all egress
              credentialPaths: []              # no credentials exposed (least-privilege)
              uid: dedicated                   # run as a throwaway uid, not the daemon
            autoAnswer: safe-only
            consent: { acknowledgedRisk: true, acknowledgedAt: "2026-06-14T00:00:00Z" }

          # Drive an interactive AI CLI (Claude Code here, but the driver is TOOL-AGNOSTIC).
          # filesystem: home because (a) the claude binary is home-installed
          # (~/.local/bin/claude -> ~/.local/share/...), which filesystem: workspace cannot
          # reach -- the jail only execs a binary its filesystem scope binds; and (b) claude
          # WRITES ~/.claude (session state + OAuth token refresh), which a read-only
          # credentialPaths bind would block. credentialPaths (RO) instead suits a CLI that is
          # system-installed AND only reads its creds -- see the credentialPaths note below.
          - id: claude
            match:
              path: /home/comis/.local/bin/claude   # canonical binary (realpath/hash-pinned)
              argsPrefix:                            # operator-pinned: the agent cannot change the permission mode
                - --permission-mode
                - bypassPermissions
            scope:
              filesystem: home                 # binds the home-installed binary + RW ~/.claude state
              network: full                    # reach the model API
              credentialPaths: []              # not needed -- filesystem: home already exposes ~/.claude (RW)
              uid: daemon                      # run as the daemon user so it owns its (comis-owned) creds
            autoAnswer: safe-only
            consent: { acknowledgedRisk: true, acknowledgedAt: "2026-06-14T00:00:00Z" }
            limits: { wallClockMs: 7200000, maxInteractions: 800 }
        redactSecrets: true
        audit: { enabled: true }
        # unsafeDisableSandbox: false   # DANGEROUS opt-out of the bwrap jail (see Security model).
                                        # Only for hosts that cannot run bwrap; leave false otherwise.
        drive:                          # autonomous-drive policy (optional; omit ⇒ today's behavior)
          mode: auto                    # auto (default) | attached (never promote) | detached (promote at first wait)
          readMode: digest              # digest (default) | diff | full — the woken-turn read shape
          durable: true                 # default — detached tmux: survive a daemon restart, re-attach + resume (false ⇒ non-durable pty)
          heartbeatMs: 90000            # internal liveness backstop (default 90s) — not a poll, not a user message
          maxCostUsd: null              # per-drive spend ceiling in USD (null = uncapped)
          notify: terminal              # which outcomes reach you: terminal (default) | all (reserved; today == terminal) | none — see Notifications
          heartbeatNotifyMs: 3600000    # user "still working" heartbeat for a long drive (default 1h; 0 = terminal-only)

​

Allow-entry fields

​

Security model

• ~/.comis carve-out (non-dialable): the daemon data dir (master key, secret store) is masked with a tmpfs in every jail, even at filesystem: full. A driven child can never read Comis’s secrets.
• Fail-closed: if the declared scope cannot be materialized (no bwrap), session_create is rejected — never degraded to an unsandboxed child. The one operator override is unsafeDisableSandbox (below).
• unsafeDisableSandbox (default false, DANGEROUS): the operator opt-out of the jail — the peer of browser.noSandbox, for constrained hosts that genuinely cannot run bwrap (a container without unprivileged user-namespaces, a locked-down CI box). When true, session_create runs the driven CLI directly instead of failing closed, with no filesystem / network / uid confinement (the scope dimensions are unenforceable without the jail). Two protections are still enforced and never optional: the env-scrub still strips daemon secrets (gateway token / master key) from the child env, and a durable backend: "tmux" drive is force-downgraded to the non-durable PTY backend (a tmux server would inherit env the jail’s per-session --unsetenv normally strips). It is surfaced at boot in comis fleet config-posture (terminalUnsafeDisableSandbox), and it is operator-file-only: no runtime RPC can set it — neither config.patch (the whole agents.* prefix is immutable there) nor agents_manage / agents.update (which otherwise writes agent config) — so an admin-trust agent can never self-enable it; only editing the config file and restarting the daemon can. The same file-only rule covers skills.execSandbox (the exec OS-sandbox switch) and skills.terminal.allow (the command allowlist). Leave it false on any host where bwrap is available.
• The binary must be in scope: the jail can only exec a match.path that its filesystem scope binds. A binary under /usr rides the system RO base; a home-installed binary (e.g. ~/.local/bin/claude, the standard install) is reachable only at filesystem: home (or listed-paths including its dir) — filesystem: workspace cannot exec it.
• Env-scrub: interpreter-control vars (NODE_OPTIONS, BASH_ENV, PYTHONSTARTUP, function-export) and nested-CLI markers (CLAUDE_CODE_*, CLAUDECODE) are stripped.
• Untrusted output: terminal_session_read redacts secrets and wraps the screen as untrusted external content — a driven AI CLI can render attacker text, so the screen is treated as a prompt-injection vector, not trusted input.
• Audit: every send_text/send_key is audited (sessionId + redacted payload); a run is reconstructable from logs + events.

​

Workspace and persistence

• The session working directory is <agent-workspace>/projects — ~/.comis/workspace/projects for the default agent, ~/.comis/workspace-<agentId>/projects for a named agent — with each named project under projects/<name>. A full, multi-hour run (e.g. driving Claude Code to build a project) leaves its output there after the session ends.
• Because it lives inside the agent’s workspace, the agent’s other tools (read/write/apply_patch/exec, which operate on the same workspace) can see and continue the driven session’s work.
• The ~/.comis carve-out still masks everything else under the data dir — the secret store, config, and the agent’s other workspace files (identity, skills, memory). Only the terminal subtree is re-bound read-write inside the jail, so the driven child is confined to it (least-privilege) and can never reach Comis’s secrets.
• filesystem: workspace (the default) binds exactly this directory. The directory is created on first use and is world-writable so a jailed child running as a net-new uid (uid: dedicated) can write it; at uid: daemon the child owns it directly.

​

Network modes

• none — deny-all egress. Best for shells/tools that don’t need the network.
• full — unrestricted egress. The bwrap jail + the ~/.comis carve-out + env-scrub are still the boundary. This is the mode for driving a full-screen AI CLI (e.g. Claude Code), whose HTTP client reaches the model API directly.
• listed-hosts — a no-secret host-allowlist CONNECT proxy bounds the child to named hosts. It works for clients that honor HTTPS_PROXY. Driving a CLI whose HTTP client ignores HTTPS_PROXY through listed-hosts is still being hardened (a transparent-egress path) — use full for those today.

​

Long runs and recovery

• Session lifetime is decoupled from a turn. session_create returns immediately; the PTY lives in the worker across turns. Aborting the spawning turn does not kill the session.
• The agent is woken by attention events, never polling: the worker classifies each session and emits a terminal:* event on a state transition; a short woken turn does status -> read -> decide -> send -> ends. The terminal:input_needed and terminal:stuck wake events carry the classification confidence and reason alongside the state (consumed by the autonomous-drive policy and surfaced in a comis explain of a drive) — both are redaction-safe machine tags, never raw screen bytes.
• Worker crash isolation: the worker is a separate supervised process — a PTY/emulator crash restarts the worker, not the daemon. For long, multi-hour runs use backend: "tmux" so the session survives a worker restart and a human can tmux attach to take over.
• Surviving a daemon restart (not just a worker crash) is the job of a durable drive (drive.durable: true): the driven CLI runs in a detached tmux server that outlives the daemon, and on restart the drive re-attaches to the live session and resumes from its journal instead of being lost. See Durability & resume below.

​

Autonomous drive (drive config)

• drive.mode — auto (default) / attached / detached. Controls auto-promotion: a drive starts attached (inline and snappy), and on the first terminal_session_wait that returns not-complete-but-still-producing (the CLI is honestly still working, not done) it auto-promotes to a detached, journaled drive-owner running in its own isolated session scope. From then on its woken turns no longer touch the primary conversation; only the drive’s terminal outcome bridges back. Promotion emits exactly one “drive started (backgrounded)” notification.
  • auto — promote on that honest still-producing signal (the recommended default).
  • attached — never promote; every woken turn stays inline, byte-identical to today.
  • detached — promote at the first wait once the drive has been given a task (a delivered send_text). A wait issued before any task has been sent keeps the drive inline: an un-tasked drive has no work to background, and backgrounding it would strand an idle terminal + persist a wake-state that resurrects on the next daemon restart. (The recommended order is task-then-wait, so in normal use this still promotes at the first wait.)
  • A sub-threshold one-shot (git status, ls, a quick build that finishes before the first long wait) stays inline and allocates nothing — no detached scope, no journal, no notification. There is no behavior change for a drive that was always short.
  • A finished, idle backgrounded drive is reaped at worker.idleTtlMs. When a backgrounded drive completes its work and settles at its prompt (awaiting-input), an unattended origin (a webhook/cron turn — one with no human to hand back to) has its idle drive evicted once it has been idle for idleTtlMs, so a finished unattended drive does not linger. An interactive origin’s drive is left alive (a human owns its lifecycle and may reply later; the completion is delivered as a notification). Either way, sending the drive more work (e.g. a follow-up webhook to the same session) before the cap re-attaches the live drive and resets its idle clock. Set idleTtlMs: 0 to disable idle eviction entirely.
    • Only a TRULY-idle drive is reaped, never one still autonomously producing. A coding CLI such as Claude Code parks its cursor at its persistent ❯ composer while it is still working — subagents running, an unattended build step in flight, the status timer/token counter advancing — which the classifier reports as awaiting-input. The idle-clock freeze that lets the reaper evict a settled drive is therefore gated on the on-screen render being unchanged across liveness probes: a changing screen (real progress) keeps the drive’s clock fresh so a long autonomous unattended drive (e.g. a multi-stage build that runs well past idleTtlMs with no operator keystrokes) is never evicted mid-work; only a static screen (a genuinely finished/idle drive) accrues idleness and is reaped. The change-detection uses a content-free digest of the render (never the screen bytes).
  This is distinct from the wall-clock auto-backgrounding of a long tool call (the “a long wait auto-backgrounds so the turn never blocks” behavior above). That mechanism keeps the agent’s own conversation turn from blocking on a slow wait, keyed off a wall clock. drive.mode instead controls where the subsequent event-woken turns execute, keyed off the honest still-producing settle signal — not a timer. They are orthogonal: one unblocks the calling turn, the other isolates the long drive.
• drive.readMode — digest (default) / diff / full. The shape of the screen read each woken turn performs.
  • digest — a bounded digest of the current rendered screen (the viewport grid, never scrollback), so each of thousands of 40h wakes stays cheap.
  • diff — only the rows that changed since the last wake.
  • full — the whole screen, still bounded (opt-in, for diagnosis).
  • Every mode is capped at a byte limit; an over-cap read writes a truncations breadcrumb (a count of dropped bytes) rather than silently trimming.

​

Durability & resume

• drive.durable — true (default) / false. The default true makes every drive durable: the driven CLI is launched inside a detached tmux server (a process independent of the worker, implying backend: "tmux" at runtime), so a worker or daemon exit leaves the CLI + its PTY running. This is the default because the tmux backend is both driveable (the worker attaches a real pty to stream + send keystrokes) and survive-a-restart (the deployed systemd unit ships KillMode=process and the tmux socket lives under the data dir, so the restarted daemon re-attaches; see systemd). On a host with no tmux it degrades to a non-durable pty drive + a WARN (not a config error). On daemon restart the session registry re-attaches to the live tmux session — matched by a stable per-drive name persisted in the journal — instead of flipping it lost. Re-attach never starts a second copy of the CLI (no double-drive). On daemon restart the session registry re-attaches to the live tmux session — matched by a stable per-drive name persisted in the journal — instead of flipping it lost. Re-attach never starts a second copy of the CLI (no double-drive).
  • Resume, don’t restart. A durable drive persists a compact, content-free rolling journal (the objective, the last classification, the prompts it has already answered, and the steps it has tried — never screen bytes or secrets) beside the agent’s workspace. On re-attach the drive resumes from that journal: it picks up where it left off and does not re-run from the top or re-answer a prompt it already answered. The journal files live under <dataDir>/terminal-drive/<agentId>/journals/ (see the data-directory reference).
  • A genuinely-gone session is reported failed, never silently restarted. If the tmux session is truly gone on restart (not merely detached), the drive surfaces as failed with its journal preserved for inspection — it is never quietly started over.
• spawn is non-durable (and that’s fine for short drives). The default backend dies with the daemon. A short or one-shot drive needs nothing more. A non-durable drive that is interrupted by a restart is honestly reported failed (with its journal preserved); it does not silently resume.
• Runtime fallback when tmux is unavailable. drive.durable: true is accepted at config load even on a host without tmux — tmux availability is a runtime property, not a config error. If tmux is missing (or a re-attach fails) at runtime, the drive degrades to a non-durable drive and logs a WARN; a subsequent restart then reports failed with the journal preserved, rather than a silent double-drive. It is never rejected at config-validation time, and it never silently widens scope.

​

Endurance & liveness

• Dialable caps — and a cap-eviction names the cap. limits.wallClockMs and limits.maxInteractions (under each allow entry) are operator-dialable; both are uncapped by default (undefined ⇒ no cap), so today’s behavior is unchanged and a long drive is not capped unless you set one. If you do set a cap and a drive reaches it, the eviction names the cap that fired in the failed reason (a deliberate operator bound, not a mystery) — and the idle reaper excludes a busy session, so quietness alone never evicts it.
• drive.maxCostUsd — a number / null (default null = uncapped). An optional per-drive spend ceiling in USD over the whole run. On breach the drive escalates and stops — never a silent overspend. It bounds cost only (it grants no privilege, path, or credential). Leave it null to run uncapped.
• drive.heartbeatMs — the internal liveness backstop interval in milliseconds (default 90000, i.e. 90s). This is a safety net under the event-driven wake, not a poll: on a tick where no wake intervened, it performs one liveness check (is the worker/tmux alive? is the child genuinely idle vs. CPU-busy or trickling output?) and synthesizes stuck only when the child is genuinely hung. A legitimately-busy multi-hour compile is busy, not stuck. It reads no screen (it is not a per-tick screen read), it fires only in the absence of a wake, and it resolves to a single check.
  drive.heartbeatMs is the internal liveness tick — not a message to the user. The user-facing “still working” progress notification is a separate knob, drive.heartbeatNotifyMs (see Notifications) — distinct from this internal backstop.

agents:
  default:
    skills:
      terminal:
        allow:
          - id: claude
            # ... match / scope / consent as above ...
            # Endurance-dialable per-session caps (omit ⇒ uncapped):
            limits: { wallClockMs: 144000000, maxInteractions: 20000 }   # ~40h horizon
        drive:
          mode: auto
          readMode: digest
          durable: true            # detached tmux: survive a daemon restart, re-attach + resume
          heartbeatMs: 90000       # internal liveness backstop (90s) — not a user message, not a poll
          maxCostUsd: 25.0         # per-drive spend ceiling (null ⇒ uncapped)
          notify: terminal         # which outcomes reach YOU: terminal (default) | all (reserved; today == terminal) | none
          heartbeatNotifyMs: 3600000  # user "still working" heartbeat for a long drive (1h; 0 ⇒ terminal-only)

​

Notifications

• done — a clean exit: the driven CLI exited at high confidence, or an explicit terminal_session_wait forText/forExit you set matched. Honest completion only — never fabricated.
• needs-you — an escalation: the auto-answer policy hit something it must not answer itself (destructive, an approval gate, an auth/login prompt) or the loop guard tripped. The drive parks awaiting you and notifies. This is the one outcome that always fires (see notify: none below).
• failed — a genuine death: an unrecoverable durable session (the tmux session is truly gone on restart, not merely detached — its journal preserved for inspection), or a named cap-eviction (a limits.wallClockMs/maxInteractions you set was reached, and the reason names the cap that fired). A healthy long or quiet drive is never failed — duration or silence alone never produces this outcome.
• drive.notify — terminal (default) / all / none. Which outcomes reach you.
  • terminal — you are notified only on a terminal outcome (done / needs-you / failed). The uninteresting middle — a safe prompt the policy answered itself, a still-working frame — stays silent. The recommended default.
  • all — reserved for a future per-wake debug stream; currently behaves exactly like terminal. The per-wake notification (a line on every answered/waited turn) is not yet implemented, so today all fires the same terminal outcomes as terminal and nothing more. Set it if you want the future debug behavior the moment it ships; until then it carries no extra noise.
  • none — the non-escalation outcomes (done, failed) and the heartbeat are suppressed. An escalation (needs-you) still fires. notify: none is not a security off-switch: it never weakens escalate-always (an auth/approval/destructive prompt always reaches you) or the loop guard. It silences only the routine outcomes.
• drive.heartbeatNotifyMs — a coarse “still working” progress heartbeat to you for a promoted (long) drive, so a 40-hour build is not 40 hours of silence. Default 3600000 (1h); 0 = terminal-only (no heartbeat). It is a bounded one-liner from the drive’s journal (still working — elapsed Xh, last activity <digest>, N interactions, ~$Y). A short (unpromoted) drive emits none. This is distinct from drive.heartbeatMs (the internal liveness backstop — not a user message); the two are independent knobs.
• Every notification is content-free. A notification or heartbeat carries the outcome/reason/errorKind, the duration, the interaction count, and a redacted final-screen excerpt — never raw TUI bytes, keystrokes, or secrets. The heartbeat digest is drawn from the content-free drive journal, and a driven AI CLI’s screen is treated as untrusted (a prompt-injection vector), so its text never rides a notification verbatim.

​

Classifier reliability

​

Platform profiles

• Render — it strips Claude Code’s dim autocomplete “ghost-text” from the captured screen so a driving model never mistakes the suggestion for queued input.
• Perception — it feeds the classifier the platform’s working-line (Claude’s spinner, Codex’s Working (Ns)) and picker/menu signatures, so a busy frame reads working and a /model-style picker reads awaiting-input rather than stuck.
• Dialogs — it declares the platform’s known interactive dialogs and their safe answer. Under autoAnswer: safe-only a non-destructive dialog (Claude’s “trust this folder” gate) is answered with the canned keystroke; a destructive dialog (Codex’s run-command approval) always escalates to you. The operator safe-only policy and the escalate-always veto still gate every answer — a profile only proposes.

1. Create packages/skills/src/tools/builtin/terminal-driver/platforms/<id>/profile.ts exporting a TerminalPlatformProfile — id, the operator allowIds it claims, a platformVersion, and any of the optional read-side fields (transformSnapshot for render, perception pattern lists, dialogs).
2. Register it in platforms/index.ts (ALL_PROFILES). The load-time guards reject a duplicate allowId or a ReDoS-prone pattern.
3. Add the paired bundled skill packages/daemon/bundled-skills/<id>/SKILL.md with a frontmatter version equal to the profile’s platformVersion (a build-time architecture test enforces the match).
4. Capture golden frames and assert the profile’s transform/perception/dialogs against them (live with the profile, e.g. platforms/<id>/profile.test.ts).

​

Related