Complete feature guide

Status: complete intended feature guide, reviewed against the feature milestones on 2026-10-12. This describes the product contract, including capabilities still in development. It is not a list of features available in a released product.

Cella gives an agent a private place to work, controls the authority it can request, and keeps attributable records of the resulting work. Its components share identity, policy, and lineage: a sandbox, proxy, log, or approval prompt alone does not provide the complete contract.

Start with components, explained if Cell, Wall, Gateway, Relay, or Workstream are unfamiliar. This page explains every requirement from the feature catalog, with additional detail from the Markdown requirements. The feature milestones own current completion gates. Examples describe intended behavior unless explicitly identified as implemented.

Every product name is defined in the glossary, including Channel, Connection, Link, Run Target, Service Revision, grants, leases, and evidence objects. Definitions link back to their feature scope and detailed guides.

How to read this guide

• Partial means some local code or tests exist; the complete integration or target-host acceptance gate is still open.
• Planned means the integrated capability is not delivered. A design or experimental parser does not make an authority path production-ready.
• Qualified requires evidence for the exact build, host, role, and generation. Agent and Service Cell protection are separate claims.

The current local shell, Service responder, and Channel slices are partial. A model-backed Codex/Claude workflow, private repository workflow, integrated policy engine, credentialed Effects, complete evidence ledger, and durable handoff remain incomplete. There is no completed account-free end-to-end product workflow yet.

The complete feature map

What needs to work together

Eight capabilities must work together before Cella claims its core product identity: Wall, policy as code, agent-independent cellad control, credentialless Connections and Gateway, governed project runtime, durable Workstreams and continuity, transactional repository workflow, and evidence with governed consequences.

The gate is one representative repository workflow, including an independent Service Cell and authorized Channel. Counting completed crates or building a Cloud interface does not substitute for a missing boundary. Ephemeral work crosses the same gate as retained work.

Agent isolation

Current status: partial. Authenticated control and local lifecycle/shell pieces exist. The live target-host and role-specific protection gates remain open.

Wall enforces the execution boundary of a Cell. Only enrolled cellad can ask it to create, inspect, stop, or destroy an admitted generation. The agent cannot choose host paths, arbitrary mounts, runtime sockets, or containment settings.

Isolation and resource limits

The initial asserted isolation target is gVisor/runsc on Linux, under the installed Debian runtime stack. Other runtimes must satisfy an explicit profile; a weaker development runtime must retain non-production status and refuse protected repositories instead of silently downgrading them.

The required profile includes a non-root UID, read-only root filesystem, dropped Linux capabilities, no-new-privileges, bounded temporary storage, and CPU, memory, process, I/O, time, and disk limits. Host home directories, sibling repositories, SSH agents, Docker sockets, devices, broad bind mounts, and inbound ports are not inherited. The privileged runtime helper remains narrow; cellad never receives unrestricted runtime authority.

Authenticated control and failure behavior

The Debian control contract requires a fixed root-created Unix socket, kernel peer credentials (SO_PEERCRED), dedicated service accounts, per-installation Rustls mutual TLS, exact service ALPN, and one controller lease. Wrong peers are rejected before application decoding. Transport authentication still does not replace method policy or the installed Cella Security Floor.

A limit violation stops or throttles the Cell and records its cause. Stop revokes capabilities and network identity before teardown. Destroy removes private writable artifacts according to retention policy. Required hostile tests cover traversal, namespaces, mounts, processes, exhaustion, wrong peers, replay, key rotation, controller takeover, socket replacement, and pre-decode failures.

Example: an agent may change its private src/server.go; a request for the host's ~/.ssh/id_ed25519 does not acquire a host filesystem route.

See Wall security, protected Cell contract, and runtime substrate.

External access and credentials

Current status: partial catalog, authenticated control, and model-access foundations. Project-bound Connections, typed provider adapters, a fixed-route HTTPS executor, and fail-closed exact-generation listener custody have local tests. The executor is not connected to an authorized Cell-origin path. Integrated model inference, provider-only egress, and external consequence execution remain unavailable.

A Connection names an approved external identity and credential source. Gateway uses that authority outside the Agent Cell. The agent requests a typed operation and receives a bounded result and receipt, rather than a token.

Connection catalog and credential resolver

A logical ID such as org/github-production records provider, owner, allowed operations, resource scopes, status, version, and a credential reference. Policies and agents refer to this stable ID. An administrator can rotate its backing credential or provider without changing the agent or policy source.

Credential resolution may use an OS keychain, encrypted Cella storage, Vault or another secret manager, workload identity, or provider-native dynamic authority. Short-lived tokens, workload federation, delegated signing, and dynamic secrets are preferred to reusable static credentials.

Connections have explicit active, disabled, rotating, and revoked states. Disable blocks new resolution and invalidates queued Effects and active capabilities. Renewal evaluates current policy again.

Model routes and typed connectors

A model route injects provider authentication only after a request leaves the Cell. Typed connectors cover approved GitHub, package, document, cloud, and Virtus operations. Arbitrary authenticated HTTP and a shell with credentials are not capability substitutes.

A grant binds organization, repository, Workstream, Run, Cell generation, Connection version, operation, resource, destination, parameter and candidate digests, budget, approval, and expiry. Cross-Run, cross-destination, stale, replayed, altered, disabled, or revoked requests fail closed.

Results have allowlisted bounded schemas, size limits, and redaction. Credential material must not enter agent memory, environment, files, process listings, prompts, output, logs, checkpoints, snapshots, artifacts, evidence, or control responses. Error and crash paths are part of that requirement.

Example external operation

Agent requests github.propose_change(candidate_digest, repository)
  -> cellad authenticates identity and evaluates policy
  -> deny, allow, or require approval for the exact digest
  -> Gateway resolves the authorized Connection outside the Cell
  -> execute exact operation and destroy or revoke temporary authority
  -> return redacted result and attributable receipt

The receipt binds Connection version, policy digest, request digest, and result digest. Retry must reconcile the operation instead of creating another external consequence. See credentialed effect flow and Approvals and external actions.

Run and test applications

Current status: partial independent no-secret Service and fixed Channel slices. Local tests exist; live two-Cell qualification, integrated policy, secret-bearing Service runtime, persistent data, and replacement remain open. Relay currently runs as a cellad child and needs privilege separation before a protected claim.

This capability lets the application run beside the agent under its own permissions. The agent's writable candidate is separate from a Service Cell's sealed runtime inputs, application secrets, and persistent data.

Run Targets

A Run Target is an approved command definition. Bounded project discovery suggests targets; the user selects or adds them. An approved digest binds the argument array, manifest, runtime, Secret Set, candidate scope, network, resources, command-change behavior, approval, and evidence requirements.

An agent asks for a target ID and candidate digest. It cannot supply a replacement command, environment, Secret Set, runtime profile, or network rules. Changes to command definitions follow configured allow, session, require, always, or deny behavior; they do not silently inherit an earlier approval.

Project Secrets and secret-bearing runtimes

Project Secret Sets contain application runtime values, such as database configuration. They are distinct from provider Connections. Importing .env values is a separate secret-boundary operation; .env never enters repository ingress, the Agent Cell, prompts, logs, checkpoints, artifacts, or evidence.

An exact Secret Runtime Binding projects approved values only to an eligible non-agent generation and lifetime. A secret-bearing Service has no attached agent, shell, debugger, or cross-process inspection. This prevents direct agent access to the secret; it does not prove that unreviewed application code cannot exfiltrate a value it receives. Secret-bearing code and permitted outputs need appropriate policy and review.

Services and Service Cells

A Cella Service is a named service identity and endpoint contract. A Service Cell implements it using an immutable revision or pinned artifact, approved Run Target, profile, network, resources, health definition, and explicit bindings. It can continue after the CLI or Agent disconnects.

A Connected Service is an enrolled endpoint running outside Cella, such as an existing database. Cella may mediate its traffic and observations; it does not claim that the external process is Wall-contained or that every other access path is governed.

Service observation can expose authorized redacted logs, metrics, traces, health, artifacts, and narrowly scoped restart/update operations. Source changes require a sealed candidate and a new service generation. Development policy may automate seal, build, health verification, and replacement; stronger policy may require an approved digest. A Channel transition to the replacement generation is explicit, and health-gated replacement and rollback are separate later gates.

Channels and Cella Relay

A Channel is a directional grant between exact endpoints. Cella Relay (cella-relay, sometimes called the relayer) carries only its authorized traffic. cellad authorizes the Channel; Relay does not own provider credentials or choose a destination from an agent-supplied URL, host, or port.

A Channel binds Project, named Service, source and destination generations, protocol, permitted operation, direction, policy digest, expiry, and connection, request, byte, and time limits. Provisioned endpoint identity is trusted; a payload cannot declare itself to be another Cell.

Agent generation -> authorized Channel -> Relay -> named Service endpoint
stop / detach / expiry / revoke -> Channel closes; Service may stay running

Intended paths include Cell-to-Cell, Cell-to-enrolled-local-service, and explicitly authorized local-client preview. A grant does not expose every service port, filesystem, environment value, or host route. Wrong generations, direct routes, stale grants, over-limit requests, wrong operations, and post-revocation traffic must fail. Restart and reconnect must not revive expired authority.

Network, packages, and tools

Admitted tools and lockfile-derived package access use governed paths with resolved digest receipts. Private networks, metadata endpoints, undeclared localhost, arbitrary DNS/IP/port/Unix sockets, redirects, and tunnels are denied. There is no general Cell networking, wildcard host bridge, runtime socket, SSH agent, or credential socket. If Gateway, Relay, or the secret boundary is unavailable, its governed path blocks while permitted local work can continue.

Persistent data and Analysis Job Cells

A Data Volume is declared Cella-owned mutable service storage. A Data Snapshot is an immutable point-in-time identity. A Data Grant authorizes a specific read-only projection; it is not arbitrary mount permission. Database-native backup or consistency procedures are required before treating live database state as a usable snapshot.

An Analysis Job Cell runs one approved bounded task against exact data, parameters, resources, network, secret binding, and expiry. It may have database authority the Agent Cell never receives. A classified, redacted, content-addressed Artifact can then reach an Agent Cell through an exact read-only Artifact Grant. Object Transfer verifies ingress/export by digest rather than exposing caller-selected host paths.

Service data -> consistent snapshot -> approved Analysis Job Cell
  -> bounded analysis artifact -> Artifact Grant -> Agent Cell

A policy may deliberately grant raw snapshot access to an agent, binding classification, snapshot digest, path, size, lifetime, model/provider policy, and network restrictions. Data visible to an agent can reach its model provider. Restricted data may instead require filtering, aggregation, a local model, an approved provider, or denial of raw access.

Example: the agent tests a backend's named endpoint through Relay. The backend uses its own database secret and volume. A separate analysis job returns only an approved report to the agent.

See service runtime and data, Channel flow, and Service milestone.

Permissions and policy

Current status: partial integrated policy slices. Restricted-YAML parsing, durable Project adoption, explanation/simulation, and exact shell, Service, Channel, and model grants are wired into cellad. Gateway Effects, Project Secret bindings, and complete cross-boundary enforcement remain incomplete. This is not the full proposed Policy Engine or complete workflow qualification.

Hierarchy and strict authoring

Effective authority intersects the installed Cella Security Floor with organization, Project, Workstream, Cell, and operation restrictions. A lower layer may preserve or narrow authority; it cannot widen an inherited boundary. Prompts, repository Markdown, model memory, and agent edits grant no authority.

A restricted YAML 1.2 authoring surface rejects duplicate keys, aliases, anchors, merge keys, tags, multiple documents, ambiguous implicit scalars, unknown fields, unsupported schemas, invalid destinations, unregistered operations, and over-limit structure. It normalizes into a format-independent policy IR; the original YAML bytes are not the authority representation.

Canonical compilation pins referenced profiles and operation definitions, produces an immutable digest, and retains source maps and provenance. Policy, template, or candidate changes invalidate stale approvals and Capsules.

Templates and custom operations

Versioned templates cover personal ephemeral work, repository review, development, PR authorship, service observation, and organization-restricted execution. They remain inspectable/editable convenience inputs, compile through the same hierarchy, and have no special authority.

Trusted installations or connectors can register namespaced versioned custom operations with bounded typed parameters, mediation classes, and exact mediator identity. Registration is not authorization. The catalog definition enters the Effective Policy digest; a repository cannot install mediator code or assign its own trust class.

Decisions, explanation, and simulation

A request includes actor, model, repository, Workstream, Run, generation, operation, destination, parameter digest, budget, and time. A decision returns allow, deny, or approval-required, plus matched rule, source, explanation, scope, expiry, and evidence requirements. Validation, explanation, simulation, and diffing must use the same evaluator as runtime decisions. Deny decisions and missing authority fail closed. Approval can satisfy only an exact permitted approval condition; it cannot override the Security Floor or an inherited denial.

Example: changing from Codex to Claude Code preserves the governing policy hierarchy, while requests are re-evaluated for the new actor, adapter, model, operation, and generation. The resulting grant may differ or be denied; handoff does not automatically broaden a Connection or inherit an earlier lease.

See Policy Engine and policy hierarchy.

Tasks and execution history

Current status: partial Workstream identity and Run/journal storage. Project-owned identity, owner-authored handoff notes, and immutable attempt records have local tests. The source-backed offline Run path fails closed without Wall protection proof; checkpoints, cross-agent handoff, and the complete durable workflow remain unavailable.

A Workstream is one intended repository change. Its immutable identities link Runs, Candidates, Checkpoints, Decisions, Approvals, Capabilities, budgets, Capsules, and final disposition. Organization/repository ownership, issue key, title, branch, and base are attributes; renaming an issue does not change identity.

A Run is one bounded execution attempt under an exact generation, adapter or job, policy, inputs, budget, and result lineage. It is not a Workstream, shell command, CLI invocation, or Run Target. Retry, resume, handoff, and fork create a child Run while preserving the parent. Actor-scoped idempotency covers create, resume, checkpoint, approval, and export. A policy-first logical Cell may exist before source, a generation, Run, process, or protected state exists.

Deliberate and quick entry

The intended deliberate flow creates a policy-first logical Cell, imports named repositories, then starts a Run in a revalidated compatible generation or admits a new generation when required. The quick agent/path flow atomically creates the same records and crosses the same gates. A matching host path never silently implies continuation. Creating a logical Cell alone creates no process, protected runtime, or source import.

Reusable environments and focused tasks

An Agent Cell is a general-purpose environment that can retain workspace files, scripts, permitted workspace-local tools/dependencies, agent conversation/context state, and task state across explicitly selected Runs. The agent can create and execute scripts there within the admitted limits. Completing a Run or detaching does not by itself delete a retained Cell's state; runtime suspension need not erase that state either.

A user may create another Cell for narrower inputs, context, tools, permissions, or resources. General and focused describe scope, not roles or lifetime: either can be retained or explicitly ephemeral. New Cells receive only selected admitted inputs/context and their own authority. A separate Service Cell is recommended for long-running services needing independent lifecycle or availability.

Ordinary permitted workspace edits, script creation, and workspace-local dependency changes are workload state. Changing admitted sources, policy, runtime/tool profile, adapter, or other security-relevant configuration requires a new generation. Reuse never restores expired or revoked grants. See the Cell lifecycle contract.

Ephemeral and retained work

Low-risk ephemeral work uses one Run under the full authority contract. Default completion destroys runtime and private workspace. Explicit retention seals an eligible checkpoint and converts the Workstream to retained continuity. Workspace, continuity, and evidence retention are separate decisions. GitHub remains the backlog, discussion, code-review, and merge surface.

Example: a paused password-reset task retains its identity when another adapter continues from an authorized checkpoint in a new Run.

See entry flow and Cell identity.

Private repository workflow

Current status: partial private ingress, custody, and sealed-result foundations. Reviewed local Git snapshots, sealed-descriptor import, durable primary-source binding, private reconstruction, and exact-Run worktree-result custody have local tests. Wall cannot yet attest a protected source Run on Virtus. Final worktree bytes and modes are distinct from Cell-local Git index or commits, which are not retained. Result selection, host apply, commit, and push remain unavailable.

Private repository ingress

A broker authenticates outside the Cell and stores verified content-addressed Git objects. Each candidate receives an exclusive writable worktree from a pinned immutable base. Secrets and unsafe filesystem objects are blocked before import; host repositories are never live mounts.

Requirements cover submodules, LFS, monorepos, sparse paths, and declared generated inputs. Dirty local state requires an explicit previewed import with provenance. A remote import is a typed Connection-backed read and rejects embedded credentials.

Policy may admit multiple named Repository Objects. Each retains its own identity, ingress manifest, policy, delivery scope, and evidence. Import updates pending desired state; it does not hot-copy into an admitted generation or synchronize continuously with the host.

Selected delivery

A candidate returns patch, commits, changed paths, artifacts, checks, evidence gaps, and an exact digest. Only the deliberately selected sealed result can leave. Previewed three-way local apply refuses unresolved conflicts. An external GitHub proposal is a governed Effect, keeping credentials outside the Cell. Deleting a private candidate must not corrupt shared immutable repository objects.

Example: the agent edits a private copy while the developer's checkout stays independent. The developer reviews and applies the selected result explicitly.

See repository requirements and governed effect flow.

Save and resume work

Current status: partial declared journal and owner-authored handoff records. Checkpoints, restoration, and cross-agent continuation are still absent; the complete continuity acceptance gate remains open.

The four continuity layers

• Repository: pinned base, worktree delta, staged state, files, tests, and selected artifacts form a content-addressed checkpoint.
• Environment: image, tools, locks, dependency caches, declared services, and setup results form a prepared-state manifest.
• Task: goals, constraints, decisions, completed steps, failures, remaining work, files, checks, evidence, and next action form a typed Work Journal.
• Provider: an encrypted opaque session reference and native resume metadata may optimize same-provider continuation where supported.

Hidden model reasoning cannot be captured or transferred exactly. Agent-authored notes are provider-reported additions, not authoritative observations.

Checkpoint, resume, fork, and fresh

Checkpoint boundaries include pinned input, environment ready, agent turn complete, checks complete, and candidate sealed. Resume validates base, policy, image, environment, and lineage compatibility. Fork creates a child Candidate at an explicit divergence. Fresh retains the task goal with a newly pinned base and environment. Restore always creates a child Run and preserves parent evidence; it is not deterministic model replay or inherited evidence attributed as new work.

Continuity storage

Retained Agent Cells keep their working context and permitted workspace state inside the Cell across Runs. Checkpoints provide recovery and portability; the Work Journal supplies attributed handoff state. The Repository Continuity Index holds separately governed knowledge for later work and does not replace the Cell's working context or transfer its authority.

The intended local metadata default is SQLite; Cloud metadata may use PostgreSQL. Content-addressed storage holds deltas, caches, artifacts, and provider records. A repository mirror holds Git objects, and an append-only ledger holds causal events. Each class has explicit retention.

Example: after a session stops, the next adapter receives the patch, failures, decisions, and next action without pretending to receive the previous model's private reasoning.

See continuity components.

Agents and handoff

Current status: runnable Codex/Claude Agent Cells are not started end to end; the current image is an offline shell, not an agent runtime.

Adapter contract

Adapters support start, structured input, output streaming, interrupt, exit, declared model/tool metadata, optional provider session references, and checkpoint requests. Versions are pinned; capability matrices, health checks, and conformance fixtures make support inspectable. Raw provider signals retain source attribution. Unsupported semantics remain unavailable rather than being normalized into false parity.

Cross-agent handoff

A handoff includes task, base, patch, decisions, completed/failed work, checks, capabilities, evidence links, explicit gaps, and next action. Same-provider native resume is an optional optimization; a cross-provider child Run gets the structured Work Journal and checkpoint. Cella retains the governing policy hierarchy, identity, workspace, and consequence control while the agent changes. Authority is re-evaluated for the new actor, adapter/model, operation, and generation, and eligible requests need fresh generation-bound grants. Handoff does not imply identical decisions or transfer old capabilities into the new Run.

Example: Codex investigates a bug; Claude Code continues from its declared checkpoint. No new host authority or claim of transferred chain-of-thought is introduced.

See agent adapters and handoff flow.

Compare candidate changes

Current status: later planned feature track.

The initial comparison requirement permits at most two isolated alternatives from the same pinned base under equivalent policy, budgets, and checks. Each has its own worktree, branch lineage, Cell, events, artifacts, and budget. Changed-path overlap and dependency conflicts are detected early. There is no shared writable state or uncontrolled multi-agent swarm.

Compare diffs, interfaces, overlap, checks, failures, policy events, evidence gaps, elapsed time, and model/compute cost. A human selects one exact digest. Synthesis creates a new Candidate with explicit provenance; only its selected digest can proceed to proposal. Cella does not declare a universal model winner.

Example: two agents propose different fixes; both pass the same check profile, and the reviewer deliberately chooses one result.

See comparison requirements.

Checks and build outputs

Current status: planned integrated checks; the first complete workflow is still in development.

Approved check profiles

Repository-defined checks have versioned commands, environment, services, timeouts, retries, resource budgets, output limits, and required status. Unit, integration, lint, type, security, build, and repository-specific checks execute through approved Run Targets. Compared candidates use the same declared profile. Execution and logs are bounded and linked to evidence.

Results and artifact provenance

A result includes exit status, duration, output digest, structured summary, coverage, reports/binaries, and known flakiness. Provenance binds Run, candidate, environment, and policy. Missing required checks block seal or proposal. A rerun creates a new receipt; it never overwrites failed history. Reviewers must be able to distinguish code failure, infrastructure failure, and unavailable evidence.

Example: “tests passed” becomes an exact receipt for the selected candidate and environment rather than an agent's unverified completion message.

See checks requirements.

Activity and evidence

Current status: partial receipts and isolated signing validation. An Ed25519 Wall-envelope signer/verifier has local invariant and replay tests and refuses to claim protected. Key provisioning, Wall integration, durable sequence custody, the complete ledger, and cross-boundary signing remain incomplete.

Evidence classes

Integrity, coverage, and enforcement

Records cover admitted input, effective authority, observed commands/processes, denials, approvals, checks, state changes, interventions, cost, Effects, outputs, and external consequences. Event ID, Run, Cell, sequence, actor, source, coverage, policy digest, request/result digests, and prior hash preserve attribution.

The collector stays outside the Cell; distinct signing roles authenticate their own claims. Wall, Gateway, Relay, the secret boundary, and policy enforce their contracts. Evidence explains what each boundary enforced, observed, or caused; it does not replace enforcement, reveal hidden model reasoning, or prove that an allowed action was a wise decision. Missing signals and covert-channel limits stay explicit.

Inspection experience

Intended history inspection reconstructs causal events. File explanation links a change to Runs and checks without inventing reasoning. Restore creates a child Run; it does not assert exact deterministic replay.

Example: an inspector can see which generation requested a denied resource, which policy applied, and which boundary refused it.

See evidence events, signing roles, and components.

Approvals and external actions

Current status: external consequence execution is planned. Gateway health and control are not an implemented Effect broker.

Exact protected operations

An Effect is a typed, idempotent transaction, such as private repository read, model use, authenticated package access, PR creation/update, document publication, or a cloud/Virtus operation. Its request binds actor, Run, candidate, operation, resource, destination, parameter digest, Connection version, budget, reason, idempotency key, and deadline.

Policy returns allow, deny, or a named approval requirement. Prefer an exact github.propose_change candidate over generic Git push; direct push and merge remain separately denyable operations.

Approval, reconciliation, and receipts

Approval binds approver identity and role, decision, reason, policy/request and candidate digests, Connection version, scope, and expiry. Any material change invalidates stale approval. Disconnect, timeout, retry, or missing acknowledgment requires reconciliation; the same operation must not happen twice.

The receipt records the requester, resolved authority version, approved parameters, provider result, redactions, reconciliation state, and disposition. An approved Capsule does not replace normal code review. Some consequences can be compensated but cannot be undone; that limitation must be explicit.

Example: an approved PR proposal uses the chosen patch once, even if the CLI loses its connection before receiving the response.

See effect contract and Gateway flow.

Review and verify changes

Current status: later planned feature track.

A Change Capsule is a portable contract for the selected result. It binds organization, repository, base, exact patch and PR-head digests; task, agent, model, image, environment, policy, Workstream, Run, candidate, and checkpoint lineage; check receipts, capabilities, denials, interventions, approvals, cost, evidence gaps, protected Effects, signature, keys, schema, and disposition.

The open verifier operates offline without an account. A required GitHub check rejects missing, stale, altered, incomplete, or unapproved Capsules. Material PR-head changes invalidate the old status. Third-party CI/security tools can verify the same schema. Tamper fixtures must cover patch, head, checks, policy, evidence, and approvals.

Example: approval for patch A cannot authorize a modified patch B simply because both occupy the same pull request.

See Capsule requirement.

Supervise agent work

Current status: later planned interface track.

Queue, review inbox, and decisions

The primary experience is asynchronous supervision. Workstreams expose queued, running, suspended, blocked, failed, review-ready, proposed, and completed states. Grouping by repository/issue shows owner, candidate, checks, policy block, evidence gaps, budget, cost, and next decision. Notifications request a specific decision; teammate handoff records responsibility.

Controls include pause, checkpoint, fork, cancel, capability request, handoff, selection, and proposal. GitHub remains the code-review surface; the Capsule view explains execution and authority evidence.

Optional terminal intervention

Native Claude/Codex terminal attachment is optional. Operator identity, keystroke boundaries, input leases, and autonomy status are recorded as human intervention. Normal successful work should not require terminal takeover.

Example: a reviewer resolves an exact blocked operation from the inbox rather than taking over the agent's terminal to finish every task.

See supervision requirement.

Limits, recovery, and cleanup

Current status: partial local authority, lifecycle, and offline-shell pieces. Complete recovery, durable-work retention, and deletion gates remain open.

Runtime lifecycle and hard budgets

The required lifecycle covers create, start, attach, pause, checkpoint, resume, stop, destroy, inspect, collect, archive, and delete. Durable leases, heartbeats, idle suspension, retry reconciliation, and orphan cleanup keep failures bounded. Hard budgets cover compute, storage, network, tokens, time, artifacts, logs, and cost. Capability revocation precedes Cell termination. Ephemeral and retained classes keep identical containment and authority boundaries.

Independent retention and verified deletion

Runtime, workspace, continuity, and evidence retention are independently policy-evaluated. Repository objects, candidate deltas, caches, checkpoints, events, provider records, Capsules, and indexes have explicit classes. Ephemeral cleanup must not discard required evidence. Explicit retention seals a checkpoint. Deletion removes private artifacts and derived index entries and emits a receipt.

Failure tests must reach documented safe states without duplicate consequences, lost approved artifacts, orphan authority, surviving post-stop capabilities, or undeleted private data.

Example: ending an ephemeral task destroys its private workspace while retaining required evidence for the configured period.

See lifecycle decisions and durable recovery.

Run Cella yourself

Current status: the integrated account-free workflow is not delivered. The open-source project has working local foundations and experimental slices.

The intended Engine contains the Rust CLI, local Workstream storage, runtime worker, repository transactions, Codex/Claude adapters, checkpoints, policy, local Connections/Gateway, Run Targets, Project Secrets, Service Cells, Channels, evidence, checks, Capsules, GitHub export, verifier, and hostile conformance tests. Security-critical isolation is part of the local product, not a Cloud-only feature.

Local Connections support keychain/encrypted-file references, typed connectors, manual rotation, and disable. SQLite and filesystem/object storage are the local defaults. Linux is the asserted boundary target; macOS development mode is weaker unless a separately qualified runtime contract applies. The project uses Apache 2.0 licensing; licensing in the historical HTML is a recommendation, not an unresolved claim about the repository's current license.

Schemas and exports remain open: policy, Connection metadata without secrets, capabilities, events, artifacts, Workstreams, Capsules, and verification keys. Offline verification must not require a Cella account. A complete local trust loop, rather than a runnable CLI alone, is the release gate.

See repository license, CLI, and Core workflow gate.

Cella Cloud

Current status: planned organization authority plane.

Cloud governs enrolled Installations wherever their Cells run. It distributes signed organization policy, stages rollout, detects drift, inventories the fleet, quarantines installations, and revokes authority. It governs organization Connections, typed Effects, exact approvals, separation of duties, provider health, rotation, and emergency disable.

Durable evidence search, verification, retention, export, incident investigation, shared Workstreams, teammate handoff, and Capsule coordination support teams. Developer machines, on-prem infrastructure, BYOC, and optional managed Dedicated Workers retain the same local cellad enforcement contract. Managed compute is a placement option; Cloud's core role is organization authority.

Cloud sends authenticated intent and policy state. It cannot directly invoke Wall, Gateway, Relay, or the secret boundary, and cannot weaken the installed Security Floor. Credentials remain referenced through Connections, preferably using external secret managers, workload identity, or provider-native identities. Agent-edited policy, prompts, and repository Markdown grant no authority.

Example: a team centrally disables a GitHub Connection for enrolled Installations without transferring its reusable credential into their Agent Cells.

See Cloud authority and eleven use cases.

Organization controls

Current status: planned organization feature track.

Identity and role separation

OIDC/SSO, organization membership, Installation/repository enrollment, and service identity scope operations. Separate permissions cover run, intervention, Connection administration, policy proposal/activation, capability approval, Capsule approval, export, and retention administration. Credential, policy, and Effect approval roles can be separated. An agent cannot activate its own policy or mint capability. Responsibility handoff identifies the accepted checkpoint and next action.

Governance operations

Connection inventory records ownership, scope, version history, health, rotation, disable, revocation, usage, budgets, and rate limits. Governance includes signed baselines, policy simulation, staged rollout, drift detection, scoped exceptions, retention, evidence export, quarantine, and emergency kill switches. Organization policy cannot weaken the local Security Floor.

Evidence binds requester, generation, Run, policy, approval, Connection version, operation, destination, and result; SIEM export retains the same causal contract. Customer-controlled execution, retention, storage, and keys are supported where required by the organization contract.

Example: a developer requests an exception, a separate authorized approver accepts its exact digest, and the request expires without becoming permanent blanket access.

See organization governance and policy hierarchy.

Repository knowledge

Current status: later planned repository-memory track.

The index reuses provenance-linked setup facts, tool commands, environment needs, recurring failures, successful corrections, policy decisions, approved exception patterns, review outcomes, and rejected approaches. Every suggestion links to its source Workstream and evidence. Stale, conflicting, revoked, or deleted history is identified and excluded.

Knowledge remains repository/organization scoped by default. Private code is not pooled for cross-customer model training without a separate explicit agreement. Deletion removes derived private entries. Evaluation compares history-aware Runs against fresh-start and no-history baselines, checking both usefulness and safety.

Example: the next Run receives a sourced fix for a recurring test setup failure; it can inspect the evidence rather than treating an unsourced note as authority.

See continuity-index requirement.

Operations and integrations

Current status: partial local foundation and installation code; broader operations/API capabilities remain planned. First-install signed-bundle code exists without a production signing key, published signed release, or target-host acceptance. On Debian 13 x86-64, the checkout already offers a user-local CLI bootstrap through ./install.sh --check and ./install.sh, verifying the bundled unsigned alpha binary against its checked-in SHA-256. Rust and a C compiler are not required for that bootstrap. It installs no daemon, Wall, runtime, identities, images, or systemd units; it does not enable an Agent/Service workflow. Verified whole-installation upgrade and rollback are not implemented.

APIs and reliable operations

Requirements include versioned CLI, HTTP API, webhooks, signed schemas, idempotency, pagination, stable errors, and rate/size limits. Structured redacted logs, metrics, traces, SLOs, alerts, runbooks, backup, restore, upgrades, rollback, key rotation, and incident response make the system operable.

Health/readiness must distinguish controller, worker, Gateway, storage, queue, GitHub, and model dependencies. Rust supply-chain policy, SBOM, locked builds, fuzzing, property tests, and independent security review are part of the release contract. Recovery drills and external-client conformance must validate the published guarantees.

Portability and commercial requirements

Documented exports include Workstreams, policy, events, artifacts, Capsules, and verification keys. Retention must not depend on trapping customer data. The intended commercial model combines organization/governed-repository commitment, successful retained Workstreams, transparent compute, and retention. Failed infrastructure Runs are not billable, and reviewers/CLI users are not charged merely as seats. Predictable bills, bounded support burden, and sustainable margin are product requirements; the source catalog's commercial targets are not current business results or a published price list.

Example: a team can export its evidence and verify Capsules independently while an interrupted compatible update recovers to the documented safe version.

See current CLI bootstrap, installation and updates, and operations requirement.

Remote control with Cella Link

Current status: later planned remote-operator track.

Context, enrollment, and private transport

A Context selects a saved Installation. A Link is an authenticated operator connection to it. Local/admin-authorized pairing issues a distinct revocable device identity; its private key remains in the device keychain or secure hardware.

The remote CLI sends typed user intent only to the Installation's authoritative cellad. It receives no component sockets, runtime authority, provider credentials, Project Secrets, or direct Wall/Gateway/Relay/secret-boundary routes. Operator/device policy scopes Installations, repositories, Workstreams, Cells, methods, approvals, and administration.

Transport is mutual TLS over a configured user-provided private route: LAN, VPN, overlay network, or equivalent. Link requires no Cloud account, Cloud control plane, hosted relay, or external Cella service. It is not raw SSH, remote desktop, a generic tunnel, or general host control.

Multiple operators and attributable decisions

Multiple enrolled operators may observe the same Workstream. Mutations include an expected state version and are serialized by cellad; conflicts fail explicitly. Interactive input normally uses one renewable lease; others observe until policy transfers or shares control.

Approval binds exact request digest, rule, Installation, operator, device, decision, timestamp, and expiry. Policy may require distinct approvers/roles. Disconnect, retry, and failover never duplicate a consequence. Evidence records pairing, authentication, requests, conflicts, lease changes, approvals, revocation, transport path, and bounded outcomes without secret values or private keys.

Example: an enrolled Mac controls work on a Debian Installation through cellad; a revoked or wrong-Installation device is refused. Start, observe, attach, pause, resume, approve, and inspect all retain the same authority chain.

See remote-operator requirement and Link control flow.

Bring existing services into Cella

Current status: later planned migration track; separate from first Service Cell startup and first Channel support.

Adoption transfers an existing systemd, Docker, Compose, or manually managed service into a governed Service Cell. It does not retroactively protect the source process or treat a live-process checkpoint as a reproducible runtime.

Read-only discovery and reviewed plan

Discovery makes no source changes. The plan records executable/artifact, configuration, service account, ports, dependencies, data paths, secret references, health checks, resources, downtime, and rollback limits. Inferred mounts, routes, credentials, and privileges are untrusted proposals.

The user/organization approves the exact plan digest before quiescing. Unattended adoption needs narrow pre-authorization for that service class. Reproducible runtime inputs become a sealed revision; a live host repository is never retained as a mount.

Durable migration and rollback cutoff

The transaction covers discover, plan, approve, quiesce, consistent snapshot, stop, import, start, verify, complete, and rollback. Declared data is copied, moved, cloned, or placed under exclusive Cella ownership as managed volumes; database-specific flush/snapshot procedures establish consistency. Project Secret Sets/Connections replace plaintext environment and credential files without leaking values into Agent Cells, plans, logs, or evidence.

The service is managed only after health, data, network, policy, and Channel verification. Pre-write failures restore the original service without data loss. Once the new generation accepts writes, automatic rollback may be unsafe; later failure must expose the data reconciliation requirement rather than claim lossless rollback.

Evidence binds source identity, discovered facts, plan/policy, approval, quiescing, snapshot, revision, secret/volume references, lifecycle transitions, health, completion, and rollback outcome.

Example: a reviewed systemd collector moves into a Service Cell with consistent data and explicit rollback limits, rather than an undocumented sequence of mounts, secret copies, and process-manager changes.

See service adoption architecture and adoption requirements.

Release gates and source notes

The intended sequence is internal alpha, Open Engine preview, team workflow, service adoption preview, commercial Cloud, and mature continuity/ecosystem expansion. These are evidence-gated stages, not release dates or shipped claims. The original release requirements retain exact acceptance targets for task success, activation, retention, operator effort, conformance, security, reliability, and commercial viability.

The HTML catalog is the fuller feature/subfeature inventory. The Markdown adds strict YAML, custom-operation registration, detailed private-network Link semantics, and explicit adoption evidence. Both describe requirements. Some implementation summaries in older architecture documents still predate recent local shell/Service/Relay work; use the current milestones for status, those documents for contracts, and source/test evidence when qualifying a particular build.

Cella does not need to become a coding assistant, backlog replacement, generic network tunnel, unlimited agent swarm, secret-bearing agent shell, hidden-reasoning recorder, or host/container manager with weaker authority rules. The complete catalog remains one governed execution and work contract.