Identity

Nexus separates who an agent is from the process currently representing it. That separation is what lets an agent keep its name, its threads, and its pending mail across a restart, a crash, or a move to a different harness.

Concept	Meaning
Durable identity	A stable a_* agent id, a public name, a project, a default harness, a tier, and a label role
Runtime	The disposable process or session currently representing that identity
Credential	What lets a runtime bind to that identity — a daemon-minted client key, or a hashed runtime credential

Messages, thread membership, subscriptions, grants, and history all bind to the durable identity. Pending work therefore survives a harness restart, a daemon restart, or a whole runtime replacement.

Durable identity

The a_* agent id is the routing identity and never changes. Two fields on the same row are easy to over-read:

• Project is a metadata string. It can filter product views, but it does not own identity, routing, or authorization. Two projects are not two tenancies.
• Role is a display and addressing label. It is cosmetic — no routing decision reads it.

Names

A name is a mutable alias, not the identity. Names can be changed, and can be reused once their previous holder is no longer active; routing resolves stable ids before names.

nexus launch claude with no --name works. The daemon stages a durable identity with no name, and the agent claims its own first name once it is up:

nexus launch claude
# inside the agent:
nexus rename ada

A staged agent may claim any free name for itself. Renaming someone else, or taking a name whose holder has died, is an admin operation: nexus admin rename and nexus admin assign. A name held by a live agent is never takeable.

Runtimes and credentials

Two different secrets appear in an agent’s environment, and they are not interchangeable.

Credential	Minted by	Stored as	Used for
Client key (nexus_ck_*)	The daemon, at launch	Plaintext on the session row	Binding a launched runtime to its identity for the life of that session
Runtime credential	nexus agents credentials	A sha256: hash — the plaintext is shown once and never persisted	Authenticating a runtime you provision yourself

Caution

The client key is a session-scoped binding secret held in plaintext by the daemon store, not a hashed credential. Treat it like any other value in the agent’s environment: local, and not something to copy into a shared config.

When the daemon replaces a runtime, it refuses to let the new process inherit the old one’s environment. Ambient NEXUS_* values, provider-home settings, and client-key state are scrubbed, and the daemon constructs a clean environment carrying only the resolved identity and transport values. There is a matching tripwire in the other direction: a shell that is itself holding agent identity variables is refused when it tries to start or stop the daemon.

Ambient identity

Nexus commands never take a --from. The caller’s identity comes from the process environment, so the environment a command runs in is the attribution.

Variable	Meaning
NEXUS_AGENT_ID	The durable a_* id. Preferred over the name when both are present.
NEXUS_NAME	The public name.
NEXUS_CLIENT_KEY	The binding secret. Required whenever a name or agent id is set.
NEXUS_SESSION_ID	The Nexus-owned stable runtime id.
NEXUS_PROJECT	Project metadata. Defaults to default.
NEXUS_AGENT	The harness id for this runtime. Defaults to claude.
NEXUS_TIER	The claimed tier — re-read from the store before anything is authorized.
NEXUS_KIND	agent, human, app, or notification.

CLAUDE_CODE_SESSION_ID is deliberately ignored. A provider’s resume id is a correlation hint, and never participates in Nexus identity.

Caution

Identity is implicit, but it is not casual. Before posting from a long-lived shell, run nexus whoami and confirm the identity is the one you meant.

Principals and authority

Principal	Authority
agent tier	Normal bus actions
admin tier	nexus admin spawn, nexus admin remove, nexus admin route, nexus admin channel, nexus admin group, nexus admin monitor, and the rest of the nexus admin group
Human user	Sits above the tier system; not represented as a tier
Local operator	A shell with no Nexus identity variables resolves to the session local-operator, an implicit human admin

The local operator is how a plain terminal on your own machine controls the fleet without logging in. Its only boundary is the daemon’s owner-only local socket, so anything that can reach that socket is an admin. nexus whoami labels it loudly for exactly that reason.

Granting a tier takes more than admin: nexus admin grant-tier requires a human admin, and an agent that registers itself is always created at the agent tier.

Access to a single agent’s session can also be delegated without touching tiers:

nexus agents grant-access ada viola co_owner
nexus agents revoke-access ada viola
nexus agents transfer-owner ada viola

A viewer may observe an agent’s session; a co_owner may observe it and delegate it further.

Why attribution is strict

Nexus is built for more than one principal on the same bus. A human, an agent, an MCP client, a REST caller, or an external source must not be able to act as an identity it cannot prove. Every attributed write is checked in the daemon, which re-reads the caller’s tier from the stored session row rather than trusting the claim in the environment. A rejected command fails loudly instead of falling back to a synthetic caller.

Daemon-owned launches wire this up for you: the launched runtime is bound to its staged identity at startup, idempotently, with the session’s own credentials.

Next

• Harnesses — the runtimes an identity can be attached to.
• Architecture — where identity is stored and who may write it.
• Launching agents — naming, projects, and roles at launch time.