mcp

AgentSafe

Put an authority boundary in front of any agent or API.

AgentSafe intercepts consequential actions and checks whether they are authorized before forwarding them. An agent, an application or a tool sends its HTTP request to AgentSafe instead of the target; AgentSafe captures the action as an intent, asks the Decionis control plane (the Independent Execution Authority, bound to the exact action) for a decision, and forwards exactly the authorized request once on a claimed single-use grant, holds it for a person, or refuses it, leaving a chained record of each. It decides nothing itself.

brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe

agentsafe proxy \
  --upstream http://localhost:3000 \
  --port 8080

5-minute quickstart · Homebrew · Linux · Docker · Kubernetes · Hosted

Agent integration and deployment guide: put the gateway in front of tool calls, deploy on premises, or connect to the Decionis-managed shadow gateway.

Deployment strategies: Docker with TLS ingress, Kubernetes, Istio, AWS and Azure network isolation, and deployment acceptance checks.

The installed forms are produced by the release workflow from v0.2.0 on; the Homebrew formula reaches master by its own pull request after each release. The same commands run from a clone, as the quickstart shows.

The path from here is short: discover, install, test your boundary, see what is exposed, run in shadow, enforce, deploy.

The two systems behind the boundary

Arriving here for the first time, you meet three names. This repository is one of them; the other two are the services it talks to, and neither is in this repository.

• Decionis is the Independent Execution Authority, bound to the exact action: the control plane AgentSafe asks. For one captured intent it evaluates the organization's policy and answers ALLOW, ESCALATE or BLOCK; an ALLOW comes with the single-use execution grant the request executes on, an ESCALATE with the human ceremony it needs, and every decision with a signed Decision Dossier that records what was proposed, what was decided and why. It runs at decionis.com (docs); the local demo authority in this repository stands in for it on loopback with a synthetic policy, and says so on every line.
• Presence is the adaptive human verification layer. When Decionis answers ESCALATE, a verified, present person on their own device approves that exact action, and the signed Presence Record that results is evidence Decionis re-checks before it issues a grant, never authority by itself. It runs at presence.decionis.com (what the layer is); the loopback double in this repository simulates the ceremony for the examples and proves nothing about a real one.
• AgentSafe, this repository, is the execution boundary between your agent or API and those two: it captures the exact intent, asks Decionis, resolves an ESCALATE with Presence, forwards exactly the authorized request once on the claimed grant, holds or refuses the rest, and leaves chained evidence. It is Apache-2.0 and it decides nothing; OPEN-CORE.md states the seam between it and what Decionis operates.

One sentence separates the two systems agents are usually given: decision intelligence determines what an AI wants to do; execution authority determines whether it is permitted to happen. The boundary here binds the second to the exact action, never to the identity that proposed it, because the realistic adversary is not a forged credential but a valid one: an agent whose identity is real, whose credential is current, and whose request is not what anyone authorised. As agents get faster and more autonomous, identity becomes a weaker proxy for authority; the Compromised Principal Test is that failure stated as a test the boundary passes on every pull request, with three ways to run it in under a minute and what each proves; THREAT-MODEL.md states it as a threat.

Test your boundary

Before putting the gateway in front of anything, see what it changes. agentsafe test sends the same consequential requests three ways at a synthetic target that records what reaches it: directly, as an agent with nothing in the way; through the gateway in shadow; and through the gateway in enforcement. Nothing real is called and nothing of yours is read.

agentsafe test

                                                direct                                shadow                                                     enforcement
A read                                          reached 200                           reached 200                                                reached 200 (not consequential)
A payment within policy                         reached 201                           reached 201, would ALLOW                                   ALLOW: forwarded once, 201, dossier
A payment above the human ceiling               reached 201                           reached 201, would BLOCK                                   BLOCK 403, NOT FORWARDED
A payment above the autonomous ceiling          reached 201                           reached 201, would ESCALATE                                ESCALATE 202, HELD
Deleting a customer record                      reached 204                           reached 204, would ESCALATE                                ESCALATE 202, HELD
A forged approval on a blocked payment          reached 201, forged headers accepted  reached 201, would BLOCK                                   BLOCK 403, NOT FORWARDED
A consequential request the policy cannot read  reached 201                           reached 201, would ESCALATE                                ESCALATE 202, HELD
A payment while the authority is unreachable    reached 201                           reached 201, would decide nothing (authority unreachable)  AUTHORITY UNAVAILABLE 503, NOT FORWARDED
                                                with failurePolicy failOpen (explicit): reached 201, marked FORWARDED (fail-open, ungoverned)

Exposure    6 of 6 adversarial actions reached the target directly, 6 of 6 in shadow, 0 of 6 under enforcement
Work        routine actions went through under enforcement, once each
Evidence    26 chained lines, verified

Caller      the same on every row, and never the reason: the target took every direct request; the boundary decided on the action
Verdict     BOUNDARY HOLDS

Next: agentsafe proxy --upstream <your service> --mode shadow, then --mode enforcement.
✓ boundary tested

The gateways under test are the ones agentsafe proxy runs, behind the same listener; the authority is the local demo policy. agentsafe test ledger=ledger.internal:443 also dials a real system of record from where you stand and says whether it answers without the gateway, which is what an agent could reach by going around. Exit 0 is a boundary that holds; 1 is exposure; --json is the report as one line. The release smoke test runs it on every packaged binary. The Caller line is the point: nothing above was refused for who asked, only for what was asked, which is the Compromised Principal Test in one table; the last line is the step of the adoption path the run is.

With a workspace, agentsafe test --hosted sends the same requests with Decionis deciding, in shadow, at the same synthetic target: the first governed action against Decionis for that workspace, one signed Decision Dossier per consequential request, and the first record fetched with the run's own key and shown by its proof. agentsafe login --provision mints the workspace in one command, no account; the test takes about as long as the local one.

Five-minute quickstart

Nothing here needs an account: without a Decionis key the gateway runs a local demo authority in the same process, on loopback, with a synthetic policy, and says so on every line.

agentsafe proxy --upstream http://localhost:3000 --port 8080

AgentSafe 0.2.5

Gateway      http://127.0.0.1:8080
Upstream     http://localhost:3000
Mode         ENFORCEMENT
Authority    local/demo (synthetic policy on loopback; not Decionis)
Failure      fail-closed
Routes       none named; every unsafe method is governed
Evidence     not written; use --verbose or evidence.journalDir
Status       READY

Waiting for consequential actions...

Send it one request:

curl -i -X POST http://127.0.0.1:8080/payments -H 'content-type: application/json' -d '{"amount": 500}'

ESCALATE

POST /payments

Action       http.post
Decision     ESCALATE
Reason       HUMAN_APPROVAL_REQUIRED
Execution    HELD
Dossier      synthetic-dossier-1
Latency      4ms

The caller gets 202 and nothing reached the upstream. {"amount": 50} is ALLOW: forwarded once, byte for byte, with the dossier id beside the upstream's own answer. {"amount": 5000} is BLOCK: 403, not forwarded. A GET passes through untouched. Every state has its own heading and, with a terminal, its own color: ALLOW, BLOCK, ESCALATE, SHADOW, AUTHORITY UNAVAILABLE. --verbose shows the chained evidence lines; agentsafe init writes the configuration file; agentsafe doctor says what would stop it from governing; agentsafe login connects a Decionis key, after which the same gateway asks Decionis, in shadow first. A gateway in shadow keeps its own shadow report: what enforcement would have held or refused so far, by action, and how many of those refusals the upstream accepted as sent, which agentsafe status prints, the gateway prints when it stops and on its own cadence as it runs, ending with the one switch that turns enforcement on; agentsafe login --provision mints the free Decionis workspace that switch names. The quickstart is the full walk, and the CLI reference every command.

How it works

Agent / Application / Tool
          │
          ▼
      AgentSafe
   ingress / interceptor          captures the action as an intent (agent-safe.intent/1)
          │
          ▼
 Decionis Control Plane           policy, ExecutionBinding, Presence, Decision Dossiers
          │
   ALLOW | BLOCK | ESCALATE
          │
          ▼
      AgentSafe                   claims the single-use grant, forwards the exact bytes once
          │
          ▼
   Target Service / API
          │
          ▼
       finalize                   COMMITTED | FAILED | INDETERMINATE, on the Decision Dossier

AgentSafe owns ingress and interception, action extraction and normalization, enforcement of the verdict, claim-before-forward, forwarding, effect evidence, finalization, fail-safe behavior and the local ergonomics. Decionis owns execution authority: policy evaluation, ALLOW / BLOCK / ESCALATE, policy versioning, ExecutionBinding semantics, Presence verification, Decision Dossiers, and the verification of evidence and authority. AgentSafe is not a second policy engine: the local demo authority is a loopback double of the Decionis routes, named local/demo everywhere, refused in production.

What is bound and forwarded, and what each outcome finalizes as, is docs/gateway/http-interception.md; what happens when the authority cannot be reached is docs/gateway/failure-policy.md; the configuration, one schema for every distribution with the precedence flags, environment, file, defaults, is docs/gateway/configuration.md. The gateway is addressed: the workload is pointed at it. agentsafe intercept holds the same boundary without configuring the workload, by redirecting a pod's or a container's outbound 80 and 443 into AgentSafe at the network layer, reporting every destination it reaches, and governing the ones the operator names under an authority the workload trusts; docs/gateway/transparent-interception.md says what is observed, what is governed, and what the authority costs.

Install

One runtime, five ways to run it. The executable, the packages, the image and the chart are built and smoke-tested by the release workflow from the same code; nothing about authority, binding, claim or finalization differs between them.

Every install page ends at the same place: send your first governed action.

Govern, the workflow gate, ships with the same releases as one static binary per platform: curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/govern/install.sh | sh, brew install govern from the same tap, or go install github.com/decionis/agent-safe-pipeline/govern/v2/cmd/govern@v2.1.0; its README has the rest.

Golden adversarial demo

One legitimate path and eight adversarial attempts against the same boundary, offline, in a few seconds, with every expectation asserted:

git clone https://github.com/decionis/agent-safe-pipeline.git && cd agent-safe-pipeline
pnpm install --frozen-lockfile
pnpm --filter @decionis/agent-safe-example-golden-adversarial demo

A treasury agent proposes a USD 250,000 wire, a remote Chief Risk Officer completes a FIDO2 plus liveness ceremony, and exactly one wire executes. Injected authorization fields, a fabricated ALLOW, an asserted approval, a swapped receipt, a post-approval amount change, a replayed grant, 25 concurrent claims, a shadow observation, and an expired grant all fail to execute. The run exits 0 only when that holds. See examples/golden-adversarial-demo, the bank-audience walkthrough in docs/remote-cro-authorization.md, and the receipt semantics in docs/presence-evidence.md.

The same proof for infrastructure, and for the adversary a credential check cannot catch:

pnpm --filter @decionis/agent-safe-example-infra-scale demo

An infrastructure agent with a valid identity and a valid credential proposes deployment.scale for inference in prod-eu at 96 replicas and is allowed. The same agent, with nothing forged, then proposes 960 replicas, a service outside its remit, another cluster, the 96 decision with 960 substituted after authorization, an approval for 256 presented for 512, a replayed grant, and a direct call to the cluster: nothing executes, because authority was bound to the exact action and not to the identity. See examples/infra-scale-demo and the Compromised Principal Test.

Execution lifecycle

For a consequential action, in every distribution and in the library alike:

request → normalize intent → enforce-and-bind → ALLOW