Cella daemon (cellad)

cellad is the local coordinator for a Cella Installation. It turns an authenticated request into a policy decision, a durable operation, and a request to the component responsible for carrying it out. It runs outside every Cell and retains the control state needed to understand and recover the work.

This guide explains the intended responsibility model. Local control, storage, policy, and runtime coordination slices exist, but the complete protected workflow remains in development. See What is implemented today before treating an example as an available command.

Why Cella has a daemon

An agent session, terminal, or CLI process can disconnect. Cella still needs an accountable owner for the Project, its permissions, the admitted workloads, and any operation whose outcome has not been confirmed.

The CLI is a short-lived command surface. cellad provides the continuing coordination behind it. A new CLI invocation refers to existing Cella records rather than reconstructing authority from the agent's conversation or the developer's shell environment.

The daemon serves one Installation on the machine hosting the work. That machine may be local or remote. Remote intent must reach that Installation's authoritative daemon through an enrolled interface; moving the user interface does not move enforcement or grant direct access to authority components.

CLI, daemon, and authority components

Each part has a different job:

cellad owns coordination. It does not replace these components' independent checks. An agent request, a successful transport handshake, or a caller-supplied identity is not sufficient authorization.

What the daemon is responsible for

Authenticate intent and resolve identity

The daemon determines who is asking and which Installation, Project, Cell, generation, Workstream, or Run the request concerns. Local callers are identified through the accepted transport and kernel-observed user identity. Remote controllers need their own enrollment, principal context, and permitted scope.

For example, a request naming another developer's Project does not make the caller its owner. Requests from Cells require a trusted, generation-bound origin; an agent cannot authenticate itself by putting a Cell ID in a payload.

Maintain Project, Cell, and work records

cellad owns durable control records: Project ownership, trusted policy bindings, logical Cell identity, desired configuration revisions, and the relationships between Workstreams, Runs, candidates, and observed generations.

A logical Cell record is separate from its running environment. Creating or reusing the record does not by itself start a process, grant a credential, or prove protection. Wall owns actual runtime lifecycle and inspection. The daemon retains the references and observations needed to coordinate that lifecycle.

In the full continuity model, the daemon also coordinates retained checkpoints, handoff, candidate selection, and final disposition. Bulk workspace and artifact bytes remain in their owning stores rather than becoming unbounded daemon memory or ordinary log content.

Evaluate trusted policy

The Policy Engine is a responsibility inside cellad. It compiles adopted, trusted policy sources into an Effective Policy and evaluates an exact request against that policy, current state, and applicable restrictions.

The intended hierarchy combines the installed Security Floor, organization, Project, Workstream, Cell, and operation restrictions. Lower scopes narrow authority rather than silently widening it. A repository can propose a policy file, but its contents do not become authoritative until the permitted owner adopts them.

The daemon binds policy identity and digests to the operation. Wall, Gateway, Relay, and the Project Secret Boundary retain their own applicable enforcement and cannot treat the daemon's decision as permission to ignore their floor.

See Policy and approvals for the permission model and Policy Engine architecture for the complete design and currently implemented subset.

Admit exact workload inputs

Before requesting execution, the daemon resolves the approved source or artifact, workspace, runtime profile, agent adapter, model route, policy, resource limits, and placement required for that workload.

It asks Wall to admit an exact generation using those immutable inputs. The request cannot become an agent-supplied OCI document, arbitrary host mount, or command that bypasses the installed runtime contract. Changes to controlling inputs follow the generation-change rules rather than silently rewriting a running environment's authority.

Coordinate approvals and external actions

When policy requires approval, the daemon binds the decision to the exact request, accountable actor, resource, parameters, relevant generation, and expiry. Approval for one operation is not a reusable permission for arbitrary future actions.

For an Effect, it coordinates a typed authorization and asks Gateway to perform the permitted credential-backed action. Gateway owns provider credential use. The daemon retains pending intent and outcome references, and reconciles an uncertain result before a retry. It must not turn a disconnected response into an assumption that the external action never happened.

Coordinate services, secrets, and Channels

For an application, the daemon resolves an approved Run Target and sealed revision or pinned artifact. It coordinates the Service Cell generation, declared data, limits, and any exact authorized secret binding. A secret-bearing Service Cell is separate from the agent's editable workspace and interactive tools; the daemon does not receive application-secret plaintext.

A Channel grants communication with a named Service endpoint. The daemon authorizes its caller, destination, generation, protocol, scope, limits, and lifetime, then administers the grant. Relay carries the permitted traffic. Knowing a Service's name or calling one endpoint does not authorize access to its other ports, files, environment, shell, or secrets.

Observe, reconcile, and account for the work

The daemon compares desired state with authenticated observations, links operation results to their Workstream and Run, and presents bounded status, denials, progress, and evidence references to authorized callers.

It coordinates limits, stopping, revocation, cleanup, and recovery. Enforcement remains with the responsible boundary. A resource budget in a record is not a measurement of runtime usage or proof that Wall enforced it.

Evidence remains attributable to its producer. cellad can correlate a Wall receipt with the request that caused it; it cannot manufacture Wall's signature or reinterpret a reported observation as a verified containment fact.

What the daemon does not control directly

The daemon does need its own enrolled controller identity. That identity is distinct from a provider token, application secret, release-signing key, or another component's evidence-signing key. Private identity material follows the installation's protected credential-delivery contract.

Compromise of the daemon can disrupt work and exercise requests that still pass the independent component checks. Separation is therefore a defined trust boundary, not a claim that the controller is irrelevant to security.

How a request moves through the daemon

The intended mutation path is:

authenticated caller
    -> resolve Project, Cell, generation, and work context
    -> evaluate Effective Policy and required approval
    -> persist pending intent and request identity
    -> request the responsible authority component
    -> validate its result or reconcile uncertainty
    -> commit the outcome and causal references
    -> return a sanitized response

An operation's request identity supports safe retries. Repeating the same idempotent request returns its recorded outcome; reusing that identity with different content is a conflict. A timeout or broken transport does not authorize a fresh, untracked external action.

The following examples describe the complete design, not working end-to-end commands in the current release.

Example: an agent requests a Git push

1. The agent requests delivery of an exact approved candidate or commit to a named repository and branch.
2. The daemon resolves trusted origin, Project ownership, policy, and any required approval. It does not accept the agent's claimed scope as fact.
3. If allowed, it persists the exact pending Effect and authorization context.
4. Gateway independently validates the request and uses its protected Connection to perform the operation. No GitHub token enters the Agent Cell or the daemon's response.
5. The daemon records the confirmed outcome and receipt reference. An uncertain push remains subject to reconciliation before retry.

Example: an agent calls an application

1. An approved application generation is running in a Service Cell.
2. The agent requests access to its named test endpoint.
3. The daemon evaluates and administers a Channel for the exact caller, destination, permitted protocol, limits, and lifetime.
4. Relay carries the request. The application returns its permitted response.
5. The agent receives endpoint access, not the service's filesystem, debugger, or runtime credentials. Revocation or expiry closes the granted access under the Channel's defined contract.

Startup, readiness, and shutdown

On the Debian runtime target, systemd starts cellad as a foreground service under its dedicated service identity. It owns the CLI listener and passes the validated socket to the daemon. Users normally invoke cella, while the service manager supervises cellad.

The lifecycle contract separates process readiness from authority readiness:

READY=1 means the daemon can answer its accepted control requests safely. It does not prove that a Cell is protected, that an agent can start, or that Gateway and every other dependency are available. cella daemon status reports control readiness, the last authenticated Wall health observation, and protected-runtime readiness separately.

Reloading is not a shortcut for activating a new policy, trust root, credential, Connection, or runtime profile. Authority changes require their governed transactions. A daemon shutdown or restart also does not implicitly destroy every Cell: each authority component retains its own lifecycle and lease contract.

Recovery after a disconnect or restart

A CLI disconnect, daemon crash, or host interruption can occur after a request has been accepted but before its result reaches the caller. The full recovery contract requires the daemon to:

• retain committed identity, immutable inputs, policy bindings, and pending intent rather than reconstructing permission from a conversation;
• establish fresh authenticated component sessions; an old controller lease does not survive by assumption;
• reconcile recorded intent with actual component state before continuing;
• distinguish completed, pending, failed, and uncertain consequences; and
• reserve capacity for revocation and safe cleanup when ordinary work is overloaded.

Recovery does not promise an uninterrupted process or portable hidden model reasoning. Resuming agent work requires the retained state and revalidation defined by its continuity contract. If protection or an operation's outcome cannot be established, the daemon reports that limit rather than inventing success.

State, operational logs, and evidence

The daemon's control store is the durable record of the control state it owns. The CLI accesses those records through the control API, not by opening the database itself. The current local implementation uses SQLite for Project, logical Cell, policy, and Workstream/Run slices; the complete recovery and retention contract is still in development.

Keep three kinds of information distinct:

Structured operational logs go through systemd/journald. They do not become durable product evidence merely by being logged. Secrets, private keys, provider responses, terminal output, and source content are not ordinary daemon log fields. Large retained objects belong in their designated stores.

Inspecting the daemon

For an enrolled installation, the read-only CLI status command is:

cella daemon status

On a host where the service units are installed, an operator can inspect service state and logs with:

systemctl status cellad.service cellad.socket
journalctl -u cellad.service

These commands describe the installed service. Building the CLI alone does not install the daemon, its credentials, Wall, or the protected runtime. The CLI's explicit socket override is for development and testing; an arbitrary socket path does not establish a production Installation.

See CLI reference for setup status and the installation contract for release and target-host requirements.

What is implemented today

The source checkout contains partial, locally tested paths. Their presence does not establish a qualified protected workflow or a published production release.

The current feature milestones track acceptance and remaining work. The daemon architecture defines the detailed process contract; the component architecture defines the independent authority boundaries.