Shadow
POST, PUT, PATCH and DELETE are evaluated as they pass and nothing is held or blocked. The tenant proves control of the API's origin at /.well-known/agentsafe-upstream or in a TXT record before the fleet forwards.
API documentation
AgentSafe gateway
AgentSafe is the open execution boundary in front of an agent's consequential actions. Its gateway relays each HTTP write only once Decionis has decided on it and the single-use grant is claimed, and it records the evidence of each attempt. This page states the current release and how it meets the Decionis API.
Versions
Release v0.5.0 shipped on 27 October 2026. The runtime, its container image and its Helm chart share one version; the library and the release tag share another.
| Artifact | Version | What it is |
|---|---|---|
| @decionis/agentsafe | 0.7.0 | The runtime: the HTTP gateway, the TCP connector and tunnel, and the trusted executor, with the agentsafe CLI. |
| docker.io/decionis/agentsafe, ghcr.io/decionis/agentsafe | 0.7.0 | The same runtime as a distroless, non-root image, one digest on both registries. |
| oci://ghcr.io/decionis/charts/agentsafe | 0.7.0 | The Helm chart: one Deployment in front of one Service. |
| @decionis/agent-safe-pipeline | 0.5.0 | The library: intent capture, the Decionis gate, the SafeExecutor, and local test doubles. |
| agent-safe.intent/1 | 1 | The execution intent both send, hashed with RFC 8785 canonical JSON and SHA-256. |
| Decionis API contract | 0.6.0 | The OpenAPI document at /.well-known/openapi.json that this release is built against. |
New in runtime 0.7.0
An operator route can pin a published policy bundle with policyId, policyVersion or both, bound into the hashed intent so a caller cannot override it. A hosted tenant can enforce on a dedicated gateway that holds its API's credential. agentsafe actions manifest writes the action space as one agent-safe.actions/1 document. A write can be held to its target's state version. The CHANGELOG has the rest.
Install
Every install form runs the same runtime. Node.js 22.14 or newer for the npm package.
| Platform | Command |
|---|---|
| npm | npm install --global @decionis/agentsafe@0.7.0 |
| macOS | brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe |
| Linux | curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/packaging/install.sh | sh |
| Docker | docker run --rm ghcr.io/decionis/agentsafe:0.7.0 --help |
| Kubernetes | helm install agentsafe oci://ghcr.io/decionis/charts/agentsafe --version 0.7.0 |
# What reaches a synthetic target with no boundary, in shadow, and under enforcement
agentsafe testCredentials
Five credentials meet at a gateway. Each admits one thing, and none stands in for another.
| Credential | Who holds it | What it admits |
|---|---|---|
| Ingress key: the AgentSafe-Tenant-Key header, also called the tenant key | The agent's host, for a hosted gateway only | Traffic to that gateway. The gateway strips it before relaying, and it means nothing to the Decionis API. |
| Gateway key: a Decionis API key, sent as Bearer | The gateway, never the agent. On the hosted fleet Decionis holds it for you | Decisions and grants for one workspace, nothing else. A hosted gateway's key is a MEMBER key with decision:shadow, or decision:enforce once it enforces. |
| Workspace API key: the ADMIN key onboarding returns | The workspace's administrators | Administering the workspace, including issuing the other keys. It holds org:*, so it belongs in neither a gateway nor an agent. |
| Policy authoring key | The person or pipeline that publishes policy | policy:read and policy:write, issued apart from the gateway key (below). A gateway key never writes policy. |
| Upstream credential | The agent, or the gateway itself when a hosted tenant enforces | The protected API. On an enforcing hosted gateway the agent no longer holds it, so it cannot go around the gateway. |
# Issue a policy authoring key with the workspace API key (ADMIN)
curl -X POST https://api.decionis.com/v1/orgs/<org_id>/api-keys \
-H "Authorization: Bearer $DECIONIS_WORKSPACE_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"policy-author","role":"MEMBER","scopes":["policy:read","policy:write"],"provision_default_policy":false}'
# Publish with it, then name the policy on the gateway's route or mode switch
POST /v1/protocol/policies/bundles (Bearer: the policy authoring key)| Intent mode | The gateway key needs one of | The workspace |
|---|---|---|
| SHADOW | decision:write, decision:run, decision:*, org:*, decision:shadow, decision:enforce | Any, provisional included |
| PARALLEL, ENFORCEMENT | decision:write, decision:*, org:*, decision:enforce | Claimed by an owner |
Enforcement needs an owned workspace
A provisional workspace, one minted without an account, runs SHADOW only: any other mode answers 403 PROVISIONAL_WORKSPACE_SHADOW_ONLY whatever scopes the key holds. An owner claims it through POST /v1/orgs/{org_id}/claim/start and /claim/verify. Claiming does not widen a key's scopes, and a SHADOW success says nothing about whether enforcement will be accepted.
Health and policy checks
A gateway that answers is not yet a gateway that enforces the policy you meant. Check each layer on its own.
| Check | How | What it proves |
|---|---|---|
| Process health | GET /_agentsafe/healthz and /_agentsafe/readyz | The process lives, its listener is bound and an authority is configured. Nothing about keys or policy. |
| Ingress key and relay | A test POST through the gateway | In shadow, agentsafe-mode: SHADOW and agentsafe-execution: PASSTHROUGH: the key admitted the request and the relay reached the API. |
| Gateway key | The same POST, then the decision it produced | A Decision Dossier for that intent exists in the workspace: the gateway's key reached the authority. |
| Policy | Read the verdict and reason codes of that decision | Which rule decided: the Decision Dossier names the rule that matched. A catch-all, such as the starter policy's starter_allow_routine, means no rule names the action yet. |
Hosted gateway
Decionis runs the same runtime as a hosted fleet at {id}.decionisedge.com. Every tenant starts in shadow; enforcement, in private beta, runs on a dedicated gateway that holds the API's credential.
Enforcement
The tenant's own pods: ALLOW forwards once its grant is claimed, BLOCK is 403, ESCALATE is 202 and held, and an unreachable authority forwards nothing.
A hosted TCP resource is reached with the runtime's connector and tunnel, set up under Gateway deployments in the workspace.
Reference
The runtime's own documentation, pinned to v0.5.0.
| Topic | Document |
|---|---|
| Changes in this release | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/CHANGELOG.md |
| Gateway configuration | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/docs/gateway/configuration.md |
| Gateway routes and policy pins | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/docs/gateway/routes.md |
| Deployment, hosted and on premises | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/docs/gateway/deployment.md |
| Hosted TCP relay | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/docs/gateway/hosted-tcp-relay.md |
| CLI reference | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/docs/reference/cli.md |
| Agent-Safe Intent specification | https://github.com/decionis/agent-safe-pipeline/blob/v0.5.0/spec/intent/v1/README.md |