CotalEmbedding Cotal
Build your service from the published @cotal-ai/* packages.
Your application's entry point imports the packages it needs and owns their configuration and lifecycle.
The cotal CLI uses the same composition pattern in bin/cotal.ts.
For CLI automation, agent tools, and wire clients, see the API reference.
Read Architecture, Identity and auth, and the Delivery daemon before composing server processes.
Choose what to embed
For a service that operates a mesh, the supported reference composition has one broker operator, one space, and three processes:
| Process | Package | Responsibility |
|---|---|---|
| Auth service | @cotal-ai/auth | NATS auth callout, IdP exchange, and JWKS. |
| Delivery service | @cotal-ai/delivery | Durable message delivery for the space. |
| Manager | @cotal-ai/manager | Agent launch, stop, and terminal attachment on one machine. |
The broker operator owns the system account, a dedicated space data account, and a separate auth-callout account. The trust APIs can add several space accounts to one broker. The CLI does not provide per-space teardown, backup, or restore for that shared broker.
If your service only sends and receives Cotal messages, start with CotalEndpoint.
It does not need to host these daemons.
For a client in another language, use Build a client.
Keep signing authority away from agent processes
The auth service and a signer-backed Manager read signing keys into process memory.
A SecretStore supplies those keys; it does not isolate them from a process that can read them.
Use separate OS users or a stronger isolation boundary for untrusted agents.
Review the provisioning limits before creating credentials.
Plan the composition
- Select the packages and public exports your host needs.
- Assign signing authority and durable storage using the provisioning reference.
- Choose process runners or hosted daemon handles.
- Configure the Manager's authority and execution mode.
- Add remote clients or delegated seats only when the host can enforce their authorization contracts.
runAuthService and runDelivery are public process runners.
startAuthService and startDeliveryService return hosted lifecycle handles.
The complete CLI up orchestration and the supervise runner are not public library runners.
Use the Manager class for an in-process supervisor.
Package exports
Find endpoint, daemon, provisioning, authentication, and extension APIs.
Daemon lifecycle
Compare process runners with account-scoped hosted services and credential renewal.
Provisioning and storage
Identify signing authority, durable state, and remaining hosting gaps.
Remote clients
Compose MCP gateways, browser callers, and remote Manager clients.
Service authority
Look up service registration, platform supervisors, revocation, and custody contracts.
Manager authority
Configure local selection, signing policy, and supervised execution.
Delegated seats
Look up remote execution, lifecycle fencing, and recovery requirements.
Find a reference topic
The topic links below preserve section links from the earlier combined guide.
Workspace registry liveness
A liveness sweep keeps registrations and reports offline names. Mismatch pruning is a separate operation. See registry liveness.
Node connection signing
Node connections sign each authentication challenge with fresh credential material. See connection signing.
User credential authority
A provider may return its authoritative grant alongside a bearer. An absent grant answer remains unknown. See user credential authority.
Login confirmation
Manager startup confirms a cached login before saving or launching. See login confirmation.
Older issued-authority stores
Pre-0.111.0 stores require explicit handling before current issuance. See issued-authority stores.
Interactive Manager selection
A trusted host can select the local Manager for an unpinned interactive exchange. See Interactive Manager primary for the opt-in and its limits.
Account connection census
A bounded account census is an observation, not authority to evict or retire a lifecycle. See Account connection census.
Service authority
Service-access proof, registration, and renewal have separate contracts. Opt-in hosted service authority now performs owner approval, name binding, registration, activation, and native caller issuance. See host operations, verified serving access, and caller policy. See Service authority contracts.
Owner-bound platform supervisors
A platform supervisor needs an assignment that binds its owner and instance. See Owner-bound platform supervisors.
Public package exports
Import supported symbols from the published package entry points. See the export reference.
Remote MCP gateway
Each hosted conversation carries its own connection_id on tool calls.
See Remote MCP gateway.
Private tool results
Private tool-result contracts and consent prerequisites do not enable a serving path. See Private tool results.
Browser control
A browser caller uses generated validators and an explicitly selected Manager instance. See Browser control.
Remote Manager clients
The public request builders preserve the stock registration and authority checks. See Remote Manager client composition.
Long-lived endpoint credentials
A bearer function supplies fresh credentials before expiry and reconnect. See Long-lived endpoint credentials.
Daemon entry points
Process runners and hosted handles have different configuration and lifecycle ownership. See Daemon entry points.
Auth service
The process runner reads signing material from its store and local state from the resolved workspace. See Auth process runner.
Delivery service
Delivery uses a scoped credential that another process must renew. See Delivery process runner.
Supervisor signing authority
The Manager's credential source determines which signing and renewal operations it can perform. See Supervisor signing authority.
Delegated seats
Delegated execution keeps worker custody separate from the Manager's local filesystem. See Delegated seats.
Delegated recovery
Recovery requires current authority and lifecycle evidence. See Delegated recovery contracts.
Space provisioning
The one-space provisioning example creates trust, streams, a delivery class, and a scoped delivery credential. See Space provisioning.
Provisioning authority
A SpaceAuth bundle carries account signing authority even after stripSpaceAuth.
See Provisioning authority.
Hosting gaps
Public exports alone do not provide a complete hosted control plane. See Hosted composition gaps.
Durable host state
JetStream coordination state and host-held trust state need different storage plans. See Hosted durability.
Hosted run revocation
Run revocation is a host-authorized operation with lifecycle checks. See Hosted run revocation.
Private result prerequisites
Revocation snapshots and a clock-skew bound are prerequisites for serving private results. See Private tool-result prerequisites.
Native service custody
Native custody guards do not establish the remote host's authority. See Native service custody guards.
Continue
- Substrate stability describes package and protocol guarantees.
- Identity and auth describes profiles and the IdP callout contract.
- Delivery daemon describes the durable message backstop.
- Deploy describes the reference container composition.