Components, explained

Status: introductory product guide. This page explains the approved architecture, not a claim that every component is implemented or qualified. See the feature milestones for current implementation status.

Cella is designed for agents that work over time on a remote PC, server, or dedicated environment under explicit permissions. The same model supports everyday development with reusable project Cells and narrower task-specific Cells. Cella separates the place where an agent works from the authority it can use. Start with Cells, then follow how the controller, isolation boundary, and communication components work together.

Looking up a name? The glossary defines the complete product vocabulary, common aliases, and supporting modules with examples and links.

What is a Cell?

A Cell is a Cella-managed, isolated execution environment. It has an identity, a role, admitted inputs, explicit permissions, resource limits, and a lifecycle. Wall creates and contains the environment; cellad coordinates its use.

A Cell is the place where a workload runs. Agent Cell, Service Cell, and Analysis Job Cell describe different roles for that environment.

For example, an Agent Cell can contain a coding agent, a private copy of source code, and build tools. A separate Service Cell can run the application that the agent needs to test. The agent does not gain access to the application's secrets simply because it can send an approved request to that application.

A Cell Record preserves the logical Cell's identity and history. A Cell Generation identifies one admitted execution boundary with fixed inputs and permissions. Changing those admitted properties requires a new generation. Its Generation Manifest records the admitted properties; Observed Status reports changing facts such as whether it is running, stopped, or quarantined.

Further reading: Cell identity and properties.

Long-running agents and everyday development

The primary use case is a remote or dedicated machine where an agent can keep working between operator visits. The operator defines the workspace, tools, service access, external actions, and budgets. The intended workflow lets the agent work within that authority, pause for a required decision, and leave inspectable state and evidence for the operator's return.

Everyday development uses the same boundaries. A developer can explicitly select an existing project Cell for another task or create a separate Cell with narrower permissions. A Cell can be useful across many development sessions; its purpose is not limited to one disposable agent invocation.

What reusing a Cell means

Reuse means selecting the same logical Cell deliberately. It does not mean matching a host directory and silently restoring an old session. Each Run is an attributable execution attempt. A compatible generation may be reused when its admitted inputs remain valid; a security-relevant change to policy, source, declared runtime/tool profile, adapter, or secret bindings requires a new generation.

The retained Agent Cell keeps its workspace, scripts, permitted workspace-local tools and dependencies, conversation/context state, and task state across Runs. The agent can create scripts and execute them there. Finishing a Run or leaving the Cell does not by itself erase that state. Ordinary workspace edits and script execution are workload state; they do not rewrite the admitted manifest. A retained Cell may stop or suspend its runtime without losing permitted state.

Workspace retention and authorized continuation are explicit decisions. Checkpoints and the Work Journal preserve declared files, task state, and lineage. They do not transfer hidden model reasoning. Replacement generations receive fresh grants rather than inheriting expired Channels or approvals.

General and focused Cells

“General” and “focused” describe the scope of a Cell's work, not new Cell roles. A project Agent Cell might edit source and run local tests. A narrower Agent Cell might review a selected repository input without delivery authority. A Service Cell can run an approved test backend; an Analysis Job Cell can process an explicitly granted snapshot.

Think of an Agent Cell as a reusable work environment, similar to choosing a Python venv for a project. Cella also defines isolation, permissions, resource limits, and governed external operations. Create an environment, work in it, leave, and return later; create another when a task needs different context, dependencies, inputs, or permissions.

Project
  general      -> ongoing agent context, workspace, tools, and scripts
  fix-parser   -> selected inputs and focused task context
  review       -> read-only input, no delivery permission
  experiment   -> separate permitted dependencies and scripts

These names illustrate user choices, not built-in presets. Narrow scope does not imply short lifetime: a focused Cell can be reused, and a general Cell can be explicitly ephemeral. A new Cell receives only selected admitted inputs and context, with its own authority; it does not inherit another Cell's workspace, context, or permissions automatically.

A separate Service Cell is recommended for a long-running service needing its own lifecycle, restart behavior, availability, or resource budget. Ordinary scripts and local task execution remain Agent Cell work; application secrets still require an eligible non-agent runtime and an exact authorized binding.

The Cell lifecycle contract owns these rules. Checkpoints provide recovery and handoff; the repository memory index supplies selected governed knowledge rather than replacing the Cell's working context.

Cells cooperate through declared interfaces. For example, the project agent can call a test backend's named HTTP endpoint through an authorized Channel carried by Relay. This grants the exact request and bounded response, not the backend's credentials, filesystem, or other permissions.

Current Channels are defined around named Service endpoints. Arbitrary agent-to-agent messaging, remote cross-Installation routing, or shared mutable workspaces are not implied by connecting Cells. A future interface for those cases needs its own identity, protocol, policy, lifetime, and evidence contract.

These are intended product workflows. The complete long-running agent, checkpoint/resume, and daily development paths are still in development. See the feature milestones and canonical command flow for their exact boundaries.

The three Cell roles

Agent Cell

An Agent Cell runs the untrusted coding agent. The agent can edit its private workspace and use the tools and connections admitted for that task.

The intended repository workflow imports a reviewed source snapshot into Cella storage. It does not mount the live host working tree into the Cell. The agent produces a Candidate: a result that can be checked, reviewed, and deliberately selected for delivery.

Example: Codex modifies src/server.go and runs tests in its private workspace. Those edits do not silently overwrite the developer's checkout. Access to a service or a credentialed external operation requires separate authorization.

Service Cell

A Service Cell runs an approved task or application independently from the agent. Its code comes from a sealed revision or pinned artifact, and its launch behavior comes from an approved Run Target.

Example: a backend runs in a Service Cell while an Agent Cell tests its HTTP endpoint. The backend can use an authorized database secret without revealing that secret to the agent. A secret-bearing Service Cell has no agent, interactive shell, or debugger attached while its secret lease is active.

The service can continue after the agent disconnects. Updating its code or admitted settings creates a new service generation rather than letting the agent rewrite a running secret-bearing environment.

A Cella Service is the named service identity and endpoint contract. A Service Cell is a runtime that can implement that service. A Connected Service is an explicitly enrolled service outside a managed Cell; enrollment does not make its external execution Cella-contained.

Further reading: Service runtime and data.

Analysis Job Cell

An Analysis Job Cell runs a bounded task against explicitly granted data. It separates data analysis from the coding agent's workspace and from a live service's storage.

Example: an approved job reads a selected database snapshot and produces a classified report. The agent receives an authorized report artifact rather than automatic access to the raw database or the service's writable volume.

The components around a Cell

These names describe separate responsibilities. A product object such as a Channel is not another daemon, and a Cell role is not a privileged host process.

CLI and cellad: intent and coordination

The CLI is the user's command surface. cellad is the long-lived controller outside every Cell. It maintains state, evaluates policy, coordinates approvals, and asks the responsible component to carry out an authorized action.

Only enrolled cellad controls Wall, Gateway, Relay, and the Project Secret Boundary. An agent cannot obtain their control authority by calling them directly or claiming another identity in a request payload.

The Policy Engine is a responsibility within cellad. It compiles trusted policy sources into Effective Policy and evaluates exact requests. Authority components also enforce their own installed floor.

Further reading: Daemon responsibilities and lifecycle, daemon architecture, and policy hierarchy.

Wall: execution enforcement

Wall owns the privileged runtime boundary. It admits generations using installed profiles and controls isolation, lifecycle, resources, and inspection. The Wall Profile identifies the required enforcement contract.

Wall does not own GitHub integrations, provider credentials, or business approval. Its job is to enforce the admitted execution boundary.

The first runtime target uses containerd and gVisor on Debian. The sandbox technology is infrastructure beneath Cella; an alternative backend must satisfy the same required enforcement and qualification contract. A protected claim requires evidence for the exact admitted generation.

Further reading: Wall security model and protected Cell contract.

Gateway: credentialed external actions

Gateway performs typed external operations using credentials that remain outside the Agent Cell. A Connection names an approved provider identity and credential reference. An Effect is one exact external operation.

Example: the agent requests a Git push for a repository, branch, and commit. cellad evaluates policy and any required approval. Gateway then performs the authorized Effect through a Connection and returns a bounded result and receipt. The agent does not receive the reusable GitHub token.

Connections, Effects, and provider routes do not grant arbitrary internet or host access. An interrupted external operation requires reconciliation so a retry does not blindly repeat its consequence.

Further reading: Credentialed effect flow.

Relay and Channels: scoped service communication

The canonical name is Cella Relay, with executable name cella-relay.

A Channel is a directional permission to communicate with a named service endpoint. It binds the caller, destination, generation, protocol, limits, and lifetime. Relay carries the traffic allowed by that Channel.

Example: one Agent Cell may call the backend-test HTTP endpoint implemented by a Service Cell. That grant does not expose every service port, the application's filesystem, its environment variables, or its credentials.

cellad authorizes and administers Channels. Relay carries the data, while provisioned endpoints bind traffic to the admitted identities. Expired or revoked Channels must stop working; an old grant cannot silently transfer to a new agent generation.

Relay is separate from Gateway: Relay carries governed service traffic; Gateway executes credentialed external operations. Relay has no provider credential authority and is not a general host or internet proxy.

Further reading: Why Channels and Relay are separate.

What a Channel permits

A Channel names an exact caller and destination endpoint, not an entire machine. Its contract can constrain protocol, methods or messages, request and response bounds, resources, lifetime, and revocation. Endpoint identities are bound to the admitted generations; knowing an address is not authorization.

For example, the following is an illustration of the contract, not runnable configuration or the final API:

caller: agent-cell / generation-7
destination: backend-test / generation-3
endpoint: health-http
protocol: HTTP
scope: GET /health
lifetime: current authorized lease

That grant permits the health request and its bounded response. It does not permit a different service, another port, a service filesystem read, process inspection, secret access, or an arbitrary host or internet connection.

How a request crosses the boundary

1. An agent requests access to a named Service through its admitted request path.
2. cellad evaluates identity, current policy, endpoint scope, limits, and any required approval, then provisions an exact Channel grant.
3. Relay carries traffic using the provisioned data-plane identities. The agent does not call Relay's control API or configure a route itself.
4. Evidence records the authorization and the defined traffic observations, results, limits, and gaps without exposing secret values.
5. Expiry, revocation, or generation replacement ends that grant. A replacement Run receives fresh authorization rather than inheriting the old lease.

Declared paths include Cell-to-Cell traffic, an explicitly enrolled local service, and local-client preview. A Connected Service remains externally owned; Channel mediation does not make its runtime a protected Service Cell. If Relay is unavailable, the governed service path fails closed while admitted local workspace work can continue.

Channel, Connection, or Link?

“Cella Relayer” is an older informal name. Use Cella Relay and cella-relay in current documentation.

Project secrets: application runtime configuration

A Project Secret Set holds explicitly imported application runtime values outside the repository ingress and every Agent Cell. The Project Secret Boundary controls their storage and projection.

A Secret Runtime Binding authorizes a specific set for an exact eligible runtime generation, target, scope, and lifetime. Application secrets are separate from the provider Connections Gateway uses for external Effects.

Example: a Service Cell receives an approved database configuration. The Agent Cell can exercise a permitted application endpoint without receiving the secret or access to the service's process memory.

Further reading: Service and secret boundaries.

Data, snapshots, and artifacts

Source, persistent application state, and analysis results have separate identities and permissions. Sharing one does not automatically share the others.

Example: a Service Cell maintains a database in a Data Volume. A consistent snapshot becomes an approved Analysis Job Cell input. That job produces a bounded, classified report. An Artifact Grant lets the Agent Cell read the report without granting access to the database, job secrets, or service storage.

Service Cell + Data Volume
           ↓ consistent snapshot
Data Snapshot + exact Data Grant
           ↓ bounded analysis
Analysis Job Cell
           ↓ classified result
Artifact + exact Artifact Grant
           ↓ permitted read
Agent Cell

Live service communication uses Channels or a trusted query connector rather than mounting a live database file. Database-native backup or storage-consistent procedures must establish a usable snapshot; copying active files is not assumed safe.

Policy may explicitly permit an Agent Cell to read an immutable snapshot. That is a separate data-authority decision: anything given to the agent may reach its model provider. Classification, filtering, provider policy, network restrictions, limits, and expiry must therefore govern that grant. A summary is not assumed safe merely because an analysis job produced it.

Data lifecycles are explicit. Replacing application code does not implicitly replace its Data Volume, and a new runtime generation does not inherit old secret or data bindings. Service Adoption defines consistent migration and rollback boundaries; once the new service accepts writes, rollback may need data reconciliation.

Further reading: Persistent data and analysis.

Evidence, signing, and verification

Evidence records attributable lifecycle, policy, approval, execution, Channel, Effect, check, and delivery facts. Records identify the relevant generation and expose missing signals rather than imply complete visibility.

The Evidence Ledger preserves records and their ordering. Evidence signers authenticate records according to distinct producer roles. A verifier checks the required signatures, identities, policy, and completeness for a stated claim. A signature authenticates a statement; it does not by itself prove every required security property.

A Change Capsule binds a selected patch and base to its checks, policy, approvals, evidence, and protected Effects. The Capsule Verifier checks that bound result rather than accepting an approval for an unrelated or changed patch.

Further reading: Evidence signing roles.

Supporting modules and stores

These are responsibilities inside the components above, not a requirement to run a separate daemon for every row. They explain where coordination, storage, enforcement, and verification happen.

The component architecture specifies the exact trust boundary and forbidden authority of each module. The feature milestones track which paths are integrated.

Work and data objects

These objects connect the components without granting extra authority merely because they share a Project or Workstream.

Workstream continuity preserves declared work and evidence. It does not promise to recover an agent's hidden reasoning or make one model inherit another's private internal state.

How the components fit together

The control paths have distinct responsibilities:

For a backend bug fix, the intended user experience is:

1. The developer selects source inputs and permissions through the CLI.
2. cellad coordinates admission; Wall creates an Agent Cell generation.
3. The agent edits its private candidate and runs admitted tools.
4. An approved sealed revision starts in a separate Service Cell for testing.
5. An authorized Channel lets the agent call the service endpoint through Relay.
6. An approved delivery Effect goes through cellad and Gateway using a protected Connection.
7. Evidence connects the inputs, policy decisions, checks, and consequences to the exact result the developer reviews.

This is a product example, not a runnable end-to-end tutorial today. Follow the CLI reference and feature milestones for available paths.

Local Engine, remote control, and Cloud

The Cella Engine is the intended account-free open-source trust loop. Cella Link lets an explicitly enrolled device control an Installation by sending authenticated intent to its authoritative cellad; Link does not require Cella Cloud or grant direct Wall access.

Cella Cloud is the planned organization layer for shared policy, Connections, approvals, fleet coordination, continuity, and evidence. Execution can remain local or on customer infrastructure. Cloud does not replace the local execution boundary.

The planned Cloud responsibilities are:

Further reading: Cella Cloud direction.

Authoritative references

This guide explains the vocabulary. The following contracts own its precise meaning and should be consulted when implementing a component:

• Canonical component names and kinds
• Component privileges and communication paths
• Cell identity and generation properties
• Service runtime and data
• Protocol boundaries
• Current feature milestones