Workcell

Unreleased Wave C: normative assurance profile and portable commitment vectors now define the existing local predicate for alpha and proposed opt-in beta envelopes. No stable execution contract or default admission changes.

Unreleased experimental addition: local Git effect assurance prototype, separate from stable execution and preservation.

Workcell 1.1 is a stable local and CI execution harness for bounded Kujo and agent workflows on Docker or Podman. It creates a disposable Git worktree, validates a declarative execution definition, applies bounded container resources and filesystem access, enforces an explicit network policy, exports only declared artifacts, records a structured receipt and integrity manifest, and performs ownership-scoped cleanup.

The repository also contains an additive alpha provider-neutral contract: workcell-definition/v2alpha1, workcell-backend/v1alpha1, and workcell-receipt/v2alpha1. Docker and Podman implement that contract through the existing stable OCI lifecycle. Digest-pinned external adapters for E2B, Vercel Sandbox, and Daytona are separately installed, strictly capability-negotiated, ownership-recoverable, and receipt-visible. gVisor and Kata are OCI runtime selections, not provider adapters. Offline conformance is not live-provider or security certification. See backend adapters.

The container boundary defines what is physically reachable. Kujo defines what is authorized, observable, verifiable, and exportable.

The v1 guarantee is deliberately narrow. It covers the local Docker/Podman CLI, definition, receipt, verification, artifact, cleanup, and recovery contracts documented in this repository. It does not protect against a compromised daemon or host kernel, provide microVM isolation or hosted multi-tenant execution, provision organization-specific egress infrastructure, govern operator images or signing keys, set retention policy, or confer compliance or enterprise certification.

Supported contract

Workcell 1.1 supports:

• disposable Git worktrees and isolated-clone workspaces from clean repositories;
• strict, versioned JSON definitions with safe defaults and unknown-field rejection;
• Docker and Podman execution with bounded CPU, memory, PIDs, time, output, mounts, and writable paths;
• explicit none, default, or pre-created custom network selection plus a recorded egress declaration;
• declared artifact export, structured receipts, SHA-256 integrity manifests, and offline verification;
• label-scoped container cleanup, ownership-marked workspace cleanup, timeout recovery, and explicit failed-workspace preservation.

Supported host classes are Linux with Docker Engine or rootless Docker/Podman, and macOS with Docker Desktop or Colima. Windows and unsupported Unix hosts are outside v1. Run workcell doctor on every target host; host file sharing, user namespaces, seccomp/AppArmor, DNS, proxy, and firewall behavior remain deployment-specific. See platform compatibility.

Requirements and installation

• Kujo 1.2.1 at commit 692512a9070fdba713f160d795bbddb8077db7b5 (the exact pin is in RUNTIME_VERSION).
• Git and jq.
• Docker for the default backend, or Podman on a supported Linux host.
• A clean Git source repository for execution. Workcell refuses dirty sources by default so it cannot silently omit user changes.

Workcell is distributed as a source archive and can also run directly from a checkout:

git clone https://github.com/kujolang/workcell.git
cd workcell
git checkout v1.1.0
export KUJO=/path/to/kujo-1.2.1/kujo
./bin/workcell --version

The v1.1.0 tag contains the stable source release. Its Docker and Podman lifecycle remains the stable contract. The provider-neutral definitions, backend protocol, portable receipts, and remote adapters included in the source remain alpha until each provider passes live certification. The launcher reads KUJO and does not download or replace the runtime.

Quick Start

export KUJO=/path/to/kujo-1.2.1/kujo
docker build --tag kujolang/workcell-base:local docker/
./bin/workcell init
./bin/workcell validate --file workcell.json
./bin/workcell inspect --file workcell.json --json
./bin/workcell run --file workcell.json --repo . --no-pull
./bin/workcell verify --run .workcell/runs/<run-id> --json

Agent hosts can use workcell run ... --summary for one compact workcell-run-summary/v1 JSON object containing the verdict and evidence paths without embedding the full receipt. The receipt and integrity manifest remain authoritative.

workcell init creates a restrictive starter definition. inspect resolves policy without starting a container. run creates a temporary Git workspace and writes evidence under .workcell/runs/<run-id>/. For Podman, set runtime.backend to podman and follow the identity guidance in platform compatibility.

Portable backend quick start

The v2 workload stays provider-neutral; the host profile selects compute. This example resolves through built-in Docker without installing an adapter:

./bin/workcell validate --file examples/portable/workcell.json
./bin/workcell inspect \
  --file examples/portable/workcell.json \
  --profiles examples/portable/host-profiles.json \
  --profile docker \
  --summary
./bin/workcell run \
  --file examples/portable/workcell.json \
  --repo . \
  --profiles examples/portable/host-profiles.json \
  --profile docker \
  --summary

Switching profiles changes the provider, not the workload contract. Remote profiles and explicit adapter manifests are documented in backend adapters. Unsupported security or resource requirements fail before provisioning; Workcell never silently substitutes provider defaults.

Agent-efficient interface

Agents should use inspect --summary for a compact preflight and run --summary for the verdict and evidence pointers. These emit single-line workcell-inspect-summary/v1 and workcell-run-summary/v1 objects without commands, mounts, secrets, full capability ledgers, logs, or embedded receipts. Read receipt.json only when detailed evidence is needed, and use verify --json before trusting persisted evidence. Pass correlation through a bounded workcell-caller-context/v1 file with --context; never put credentials or provider options in caller context.

Stable CLI surface

Command	Contract
doctor	Check Kujo, Git, selected backend, engine security signals, repository, temp directory, and dangerous environment overrides.
init	Create a starter workcell.json; refuse overwrite unless --force is explicit.
validate	Parse and validate a definition; --schema emits workcell-definition/v1.
inspect	Render resolved mounts, resources, environment names, backend, and security arguments without execution.
run	Execute validate, prepare, launch, collect, verify, export, record, and clean.
verify	Verify a run directory's workcell-manifest/v1 hashes offline.
clean	Inventory or remove only Workcell-owned containers and workspaces; images require --prune-images.
backends	List built-ins and explicitly supplied external adapter manifests.
recover	Reconcile a durable external-backend journal without deleting resources whose ownership does not match.

Global --help and --version are stable. Command-specific options and unexpected positional arguments fail with usage code 2. The machine-readable CLI and exit-code contract is available from workcell help --json.

Output and exit codes

Each completed lifecycle writes the applicable evidence:

.workcell/runs/<run-id>/
├── receipt.json
├── stdout.log
├── stderr.log
├── integrations/
├── changes.patch
├── changes.json
├── manifest.json
├── preservation.json
├── handoff-bundle.json (when requested and reconstructable)
├── execution-result.json
├── reexecution.json
├── reexecution-input.json
└── artifacts/

The receipt separates Workcell product version, definition version, execution, verification, artifact export, and cleanup results. It records secret names but never intentionally stores secret values. workcell verify detects changes to immutable evidence.

Failed-run preservation emits kujo.preservation-outcome/v1. The outcome separates requested from actual mode, names the provider and cleanup owner, and states reconstructability and limitations. --keep-failed maps to filesystem; --preservation-mode handoff_bundle writes a clean-source-plus- patch handoff manifest. Snapshot and live-pause requests report unsupported unless a backend supplies them. --retain-until records an operator-owned UTC deadline; it does not claim provider-side erasure. After the deadline, an operator can run workcell clean --preservation <preservation.json>; Workcell revalidates the exact ownership marker and writes a separate deletion receipt outside the immutable run manifest. --dry-run previews the exact target. Remote/provider deletion continues through the provider recovery contract, not this local-filesystem command.

Every non-dry execution also emits kujo.execution-result/v1 plus a kujo.reexecution-descriptor/v1. The descriptor retains normalized inputs and secret references, never secret values. Workcell promises inspectability and, when source and inputs are present, a new re-execution attempt. It does not promise deterministic replay. Network-enabled runs record external effects as unknown and require operator policy before retry.

Portable runs use receipt v2. Its controls ledger distinguishes requested, accepted, enforced or provider-claimed, observed, unsupported, and unknown state. A provider name or marketing claim never upgrades an enforcement status.

Exit	Meaning
0	Completed successfully.
2	Usage or definition validation failure.
3	Git/source dependency or workspace preparation failure.
4	Backend or image preparation failure.
5	Container startup failure.
6	Timeout.
7	Workload command failure.
8	Verification or artifact export failure.
9	Cleanup failure.
10	Internal Workcell failure.

The workload's own exit code remains in receipt.json; the Workcell exit code identifies the lifecycle category.

Security posture

The default contained-standard profile uses network none, a non-root or rootless-mapped identity, a read-only root filesystem, bounded resources, no-new-privileges, dropped Linux capabilities, private IPC, no devices or host namespaces, no daemon socket, explicit environment passing, and one disposable workspace mount. Only declared artifacts leave the workspace.

Network access must be explicit. Workcell records the egress declaration but does not install firewalls, control DNS, or force arbitrary child processes through a proxy. For release deployments, use reviewed image digests, signature keys, registry allowlists, and host-enforced egress where required.

Containers are not universal isolation. Workcell trusts the selected engine and host kernel. Higher-risk or multi-tenant workloads need an operator-provided VM, gVisor/Kata class runtime, microVM service, or equivalent stronger boundary. Read the security model, enterprise deployment boundary, and known limitations before deployment.

Compatibility and upgrades

Workcell follows semantic versioning for the product. The workcell-definition/v1, workcell-cli/v1, workcell-receipt/v1, workcell-manifest/v1, and other evidence identifiers are independent contract versions; product 1.1.0 does not rename them. Additive fields may appear within a v1 contract. Removing or repurposing a field or exit code requires a new contract identifier and migration notes.

Patch releases contain compatible fixes. Minor releases may add optional CLI or schema surface with safe defaults. A future product major may change supported contracts only with changelog and migration guidance. Pin both the Workcell release and Kujo runtime commit for reproducible automation. See the API compatibility policy.

Verification

Run the offline release gates with the pinned runtime:

export KUJO=/path/to/kujo-1.2.1/kujo
./bin/workcell --help
./bin/workcell --version
./bin/workcell validate --file workcell.json
KUJO="$KUJO" ./tests/version_consistency.sh
KUJO="$KUJO" ./tests/run.sh
KUJO="$KUJO" ./tests/quality.sh
KUJO="$KUJO" ./tests/release_report.sh
./tests/markdown_links.sh
git diff --check

For an explicitly selected source-runtime compatibility run, set WORKCELL_TEST_KUJO_VERSION=1.5.0 alongside KUJO when invoking the tests. The override checks that exact reported version; it does not change RUNTIME_VERSION, Docker pins, or certify a release on that runtime. Release validation must leave the override unset.

Docker and Podman integration, concurrent-load, egress, doctor, cleanup, self-proof, receipt verification, and ShipCheck commands are documented in development and the release process.

Release and support boundary

GitHub source archives and the versioned source archive, checksums, provenance record, and release report produced by the tag workflow are the supported v1 release artifacts. The workflow publishes no container image, hosted runner, package registry entry, or hosted execution service. Target-host hardening, image governance, key custody, evidence retention, egress infrastructure, and organization-specific compliance remain operator responsibilities.

Use GitHub issues for reproducible defects in the supported v1 contract. Security reports follow the private process in the security model. The exact pre-tag and rollback procedures are in the release process.

Documentation

• Architecture
• Backend adapters
• Backend adapter authoring
• Live provider certification
• Remote provider operations
• Official adapter distribution
• Provider operations: E2B, Vercel Sandbox, Daytona
• Boat integration research and current build gates
• Backend matrix research and implementation package
• Backend matrix productionization mega prompt
• API compatibility and machine contracts
• Workcell definition
• Runtime lifecycle
• Platform compatibility
• Security model
• Security review
• Known limitations
• Enterprise deployment boundary
• Development
• Release process
• Launch checklist
• Examples

Workcell is licensed under the MIT License.

Unreleased experimental addition: controlled Git process participant, with one-use admission and content-addressed correlation. Dispatch remains replay authority; the existing Git CAS predicate is unchanged.