# Embedding 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`](https://github.com/Cotal-AI/Cotal/blob/main/bin/cotal.ts). For CLI automation, agent tools, and wire clients, see the [API reference](/api-reference/api-reference/). Read [Architecture](/docs/architecture/), [Identity and auth](/docs/identity-and-auth/), and the [Delivery daemon](/docs/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](/docs/build-a-client/). > **Warning: 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](/docs/embedding-provisioning/#hazardous-provisioning-primitives) before creating credentials. ## Plan the composition 1. Select the packages and [public exports](/docs/embedding-exports/) your host needs. 2. Assign signing authority and durable storage using the [provisioning reference](/docs/embedding-provisioning/). 3. Choose [process runners or hosted daemon handles](/docs/embedding-daemons/). 4. Configure the [Manager's authority and execution mode](/docs/embedding-manager/). 5. Add [remote clients](/docs/embedding-remote-clients/) or [delegated seats](/docs/embedding-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](/docs/embedding-exports/) Find endpoint, daemon, provisioning, authentication, and extension APIs. [Daemon lifecycle](/docs/embedding-daemons/) Compare process runners with account-scoped hosted services and credential renewal. [Provisioning and storage](/docs/embedding-provisioning/) Identify signing authority, durable state, and remaining hosting gaps. [Remote clients](/docs/embedding-remote-clients/) Compose MCP gateways, browser callers, and remote Manager clients. [Service authority](/docs/embedding-service-authority/) Look up service registration, platform supervisors, revocation, and custody contracts. [Manager authority](/docs/embedding-manager/) Configure local selection, signing policy, and supervised execution. [Delegated seats](/docs/embedding-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](/docs/embedding-exports/#workspace-registry-liveness). ### Node connection signing Node connections sign each authentication challenge with fresh credential material. See [connection signing](/docs/embedding-exports/#node-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](/docs/embedding-exports/#user-credential-authority). ### Login confirmation Manager startup confirms a cached login before saving or launching. See [login confirmation](/docs/embedding-exports/#login-confirmation). ### Older issued-authority stores Pre-0.111.0 stores require explicit handling before current issuance. See [issued-authority stores](/docs/embedding-provisioning/#issued-authority-stores-from-before-01110). ### Interactive Manager selection A trusted host can select the local Manager for an unpinned interactive exchange. See [Interactive Manager primary](/docs/embedding-manager/#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](/docs/embedding-service-authority/#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](/docs/embedding-service-host/), [verified serving access](/docs/embedding-service-access/), and [caller policy](/docs/embedding-service-callers/). See [Service authority contracts](/docs/embedding-service-authority/#service-authority-contracts). ### Owner-bound platform supervisors A platform supervisor needs an assignment that binds its owner and instance. See [Owner-bound platform supervisors](/docs/embedding-service-authority/#owner-bound-platform-supervisors). ### Public package exports Import supported symbols from the published package entry points. See the [export reference](/docs/embedding-exports/#the-export-surface). ### Remote MCP gateway Each hosted conversation carries its own `connection_id` on tool calls. See [Remote MCP gateway](/docs/embedding-remote-clients/#remote-mcp-gateway). ### Private tool results Private tool-result contracts and consent prerequisites do not enable a serving path. See [Private tool results](/docs/embedding-remote-clients/#private-tool-results). ### Browser control A browser caller uses generated validators and an explicitly selected Manager instance. See [Browser control](/docs/embedding-remote-clients/#browser-control). ### Remote Manager clients The public request builders preserve the stock registration and authority checks. See [Remote Manager client composition](/docs/embedding-remote-clients/#remote-manager-client-composition). ### Long-lived endpoint credentials A bearer function supplies fresh credentials before expiry and reconnect. See [Long-lived endpoint credentials](/docs/embedding-exports/#long-lived-endpoints-take-a-bearer-function). ### Daemon entry points Process runners and hosted handles have different configuration and lifecycle ownership. See [Daemon entry points](/docs/embedding-daemons/#booting-the-daemons). ### Auth service The process runner reads signing material from its store and local state from the resolved workspace. See [Auth process runner](/docs/embedding-daemons/#auth-service). ### Delivery service Delivery uses a scoped credential that another process must renew. See [Delivery process runner](/docs/embedding-daemons/#delivery). ### Supervisor signing authority The Manager's credential source determines which signing and renewal operations it can perform. See [Supervisor signing authority](/docs/embedding-manager/#supervisor-signing-authority). ### Delegated seats Delegated execution keeps worker custody separate from the Manager's local filesystem. See [Delegated seats](/docs/embedding-delegated-seats/#delegated-seats-outside-the-managers-filesystem). ### Delegated recovery Recovery requires current authority and lifecycle evidence. See [Delegated recovery contracts](/docs/embedding-delegated-seats/#delegated-recovery-contracts). ### Space provisioning The one-space provisioning example creates trust, streams, a delivery class, and a scoped delivery credential. See [Space provisioning](/docs/embedding-provisioning/#provisioning-a-space-one-space-reference-shape). ### Provisioning authority A `SpaceAuth` bundle carries account signing authority even after `stripSpaceAuth`. See [Provisioning authority](/docs/embedding-provisioning/#hazardous-provisioning-primitives). ### Hosting gaps Public exports alone do not provide a complete hosted control plane. See [Hosted composition gaps](/docs/embedding-provisioning/#hosted-composition-gaps). ### Durable host state JetStream coordination state and host-held trust state need different storage plans. See [Hosted durability](/docs/embedding-provisioning/#hosted-durability). ### Hosted run revocation Run revocation is a host-authorized operation with lifecycle checks. See [Hosted run revocation](/docs/embedding-service-authority/#hosted-run-revocation). ### Private result prerequisites Revocation snapshots and a clock-skew bound are prerequisites for serving private results. See [Private tool-result prerequisites](/docs/embedding-service-authority/#private-tool-result-prerequisites-not-serving). ### Native service custody Native custody guards do not establish the remote host's authority. See [Native service custody guards](/docs/embedding-service-authority/#native-service-custody-guards). ## Continue - [Substrate stability](/docs/stability/) describes package and protocol guarantees. - [Identity and auth](/docs/identity-and-auth/) describes profiles and the IdP callout contract. - [Delivery daemon](/docs/delivery-daemon/) describes the durable message backstop. - [Deploy](/docs/deploy/) describes the reference container composition.