Sandboxes and the execution model

One task, one sandbox

Every task maps to one sandbox. Inside it there is exactly one supervisor, which is the authority for dependency graph state and scheduling, though several independent agent sessions may run in parallel.

The supervisor and the agent runtimes run inside the sandbox. Each attempt uses its own worktree and its own session, and never edits a shared workspace directly.

Where the line falls

The control plane is responsible for:

• validating that the skills, models, extensions, coding drivers and base resources a flow references exist;
• creating, observing and cleaning up sandboxes;
• proxying connections from the web console into the sandbox's agents;
• persisting task-level lifecycle and the final delivery references;
• deciding that a task has failed once its sandbox is terminated, lost, or past the missed-connection grace period;
• providing the delivery node with controlled push and change-request tools.

The supervisor is responsible for: the dependency graph, attempts, node sessions, artefact references and UI event sequence numbers.

State authority

This is the key to understanding the whole model.

The control plane persists task-level state only: the task identifier, task-level status and the tenant creator; the repository, baseline commit, task branch and frozen flow version; the sandbox identifier and the key timestamps; and the final artefact archive, code commit, remote branch and change request references.

The control plane does not persist nodes, attempts, rework, sessions, messages or dependency graph checkpoints. All of that is held by the supervisor inside the sandbox, in a local transactional log.

The consequence is that dependency graph state, sessions, artefacts and the code worktree sit in one failure domain. The model stays simple, and consistency is easy to guarantee.

The cost this accepts

The design has explicit costs, and they should be stated plainly.

Permanently losing a sandbox fails the whole task. There is no recovery from a node checkpoint, and no restoring the dependency graph into a replacement sandbox. A brief agent disconnection does not immediately change the task outcome — the control plane may show a transient unreachable health state — but the task only enters failure once the sandbox provider confirms the instance is lost or the grace period has elapsed.

Long tasks hold their sandbox continuously, and do not release it while waiting for user input.

If the sandbox disappears at the same time as a failure, any artefacts not yet archived cannot be recovered.

Requiring cross-sandbox recovery in future would need a new architectural decision; the local transactional log cannot simply be promoted into a distributed state machine.

Execution boundary

The sandbox provider owns creation, observation, binding and cleanup of the runtime environment. The default provider uses the Kubernetes Agent Sandbox; the runtime class is frozen by deployment policy, with the local environment omitting it and standalone isolation verification selecting a stronger execution boundary.

A task freezes the provider identity, plugin version, template reference, image digest and capability digest, and the provider is never hot-swapped while it runs.

Every production provider must pass the same contract tests: create, observe, renew, terminate, clean up, idempotency and lost-connection semantics.

Credential boundary

The control plane creates a minimal private secret for the task, carrying the member model keys and controlled connector credentials that task needs.

Credentials use least-recipient injection: member model keys go only to the runner and the supervisor, local extension credentials go only to the corresponding sidecar, and remote extension credentials go only to the proxy sidecar. The agent main process never holds extension credentials directly.

The task secret is deleted once every sidecar and runtime is ready. Runtime configuration consumes secrets by environment variable reference; cleartext is never written into configuration files, the specification, events or logs.

Ordinary key rotation affects new tasks only; emergency revocation takes effect by terminating the affected sandboxes.

Network and capabilities

The task runtime permits outbound traffic in order to reach the frozen model and Git targets directly. Fine-grained egress policy and proxy governance belong to later security design.

Skills and extensions can only come from the local registry. The sandbox forbids fetching capability code from the public internet through a package manager at start-up. Skills are downloaded from the registry by an init container, verified and unpacked onto a read-only shared volume; local extensions are pre-assembled as sidecars by image digest.

A task enters the running state only after all required skills have been materialised, the local extension sidecars are ready, remote extension connections are complete, the runtime and node configuration have validated successfully, and services are ready. A required capability that is missing must surface as a capability gap before the sandbox is created; a materialisation failure at run time ends in a structured failure.

Lifecycle and retention

Images, Pod compute specifications and maximum retention belong to deployment-level runtime policy, not to a workspace, project, repository or personal setting. The control plane holds a singleton runtime policy configuration and applies the current revision when a task is created.

Each task freezes its revision, runner image, CPU and memory requests and limits, and maximum retention. Every node and rerun of that task reuses that same copy. A policy update affects later tasks only, and cannot drift an existing environment in place.

The retention window starts when a task is first observed as completed or failed. Within the window the environment, services, node files and agent sessions remain readable, and failed nodes remain rerunnable. Runtime resources may be deleted only when the user deletes the task, or when the expiry reclaimer confirms the lifecycle deadline has passed. Control plane recovery, orphan discovery, manual reclamation and recovery failures are not grounds for destruction.

After reclamation, the final task snapshot, node results, code revisions and change request metadata are still retained.