Architecture

This document explains Sandbox Loom for operators, adopters, and decision makers. It focuses on responsibilities, trust boundaries, and operational tradeoffs.

1. Introduction and goals

Sandbox Loom turns an explicit objective into verified work while keeping authority outside the disposable execution environment.

The primary goals are:

• give agents only the authority needed for the current task;
• keep work isolated from the host and external systems;
• make decisions and results reviewable;
• support pause, recovery, and human escalation;
• provide a reusable model for controlled automation.

The MVP is local-first. Hosted multi-tenant operation and unrestricted deployment automation are not current promises.

2. Operating model

• People and policy define authority before work begins.
• The workspace is disposable and treated as untrusted.
• Every consequential action is checked before it occurs.
• External effects are mediated rather than exposed directly.
• Ambiguous or unsupported requests stop instead of receiving broader access.

The operating model is intentionally workflow-first. A workflow describes the objective, dependencies, checks, and evidence to retain; the selected session profile and policy determine what the workflow is allowed to do. This keeps intent, authority, execution, and acceptance evidence reviewable as separate concerns.

3. Context and scope

flowchart LR
  User[User or orchestrator] --> Spec[Specification]
  Spec --> Loom[Sandbox Loom control plane]
  Loom --> Session[Sandbox session]
  Session --> Workspace[Disposable workspace]
  Loom --> Evidence[Audit and acceptance evidence]
  Loom -. escalation .-> Human[Human reviewer]

Sandbox Loom sits between a workflow owner and a disposable execution environment. External systems such as Git remotes, credential providers, ports, and deployment targets are reached through policy-governed brokers.

4. Responsibilities

The MVP keeps responsibilities explicit:

• policy decides what is allowed;
• the workspace performs bounded work;
• controlled integrations mediate external effects;
• the workflow verifies results and records evidence;
• people approve actions that exceed the session’s authority.

The implementation can evolve without changing this operating model.

5. Building block view

flowchart TB
  Loop[Closed-loop runner] --> Gateway[Capability gateway]
  Loop --> Planner[Planner / implementer / verifier adapters]
  Gateway --> Policy[Policy engine]
  Gateway --> Brokers[Brokers]
  Gateway --> Manager[Sandbox manager]
  Manager --> Backend[OCI backend selector]
  Backend --> Youki[Youki]
  Backend --> Runc[runc fallback]
  Manager --> Executor[Executor session]
  Executor --> Environment[Sandbox environment]
  Policy --> Audit[Audit log]
  Loop --> Checkpoints[Checkpoints and evidence]

These responsibilities do not imply separate products or services. They are boundaries that make the system easier to operate, review, and evolve.

6. Runtime view

sequenceDiagram
  participant W as Workflow owner
  participant L as Closed-loop runner
  participant P as Policy engine
  participant G as Gateway/broker
  participant S as Sandbox session
  participant E as Executor

  W->>L: Submit specification and acceptance criteria
  L->>S: Register profile, identities, expiry, backend
  S->>E: Establish outbound session
  L->>P: Evaluate requested capability
  P-->>L: Decision and constraints
  L->>G: Execute authorized operation
  G->>E: Request sandbox-side work
  E-->>L: Result and evidence
  L->>L: Verify, repair, checkpoint
  L-->>W: Acceptance evidence or escalation

7. What adoption means

Sandbox Loom is a control layer around agent work. It does not replace engineering judgment, code review, dependency review, or release governance.

For an adopting team, the important operating choices are:

• which workflows are allowed;
• which repositories and external systems are in scope;
• which profiles agents may use;
• which actions require approval;
• what evidence must be retained.

Start locally, keep authority narrow, and expand only after the workflow and evidence are understood.

A practical adoption review should answer four questions:

1. What objectives and repositories are in scope?
2. Which capabilities can the workflow request, and which require approval?
3. What verification and evidence are required before accepting the result?
4. How are paused, failed, expired, or externally affected sessions resumed or recovered?

The answers belong in policy, workflow configuration, runbooks, and acceptance criteria. They should not be inferred from the presence of a tool or runtime inside the workspace.

8. Current boundaries

• The MVP is local-first rather than a hosted multi-tenant service.
• Production persistence, enterprise credential management, and organization-wide policy administration require deployment-specific design.
• Additional integrations should be introduced only when a concrete workflow and its safeguards are defined.

See the security model, operations guide, and architecture decisions for practical guidance.

9. Glossary

• Capability — an operation an agent may request.
• Profile — the authority level selected for a session.
• Gateway — a controlled entry point for an operation.
• Broker — a controlled connection to an external system.
• Sandbox session — the lifecycle boundary around one unit of work.