No FAQs match that search.
Caracal gives agents and automated workflows short-lived, policy-approved authority instead of long-lived credentials. The agent asks for scoped authority at the moment it acts, STS evaluates policy, Gateway or a connector enforces the mandate, and Audit records the decision and result.
See Authority and Enforcement and the Caracal Mental Model.
No. Caracal is an authority broker for agent and workload actions. It can sit in front of HTTP resources like a protected Gateway, and it can broker provider credentials, but it does not replace your IdP, your static config store, or your general API management layer.
Use an IdP for human login, a secret manager for static application configuration, and Caracal when an agent or service needs scoped, auditable authority for a resource.
A zone should represent a trust boundary: the set of resources, sessions, policies, signing keys, and audit records that are allowed to share authority state. Use a separate zone when two workloads need independent signing keys, policy activation, or audit trails. Use one zone with separate resources when the same trust boundary protects multiple upstreams.
For examples, see Model Your Application in Caracal.
No. The open-source Community Edition gives you zones as a manual isolation primitive. You can model customers, environments, or trust tiers with zones and automate them through the Admin API, but managed tenant, team, SSO, and hosted lifecycle features are Enterprise Edition features.
To serve many of your own customers from one deployment without per-customer zones, see Serve Your Own Customers.
See Compare Editions for the commercial feature boundary.
An application is registered software that authenticates to Caracal. A principal is the acting identity, such as a user, service, or agent. An agent session is a time-bounded execution context spawned from a subject session or application context.
Policy decisions consider all of them: which application is asking, which principal is acting, which session anchors the request, and which resource scopes are requested.
No. This is the most common modeling mistake, and it does not match how Caracal scales. An application and an agent are different layers:
The default model is one managed application per durable workload, with many agent sessions under it. When that workload fans out — spawning sub-agents, delegating a narrower slice of authority, or building an agent hierarchy for a single request — each of those is a new agent session under the same application, not a new application. Policy and audit still tell them apart by agent session, lifecycle, labels, and delegation chain (see FAQ-008).
One application per agent breaks this. Managed applications are operator-provisioned, so a workload cannot mint one per spawned agent at runtime. DCR can register at runtime, but a DCR application is meant to expire and bind exactly one session, so per-request fan-out would register and tear down an application for every sub-agent — adding registration latency, credential sprawl, and registry churn for no policy or audit benefit. Reach for an application per agent only when a spawned agent genuinely needs its own isolated, expiring credential and a registry-visible identity; then use a DCR application with one session, as described in FAQ-007.
See Identities and Applications and the Caracal Mental Model.
Use a managed application for durable software you intentionally operate: a backend service, Gateway application, orchestrator, or agent runtime — including the runtime that spawns and fans out child agents. Ordinary spawn fan-out does not need DCR: every spawned child is an agent session under the runtime's own managed application. Reach for DCR only when an identity needs its own isolated, auto-expiring credential boundary — for example a per-tenant or per-integration identity. DCR applications are registered through the zone DCR endpoint as a control-plane action (the SDK spawn() primitive never registers applications), always expire, and bind exactly one session, so a DCR application is not reused across agents and is not a spawn parent for further sessions.
Yes, with one important distinction between attribution and credential isolation.
The agent's identity in a decision is the agent session, not the application. You do not pre-register agents in the Console; the workload that holds the application credential creates each agent session at runtime and declares its labels then, while the coordinator records the session's lifecycle (task for an ordinary session, service for a heartbeat-leased one). The token exchange carries the acting agent_session_id, lifecycle, and labels, plus the delegation edge and chain, alongside the application_id. Policy reads these as input.principal.agent_session_id, input.principal.lifecycle, and input.principal.labels, and audit records the same fields with the parent and delegation context. The Console agent list shows the lifecycle and labels of every session, so you can see which agent is which under a shared application. So two agents under one managed application present different sessions, labels, and delegation paths, and both policy and audit can tell them apart without referencing the application.
What is actually enforced is the authority, not the label. Spawning is gated by application ownership, the asserted agent_session_id is bound to the owning application at exchange, and requested scopes must stay within the delegation chain, which is itself bounded by the parent's authority. The labels, by contrast, are asserted by the credentialed workload and are not delegation-constrained. They are a sound basis for policy and audit when you control and trust the spawner, but they are not a defense against a compromised workload mislabeling its own sub-agents. For that, the boundary is scopes, delegation, and policy.
A single managed application is therefore the right fit for one durable workload that spawns many agents: per-agent attribution comes from the agent session, lifecycle, and labels, not from one application per agent. To investigate a specific agent, the zone audit endpoint filters directly by agent_session_id (one exact session) or by label (a role across a fleet). Reach for a DCR application per agent only when a spawned agent needs its own isolated, expiring credential and a registry-visible identity. What that buys you is credential isolation, not additional policy or audit distinguishability.
See Identities and Applications and Model Your Application in Caracal.
A resource is the protected target and policy audience: the thing a mandate authorizes access to. A provider describes how Gateway authenticates upstream: no credential, Caracal mandate, OAuth, API key, or bearer token.
Keep target identity, scopes, upstream URL, and Gateway binding on the resource. Keep secrets, token endpoints, OAuth settings, API keys, and bearer tokens on the provider.
Policies, grants, mandates, and audit records refer to the resource identifier. If you use a mutable deployment hostname as the identifier, changing infrastructure also changes your authority boundary and breaks audit continuity. Use a stable audience URI such as resource://billing, then change the upstream URL when routing changes.
Use small action-oriented scopes such as payments:read, tickets:comment, or mcp:tool:call. Do not encode environment, tenant, user, or hostname into scope names when that data belongs in the zone, principal, resource, or policy input.
Scopes answer "what action is allowed?" Resource identifiers answer "what target is protected?"
In the current Console flow, you usually define resources, scopes, applications, subjects, and policies rather than managing grants as a separate daily object. Grants are an authorization input that policy can read; the active policy set still makes the final allow, deny, or step-up decision.
If access is denied, inspect the active policy, subject, application, resource, and scopes through request trace.
No. An application secret authenticates the application to Caracal. A provider credential authenticates Gateway or STS to an upstream provider such as Google, Slack, OpenAI, or an internal API. Agents should authenticate to Caracal and receive short-lived mandates; they should not receive long-lived provider credentials.
Use per-user OAuth (oauth2_authorization_code) when the upstream call must act as a specific user and that user must consent. Use a shared service credential (oauth2_client_credentials, api_key, or bearer_token) when the agent acts as the application or service, not as an individual user.
The concrete setup fields are in Provider Recipes.
caracal CLI?The top-level caracal CLI is intentionally limited to local runtime lifecycle and process execution: up, down, status, purge, run, and console. Product-management workflows such as zones, applications, providers, resources, policies, audit, diagnostics, agents, and delegation live in the Console, Admin API, and SDKs so they use one management surface and do not drift into duplicated CLI commands.
A 403 from STS means the exchange was authenticated but policy did not allow the requested resource scopes, or a step-up/grant/session condition blocked issuance. A 403 from Gateway or a verifier means the request reached a protected boundary but the mandate, resource binding, scope check, revocation state, or route safety check failed.
Use request trace with the request ID to identify the surface before changing policy or resource configuration.
The diagnostic bundle is exposed through existing surfaces instead of a separate top-level command. Use caracal status --json for runtime status, Console diagnostics for Doctor checks (health, readiness, zones, preflight), audit for recent decisions, and request trace for a known request ID.
First confirm the request reached a Caracal-protected boundary. If it did, check the selected zone, time window, request ID, Audit service readiness, Redis stream health, replay backlog, and DLQ. If the request failed before STS, Gateway, Coordinator, or a connector emitted evidence, there may be no action-result event for that boundary.
Start with Inspect Diagnostics and Audit and Debug Infrastructure Issues.
Managed multi-tenancy, hosted management UI, managed Gateway and service operation, SSO, SCIM provisioning, teams, organization-level RBAC, commercial support, and enterprise lifecycle features are Enterprise Edition features. The Community Edition remains self-hosted and uses zones, Admin API automation, Console workflows, SDKs, and connectors.
See Compare Editions or book an enterprise call.
Related: FAQ-004
Every agent has exactly one canonical identity: the server-minted agent_session_id. It is unique, returned to the caller the moment spawn() or service() creates the session, and stamped onto every token exchange and audit event that session produces. That id — not the application, lifecycle, or labels — is the answer to "which agent did this?". Even two sessions that share the same application, labels, and metadata are still separated by their agent_session_id in audit.
Identical sessions are interchangeable on purpose. A hundred ["pricing-worker"] sessions fanned out under one application are meant to be fungible — that is how fan-out works, and it is why labels are a descriptor rather than a unique name. When you need to tell sessions apart by meaning rather than by raw id, give them distinguishing labels, attach business correlation in metadata, or propagate a trace_id through the work.
To investigate, the zone audit endpoint filters directly on these fields: query agent_session_id to follow one exact session end to end, or label to scope to a role across a whole fleet of sessions. The Console audit view exposes both filters.
To see the sessions themselves — including ones that have ended — the management API exposes GET /v1/zones/{zone}/agent-sessions, filterable by status (active, suspended, terminated, expired), lifecycle, label, parent_id, and application_id. Rows are never deleted on termination — a session keeps its row and its status flips to terminated or suspended — so this is the authoritative place to review past agents. Add format=csv to the same endpoint to export the filtered set for offline analysis.
Both apply, and they compose as a strict intersection — a logical AND — so the narrower of the two always wins. They are two independent layers with different jobs: a grant (the delegation edge a narrowing spawn(grant=…) creates) caps which scopes the token may carry at all, while policy decides whether the action is allowed. Neither layer can ever add authority; each one can only subtract.
At token exchange a resource is released only if it passes every gate: the requested scopes must be within the resource's own scopes, within the grant edge's scopes (which is itself re-validated to be within the parent's authority), the resource must fall inside the delegation, and policy must return allow. The effective authority is therefore policy ∩ grant ∩ resource ∩ delegation. This holds in both directions: if policy is the narrower of the two, policy wins and the grant cannot widen past it; if the grant is the narrower, the grant wins, because the token cannot request scopes outside the grant and resources outside the delegation are rejected even when policy would have allowed them.
This means there is no "clash" to resolve when a spawned agent runs under its parent's application. A plain spawn() carries no grant edge, so the child runs at the application's full, policy-bounded authority — deliberately identical to the parent, which is what inheriting means. Reach for spawn(grant=Grant.narrow([...])) when the child should hold strictly less; the grant then sub-bounds the authority further while policy continues to apply on top. Because every layer is subtractive, inheriting an application's policy and carrying a grant can only ever narrow access, never expand it.
See Delegation and Policy.
A DCR application is used by authenticating as it, not by spawning under it. Because spawn() always runs under the caller's own application, a DCR application — bound to exactly one session — cannot be a spawn parent. Its single root session is created by a workload that already holds the DCR credentials.
The credential boundary between durable managed identities and short-lived DCR identities is named by registration_method (managed vs DCR), not by an agent's lifecycle. A session's lifecycle is either task (the default) or service (heartbeat-leased), and a DCR application cannot host a service session, so its one session is always a task session. A short-lived worker is therefore not a separate lifecycle — it is an ordinary task session with a TTL (see FAQ-023).
That root session is created by a workload that holds the DCR application's credentials. The control plane registers the DCR application through the Admin API DCR endpoint, which returns a one-time client secret and a short expiry; the SDK never registers applications. An orchestrator injects those credentials into an independently launched workload — for example a per-tenant container — and that workload, configured with the DCR application_id and secret, authenticates with the client_credentials grant and creates its one root session. The application then expires (one hour or less) and is archived by DCR cleanup.
The credential split is deliberate: minting a new credentialed identity is a privileged control-plane action, so a runtime cannot register applications for itself. The SDK consumes a DCR application by being configured with its credentials; only an operator or orchestrator with Admin API access mints one.
Because a DCR root has no parent and no delegation edge, its authority is decided entirely by policy, not by inheritance — and policy is default-deny, so a DCR identity opens no tools until a policy grants it scopes. Policies receive input.principal.registration_method, so you write one policy class targeting registration_method == "dcr" (optionally narrowed by labels, resource, or zone) that covers every DCR application; you do not author a policy per DCR app. Pair that with per-tenant or per-job resources to keep each DCR identity scoped to its own data.
So DCR has a real, distinct purpose that managed applications do not serve: a per-tenant, per-job, or per-integration identity that is credential-isolated, independently revocable, auto-expiring, and registry-visible. What it does not add is extra policy or audit distinguishability — the agent session already provides that. Reach for DCR when you need an isolated, short-lived credential boundary for an independently launched unit of work; use one managed application with many agent sessions for ordinary spawn fan-out.
See Identities and Applications and FAQ-007.
This is the mainstream multi-agent shape, and it is modelled under one managed application. Every node is an agent session under that app. A short-lived worker is not a separate lifecycle: a spawned agent is task-scoped — it dies when its block exits — and "least-privilege" is expressed by a narrowed grant. An optional ttl_seconds adds a hard upper bound for the case where the agent should also expire on a clock (see FAQ-025):
service() handle when it needs a heartbeat lease.spawn() that inherits the application's authority.spawn(grant=Grant.narrow([...])) — bounded to a subset of authority and auto-terminated when its block exits — with ttl_seconds=… added only when you also want a wall-clock cap.On where authority comes from: a spawned agent's authority comes from its application, not from its parent. The SDK authenticates with the client_credentials grant using the configured application_id and secret, so every session under that application already acts under the application's own authority — which is why spawn() needs no parent and a parentless (root) spawn is well-defined. A parent matters only when you narrow authority: grant=Grant.narrow([...]) creates a delegation edge that the server re-validates as a subset of the parent's effective authority, and a cross-application grant goes through delegate(to=peer) with receiver consent. With the default grant=inherit and no edge, the child simply shares the application's authority, bounded by policy.
See Identities and Applications, Delegation, and FAQ-022.
Yes — by default. inherit carries the parent's effective authority forward, so least-privilege is transitive down a same-application spawn tree. Take A spawns B with grant=narrow([tickets:read]), then B spawns C:
B → C edge is recorded holding B's exact scopes, resource, constraints, and expiry. C is therefore bounded by B's tickets:read slice — it does not regain the application's full authority. A narrowed intermediary contains its descendants without you having to re-narrow at every hop.B → C edge is recorded and the coordinator rejects it unless C ⊆ B (scopes, TTL, hop count, budget, and resource are all checked). So B can never pass on authority it does not hold.Transitive inheritance is enforced for same-application spawns, where the mirrored edge is escalation-proof by construction (the child copies the parent edge and can never broaden it). It is not auto-created across applications: a cross-application grant must go through delegate(to=peer) with receiver consent. The hard, server-enforced boundary that contains every session is still the application plus policy (default-deny); to place a subtree behind a real cross-trust boundary, give it a different application via delegate(to=peer).
See Delegation and FAQ-023.
Every runtime actor is an agent session; lifecycle only describes how it runs. There are two lifecycles, and they map directly onto the two SDK primitives:
spawn(), recorded as lifecycle = "task". It lives for the duration of its task: when its block exits it is terminated automatically. This single behavior covers both of the cases you are distinguishing. A "do one task and die" worker (for example a search sub-agent) is just spawn() whose block returns when the task is done. A "live up to N seconds then expire" worker is the same spawn() with ttl_seconds=N, which adds a hard wall-clock cap enforced by the TTL sweeper. The difference between "task-and-die" and "time-limited" is whether you set a TTL, not a different lifecycle.service(), recorded as lifecycle = "service". It is the genuinely different lifecycle: it outlives any single task and is kept alive by a heartbeat lease, so the runtime can detect and reap it if it stops reporting. A service is governed only by that lease — it is not subject to the wall-clock TTL sweeper that retires tasks, so a faithfully heartbeated service is never terminated on a timer. Each heartbeat() renews the lease (extends the deadline); it does not just check status. The SDKs offer an opt-in background auto-heartbeat (heartbeat_interval / heartbeatIntervalMs) so the lease stays current even while your code is blocked awaiting a long provider stream.The stored lifecycle column carries exactly these two values, and only service changes runtime behavior (the heartbeat lease). The default is task — named for the lifecycle, not the actor, so it never collides with the "agent" umbrella that every session already belongs to. So how long a worker lives is expressed by task scope and an optional TTL, not by a separate lifecycle. Reach for service() when you need a durable, heartbeat-leased agent; otherwise use spawn() and let task scope (optionally plus a TTL) express how long the worker should live.
See Identities and Applications and FAQ-023.
Different policies per DCR app: yes. Policy evaluation receives the full principal, including the specific input.principal.id (the application id), input.principal.labels, and input.principal.registration_method. Matching on registration_method == "dcr" is just the convenient way to write one rule that covers every DCR app; when two DCR apps need different authority, target their distinct application ids or labels, or scope them to different resources. There is no requirement that all DCR apps share a policy.
Can a DCR-application agent spawn children: no, in practice. A DCR application binds exactly one agent session (a second spawn under the same DCR app is rejected with dcr_application_already_bound), so a DCR session cannot create further sessions under its own application — it is a leaf. Spawning a child under a different application would require cross-application spawn authority that a DCR workload is not granted. So a DCR identity is a single, isolated, non-parent session by design.
Which sessions can be parents: any session under a managed application can spawn children via spawn(), with one lifecycle rule — a task parent cannot spawn a service child (task_agent_cannot_spawn_service). A task is bounded by its work or its TTL, so it must not mint a durable, lease-renewable session that could outlive it; a service parent may spawn either lifecycle. The only structural non-parent is the DCR session described above — it can be neither a parent (dcr_application_cannot_spawn) nor a spawned child (dcr_application_cannot_be_child). So the practical answer is that managed sessions spawn (task parents to task children, service parents to either) and DCR sessions are isolated leaves.
See Identities and Applications and FAQ-022.