Interocept · Installation and usage

Install the gate, then gate every tool call.

Two parts. An operator runs interocept-gated on a host the agent cannot write to. The agent host installs a small Python client that asks the gate before each tool call runs.

Before you start

What you need.

Two hosts, one socket path between them, and a key for each agent host.

  • Gate host: Linux with Docker, or the built interocept-gated binary. The gate’s code opens no outbound connection.
  • Agent host: Python 3.11 or newer, running the agent that makes the tool calls.
  • A socket path both hosts can reach, such as /run/interocept/gate.sock. Keep it under 108 bytes.
  • Full strength needs activation access to a self-hosted open-weight model (Mode A). A closed-API agent runs in Mode B, which is weaker. We will show you the difference before you deploy.
Step 1 · Agent host

Install the client.

The client is what runs on the agent host. It is separate from the gate and installs from the Interocept source tree, not the gate’s build.

shell
# Core client: gRPC runtime, protobuf and Ed25519 signing. No torch.
pip install ./clients/python

# Add the LangChain adapter, or OpenTelemetry spans for each gated call.
pip install './clients/python[langchain]'
pip install './clients/python[otel]'

The core install brings in grpcio, protobuf and cryptography. It does not bring in torch or any training code.

Step 2 · Gate host

Run the gate.

The gate is a service on its own host. Its keys and policy are signed, and it refuses to start on unsigned or altered files.

2a. Mint a key for each agent host

Keys are minted per role. An agent host gets an extractor key. A reviewer gets a reviewer key. Only public keys go to the gate.

shell
# On the gate host: the public half goes into keys.json.
interocept-keygen --id agent-a --role extractor \
  --private-out /etc/interocept/agent-a.key \
  --public-out  /etc/interocept/keys.json

# Copy agent-a.key to the agent host only. The gate never needs it.

2b. Sign the key file and policy

Changing the key file needs signatures from the root custodians. Changing the policy needs signatures from distinct policy-admins. Both thresholds come from the trust root, so no single person can add a key or put a policy in force.

shell
# Production gates refuse unsigned key files and policies.
interocept-policy sign --keys /etc/interocept/keys.json --key root-1.key --key-id root-1
interocept-policy sign --policy /etc/interocept/latch.json --key infosec.key --key-id infosec

# Optional: check both before a deploy.
interocept-policy verify --policy /etc/interocept/latch.json --keys /etc/interocept/keys.json

2c. Start the gate

The gate listens on a Unix socket created with mode 0600, so only its owner can reach it. The --keys flag is required. There is no flag that starts an unauthenticated gate.

shell
interocept-gated \
  --config  /etc/interocept/latch.json \
  --probe   /etc/interocept/probe.json \
  --lexical /etc/interocept/lexical.json \
  --keys    /etc/interocept/keys.json \
  --socket  /run/interocept/gate.sock \
  --audit   /var/lib/interocept/audit/chain.jsonl

Packaged installs

  • Container: build the gate image from packaging/Dockerfile.gate.
  • Air-gapped: build the bundle with make -C packaging bundle, carry it in, then run packaging/install.sh <bundle-dir>. The script verifies checksums before it loads any image.
Step 3 · Agent host

Use it in your agent.

Create one gate and one keeper per session. Route each tool through keeper.run, which blocks until the gate has decided.

python
from interocept_client import Attestation, Gatekeeper, GrpcGate

gate = GrpcGate(
    "/run/interocept/gate.sock",           # the gate's socket (mode 0600)
    "agent-a",                             # this host's key id, extractor role
    "/etc/interocept/agent-a.key",         # from interocept-keygen --role extractor
    attestation=Attestation.text_only(),   # or attestation_for(extractor, layers)
)
keeper = Gatekeeper(gate, session_id="ticket-4411")
keeper.start(system=SYSTEM_PROMPT, user=user_request)

# The tool runs only if the gate allows it (or a reviewer releases it).
result = keeper.run("send_email", {"to": to, "body": body}, lambda: send(to, body))

With LangChain, wrap the whole tool list the agent receives:

python
from interocept_client.langchain import gate_tools

agent = create_agent(model, gate_tools(keeper, [search_tool, email_tool]))

Optional settings

  • max_wait_s on the keeper caps how long a held call blocks the agent. The gate’s own TTL is 300 seconds by default.
  • capture_text=True adds the transcript and tool results to traces. It copies customer data into the trace store, so it is off by default.
  • Installing the [otel] extra emits one span per gated call. Spans carry decision metadata only, never a score.
Step 4 · Check it works

Verify the setup.

Run the smoke check from the agent host. It sends one read-only call and one destructive call, both benign, and expects an Allow for each.

shell
gate-smoke --socket /run/interocept/gate.sock \
           --key-id agent-smoke --key /etc/interocept-agent/agent.key

It exits 0 only when the gate answers both calls with a decision. Any other result, including a scored Deny, fails the check and should be investigated. The check proves that signing, sessions, scoring and the audit write work end to end. It does not prove detection quality. Measure that on your own traffic before you rely on it.

Usage

What each decision does.

The agent only ever sees the tool’s result or a block message. No score ever reaches the agent, because a score in a refusal would show an attacker where the boundary is.

Gate saysTool runs?Agent sees
AllowYesThe tool’s result
DenyNoBLOCKED by Interocept: … was denied …
Escalate, then a reviewer releases itYes, after the releaseThe tool’s result
Escalate, then refused, expired or past max_wait_sNoBLOCKED … held for review and …

A held call blocks that session until it resolves. Reviewers release or refuse holds with interocept-review, through Slack or PagerDuty. The agent’s own key cannot release anything, because its key has only the extractor role and the gate refuses a self-release.

Limits

What installing Interocept does not give you.

Read these before you describe the product to anyone, including your own team.

It detects exposure, it does not make an agent unbreakable.

The gate flags injection exposure and enforces fail-closed. An attacker with white-box access to the probe can still try to optimise against it. See our published red-team measurement.

Attestation is self-reported.

Attestation.text_only() and attestation_for catch a wrong or drifted build. They do not catch a compromised host, because a modified process can report whatever it likes about itself.

A root on the gate host can replace the binary.

Signed keys and policy stop one person from changing what the gate trusts. They do not stop someone with root on the gate host from replacing the binary.

Every check has a cost.

Each gated call adds latency, and a held call waits on a reviewer until the TTL or max_wait_s. Plan the hold path before you turn on escalation.

Want help with your first install?

Tell us which model you run, where it runs and which tools it can call. We will work through the gate setup with you and show what it would and would not catch.