> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/isolation-and-sandbox.md). # Isolation And Sandbox Boundary Last updated: 2026-06-26. ## Purpose FactionOS records local observability, diagnostics, queue intent, and guarded-action decisions. It also ships bounded local File/Git and Session 12 terminal/container command-center subsets. Those subsets are local-only, registry-gated, idempotency-guarded, timeout-bounded, and redaction-scoped. They do not create a general shell, Docker, remote, Worker, hosted, or browser-to-terminal execution claim. This document is the source-backed threat model for implemented executor subsets, unavailable execution posture, and future executor work. Future executor sessions must use this document together with the API contract, package README files, and Phase 06 baseline artifacts before adding or expanding any execution capability. ## Current Runtime Boundary The current local runtime can: * Accept hook events through `/event`. * Maintain local heroes, missions, notices, achievements, task queue entries, mission graph state, agent templates, and guarded-action proposals. * Record guarded-action approval or rejection decisions. * Return compact local diagnostics for orchestration and isolation posture. * Report unsupported route families through deterministic 501 envelopes. * Run allowlisted local Git workbench operations through the command-center Git route, with timeout, redacted summaries, and policy-blocked push by default. * Probe optional PTY readiness and run scoped terminal sessions through the Session 12 terminal manager when the PTY adapter is ready. * Probe Docker and Apple Containers readiness and run a guarded local isolated spawn only when required container gates pass. The current local runtime cannot: * Perform arbitrary local file reads, writes, edits, diffs, deletes, moves, or opens outside an approved scoped implementation. * Run arbitrary git status, commit, push, branch, worktree, checkout, remote, or repository commands outside the allowlisted Git workbench path. * Run arbitrary shell, terminal, process, subagent, Docker, container, or VM commands outside the Session 12 terminal/container command-center routes. * Open remote access, browser-to-terminal bridges, Worker command bridges, or inbound webhook command channels. * Execute hosted queue jobs, hosted agents, hosted diagnostics, analytics actions, push actions, or public replay jobs. * Provide trusted unified erasure for Worker state, browser hints, archives, exports, replay buffers, diagnostics, logs, backups, valid spool state, or future hosted data. ## Source Evidence | Evidence | Source anchors | Conclusion | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Phase 06 isolation baseline | `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md`, `.spec_system/archive/phases/phase_06/phase06_requirement_routing_matrix.md` | Executor families need consent, authorization, audit, rollback limits, redaction, tests, and docs before any operation moves out of unavailable posture; unimplemented operations still fail closed. | | Protocol ownership | `packages/protocol/src/guardedActions.ts`, `packages/protocol/src/rest.ts` | Shared contracts own guarded-action families, unavailable reasons, REST route family names, and compact unsupported envelopes. | | Server boundary | `apps/server/src/managers/guardedActions.ts`, `apps/server/src/lib/unsupportedRoutes.ts`, `apps/server/src/routes/diagnostics.ts` | Approval records a decision and returns unavailable; unsupported routes return compact 501 envelopes without body echo. | | Session 12 terminal/container contracts | `packages/protocol/src/orchestrationCommandCenter.ts`, `packages/protocol/src/isolation.ts`, `apps/server/src/managers/terminalSessionManager.ts`, `apps/server/src/managers/containerRuntimeManager.ts`, `apps/server/src/routes/terminalContainers.ts` | Terminal and container execution is implemented only through manager-owned local routes, optional PTY/runtime probes, bounded output, safe attachments, idempotency locks, and structured unavailable states. | | CLI and hook boundary | `apps/cli/src/lib/orchestrationDiagnostics.js`, `apps/hooks/src/_lib.js`, `apps/hooks/src/ws-listener.js` | Diagnostics summarize counts, labels, durations, and sanitized identifiers only. Recovery is narrow and explicit. | | Local-first ADR | `docs/adr/0001-local-first-npm-workspace.md` | Hosted accounts, Docker, remote runners, and provider credentials are not core runtime prerequisites. | ## Session 12 Terminal And Container Boundary Terminal and container execution is no longer an all-family unavailable label, but it is deliberately narrow: * Terminal readiness comes from `TerminalSessionManager.probe()`. The PTY adapter is the required native `node-pty` dependency; if it fails to import or probe on the local host, terminal status is unavailable with `pty_unavailable`. * Terminal command text and terminal input are request-scoped. They are validated for length and null bytes, and blocked raw field names are rejected at the route boundary. * Terminal output is bounded by byte cap and line metadata. It may appear only in the selected `CommandCenterTerminalSession` detail surface. Broad command center rows, WebSocket snapshots, diagnostics, exports, replay, Worker transfer, docs examples, and logs must use safe summaries and attachment metadata only. * Terminal lifecycle operations are `preview`, `run`, `input`, `kill`, and `restart`. Mutations use route-level in-flight locks and optional idempotency keys. Cleanup runs on exit, kill, restart, timeout, and server shutdown. * Container readiness probes Docker and Apple Containers independently, plus image state, browser dependency state, auth mount, worktree mount, network profile, provider runtime, cleanup posture, docs path, and fallback reason. Probe output is summarized as labels and booleans, not returned raw. * The default local image is `factionos-isolated:latest`, built from `docker/factionos-isolated/Dockerfile` with `npm run isolation:image:build`. * Isolated spawn preview does not start a container. Isolated spawn run is local-only and requires ready runtime gates. Missing Docker, Apple Containers, image, mount, browser dependency, network, or provider runtime state returns unavailable or preview-only posture. * Task queue and campaign container dispatch are not separate Docker command surfaces. They route `executable.kind: "container"` through the same manager-owned isolated-spawn boundary, preserve expected-revision and duplicate-trigger guards, and expose only compact queue/execution metadata such as runtime, cleanup posture, container run id, unavailable reason, retryability, and recovery guidance. * Session 12 does not add remote access, Cloudflare Tunnel, browser-to-terminal bridging, Worker command bridging, hosted queues, hosted agents, public replay execution, broad Docker build pipelines, or trusted rollback for terminal side effects. ## Executor Family Boundaries Executor design treats each family as a separate capability, not as a generic "safe local action" bucket: * `file`: file read, file write, file edit, diff, open, delete, move, and workspace path inspection. * `git`: status, diff, commit, push, branch, checkout, rebase, merge, worktree, and remote configuration changes. * `terminal`: shell commands, process launches, package scripts, process termination, subagent spawning, and background tasks. * `container`: Docker, container, sandbox, VM, volume mount, network, image, and cleanup operations. * `remote`: SSH, tunnel, IDE remote, browser-to-terminal, remote runner, and cross-machine command surfaces. * `hosted`: hosted queues, hosted agents, analytics jobs, public replay jobs, push channels, inbound webhooks, and account-backed automation. An implemented subset does not imply the whole family is safe. Until a later session implements a specific operation, that operation's posture is unavailable. Approval must not be interpreted as execution unless the matching executor entry is executor-ready and the request passes its enforcement gates. ## Required Future Threat Model Sections Before any new executor family or expanded operation ships, the owning session must define: * Capability scope and explicit denied operations. * Consent and user-visible approval language. * Authorization and trust boundary checks at the nearest enforcement point. * Idempotency and duplicate-trigger behavior. * Audit records that avoid raw sensitive payload transfer. * Rollback and compensating-action limits. * Redaction rules for diagnostics, logs, exports, replay, Worker frames, archive state, backups, and hosted transfer. * Timeout, retry, cleanup, and failure-state behavior. * Test evidence for unavailable states, blocked inputs, no raw echo, and no mutation on diagnostic routes. ## Consent Requirements Future executor consent must be explicit, visible, and scoped to the smallest action that can be understood by the operator. Consent cannot be inferred from opening the app, joining a room, accepting a War Room participant, approving a mission plan, enabling diagnostics, or running `factionos doctor`. Every executable action must show: * The executor family. * The operation class. * The bounded target label. * The risk level. * The expected mutation. * Whether the action can be rolled back automatically, manually, or not at all. * The idempotency key or duplicate-action protection state. Consent copy must avoid raw prompts, command bodies, terminal output, full paths, tokens, diffs, patches, queue entries, or proposal rationale. Approval records intent only unless the specific executor family is implemented and the runtime confirms that all enforcement checks passed. ## Authorization Requirements Authorization must be checked at the enforcement point nearest to the protected resource. UI state, browser localStorage, Worker participant role, CLI flags, hook payloads, and request bodies are hints only. They must not authorize local file, git, terminal, container, remote, or hosted mutation by themselves. Minimum authorization checks for future executors: * Local server auth must pass before executor routes are considered. * The executor family must be enabled by configuration and visible posture. * The requested operation must be allowlisted for the family. * The target must be inside the allowed scope for that family. * The caller must present a fresh approval record with expected revision or equivalent replay protection. * Duplicate actions must return the original outcome or a compact conflict. Hosted or Worker authority must not be reused as local execution authority without a dedicated bridge threat model and tests. ## Audit Requirements Audit records must support operator review without becoming a data leak. Future executor audit entries should record: * Action id, executor family, operation label, requester label, decision label, timestamps, idempotency key, and result status. * Bounded target labels rather than full paths or command bodies. * Failure codes and unavailable reasons. * Redaction boundary version or policy label. Audit records must not store raw prompts, command bodies, terminal output, file contents, diffs, patches, broad paths, tokens, transcripts, raw queue entries, proposal rationale, raw spool payloads, state files, logs, backups, archives, browser state, Worker payloads, or hosted account data. Container queue and campaign audit records must also reject raw Docker command text, raw container output, env maps, entrypoints, args, mounts, volumes, image-inspect payloads, and workspace paths. Safe image labels and runtime labels are metadata only; they are not permission to run arbitrary Docker operations. ## Idempotency And Concurrency Requirements Every future state-mutating executor operation must have duplicate-trigger protection. A double click, retry, reconnect, stale browser tab, duplicate hook fire, repeated CLI command, or Worker replay must not execute the same mutation twice. The minimum behavior is: * Create and decision paths accept idempotency keys or equivalent operation identities. * In-flight mutation locks protect shared state. * Stale revisions return compact conflicts. * Retried completed actions return the prior compact result. * Timed-out external dependencies have a visible unknown or unavailable state until reconciliation proves the final outcome. ## Rollback Requirements Rollback support must be family-specific. It cannot be described as trusted erasure or guaranteed reversal unless the implementation proves that claim. Examples: * File writes may need backup files, patch inversion, or manual recovery guidance. * Git operations may need a safe local ref snapshot and explicit warning when remote pushes cannot be rolled back. * Terminal operations may have no reliable rollback after external side effects. * Container operations may clean temporary containers and volumes, but mounted workspace mutations still need separate file rollback. * Hosted operations may need provider-specific deletion and audit evidence. When rollback is unavailable or partial, the UI, CLI, API response, and audit entry must say so before execution. ## Redaction Requirements Redaction is boundary-specific. A value safe for a route label is not automatically safe for a log, export, replay, Worker frame, archive, CLI screen, hook spool entry, or hosted payload. Future executor work must define separate redaction rules for: * API responses and errors. * WebSocket frames. * CLI and hook output. * Local logs. * Archives and backups. * Exports and replay buffers. * Worker transfer. * Hosted transfer. Every boundary must block the redaction categories listed in the protocol isolation contract unless the owning session explicitly proves a narrower safe subset with tests. ## Validation Requirements Future executor validation must include both success and fail-closed tests. Before any executor is marked shipped, focused tests must prove: * Unsupported families still return deterministic unavailable or 501 envelopes. * Diagnostics remain read-only and compact. * Invalid, stale, duplicate, expired, unauthorized, and policy-blocked actions do not mutate state. * Raw prompts, commands, paths, tokens, outputs, logs, backups, state files, and spool entries are not echoed. * Timeouts and dependency failures return visible compact outcomes. * Idempotent retries do not duplicate mutation. * Rollback behavior is either proven or explicitly unavailable. ## Current Diagnostic Contract Isolation diagnostics may return only compact metadata: * Status labels such as `unavailable`, `non_executing`, `deferred`, `offline`, `auth_required`, `timeout`, and `available`. * Executor family labels. * Bounded counts. * Capability flags. * Documentation paths. * ISO timestamps. * Terminal readiness labels such as PTY availability, safe shell/cwd labels, active session count, timeout, output cap, cleanup posture, and fallback reason. * Container readiness labels for Docker, Apple Containers, image, browser dependencies, auth mount, worktree mount, network profile, provider runtime, cleanup posture, and fallback reason. Isolation diagnostics must not return raw prompts, provider prompts, command bodies, terminal output, stdout, stderr, file contents, diffs, patches, broad paths, cwd, transcript paths, tokens, authorization values, request bodies, raw queue entries, proposal rationale, raw spool payloads, state files, logs, backups, archives, browser storage, Worker payloads, or hosted account data. ## Current Recovery Boundary CLI recovery is local diagnostic cleanup only. It can remove stale listener PID files and malformed spool JSON entries after an explicit operator flag. It must not delete valid spool entries, settings, lifecycle files, sessions, archives, memory, browser state, Worker state, backups, workspace files, or all `~/.factionos` data. ## Validation Expectations Current validation should prove: * Guarded-action approval is family-specific and executes only when the matching executor entry is ready. * Unsupported and unimplemented route families return deterministic unavailable or 501 envelopes without raw echo. * Server isolation diagnostics are compact, auth-protected when auth is configured, and read-only. * Terminal routes reject malformed and raw-field payloads, fail closed when PTY support is unavailable, cap output, clean resources on exit/kill/restart/ timeout/shutdown, and keep broad execution records attachment-only. * Container routes reject malformed and raw-field payloads, summarize Docker and Apple Containers probes without raw output, return unavailable or preview-only states when gates are missing, and guard isolated spawn against duplicate in-flight runs. * CLI status and doctor output include isolation posture without raw local payloads or trusted-erasure claims. * Hook diagnostics stay silent, timeout-bounded, sanitized, and non-executing. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/docs/isolation-and-sandbox.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.