Architecture decisions

These decisions summarize the choices most relevant to adopters and operators. They explain what Sandbox Loom promises today and where the MVP remains intentionally narrow.

Policy survives runtime changes

Authority is defined separately from the isolation technology. This protects workflow and policy decisions from a change in runtime.

Youki first, runc fallback

Youki is the preferred first Linux OCI backend. If it is unavailable, the selector tries runc. A caller that explicitly requires one runtime receives an error instead of an unexpected fallback.

Explicit session profiles

The active profile is supplied by sandbox/session configuration. Gateways do not infer autonomous-development or any other workflow profile.

Keep the first deployment simple

The initial control plane is a Ruby modular monolith, with a clear boundary around disposable work. Separate services are deferred until scale, operations, or credential isolation justify them.

Keep credentials outside disposable work

External credentials are managed outside the disposable workspace and exposed only through controlled, scoped access.

Make workflows reviewable

Versioned YAML backed by JSON Schema is the canonical workflow format. It supports review, IDE validation, and predictable planning. A future Ruby composition DSL must produce the same representation and cannot bypass policy.

The full normative decision records are maintained in the repository specifications/decisions/ directory.

Model providers are opt-in

Live model access is never an accidental side effect. Provider credentials, tool permissions, usage limits, cancellation, and audit behavior must be configured explicitly.

Evidence is part of the workflow contract

Verification, checkpoints, audit events, published artifacts, and acceptance results are treated as workflow outputs rather than informal operator notes. This makes an automated result reviewable and gives a paused or recovered run an explicit continuation boundary. A workflow that cannot state what evidence it must retain is not ready for broader authority.

Expand by concrete workflow

New integrations and deployment targets are deferred until a concrete workflow, authority model, failure behavior, and operating procedure are defined. This keeps the local MVP small while allowing the policy, gateway, broker, and backend boundaries to evolve without changing the core operating model.