What is ScopeGate?
ScopeGate is an open-source (Apache-2.0) ephemeral-credentials gateway for coding agents — Claude Code, Kimi Code, Cursor, OpenCode, and any MCP-capable harness. The agent never holds secrets; it holds short-lived, minimum-scope capabilities minted per task. Real secrets live in an AES-256-GCM encrypted local vault and are injected only at the outbound hop — so a leaked model context leaks nothing of durable value. Think of it as AWS IAM + STS for coding agents, installable by the agent itself in under 90 seconds.
Long-lived credentials don't survive contact with agents
Coding agents today run with your real secrets sitting in their context —
.env files, MCP configs, shell environment. That creates two structural failures:
01 Exposure
Every secret the model reads is potentially leakable — transcripts, logs, prompt injection. So you rotate constantly, just in case, and audit by hand when something slips.
02 Expiration
OAuth tokens for MCP servers die in the middle of four-hour agentic sessions. The workflow breaks, the agent stalls, a human has to re-authenticate.
exposed The agent reads .env with AWS_SECRET_ACCESS_KEY — the key is now in the transcript.
broken Two hours into a four-hour refactor, the Notion OAuth token dies. The workflow stalls until a human re-authenticates.
blast radius That transcript gets synced, logged and indexed. You rotate everything and audit by hand.
| Scenario | Without ScopeGate | With ScopeGate |
|---|---|---|
| Agent deploys to staging | AWS keys in .env, visible to the model |
STS token, 10 min TTL, scope deploy:staging |
| 4-hour session with an MCP | OAuth expires at hour 2, workflow broken | Refresh daemon renews before expiry, transparently |
| Key leaked in a transcript | Rotate everything, audit manually | Token already expired; the signed audit shows exactly what it touched |
| Onboarding a new service | A human copies keys into configs | The agent calls scopegate_register_upstream and it's done |
How it works
Three steps. The only human moments: depositing secrets and approving escalations.
1 Init
scopegate init creates the encrypted vault, detects your harness
(Claude Code, Kimi Code, Cursor, OpenCode, .mcp.json) and migrates
existing MCPs behind the gateway — plaintext secrets move into the vault.
2 Deposit secrets
scopegate secret add github_pat — hidden prompt or piped stdin,
never through chat, never via argv. This is the one human-only path, once per secret.
3 Agent operates
The agent requests capabilities (github:write:repo/*, 15 min),
gets TTL grants from the policy engine, and never sees the credential that
authorizes the call.
Requests leave the agent with no secrets; the credential is injected only on the outbound hop.
The same flow, as text
Agent/CLI ──(MCP, zero secrets)──► ScopeGate ──(creds injected)──► GitHub / AWS / your MCPs
│
vault + policy engine + token minter + refresh daemon + signed audit
$ npm i -g scopegate && scopegate init
✓ vault created (~/.scopegate, AES-256-GCM)
✓ harness detected: claude-code — 3 MCPs migrated, 2 plaintext secrets vaulted
✓ gateway registered as the single MCP entry point (backup: .mcp.json.pre-scopegate.bak)
$ scopegate secret add github_pat
( hidden prompt — the value never touches the transcript )
✓ github_pat stored in the vault
# from here, the agent operates alone —
> scopegate_request_capability { capability: "github:write:scopegate/*", ttl: "15m" }
✓ granted · expires in 14m59s
first tool call at 87s — zero secrets in context
Watch a grant live
A capability the agent might hold right now:
When it hits zero it is gone for good — a leaked token is worth ~zero in ~60 seconds. The agent simply requests a fresh one.
Everything between the agent and your secrets
Encrypted vault
AES-256-GCM at rest. Optional process isolation (scopegate vaultd)
over unix socket / named pipe, master key in DPAPI, Keychain or Secret Service.
Policy engine
Declarative YAML: per-agent scopes, TTL ceilings, rate limits, PII redaction.
Hard limits are fail-closed — deny globs beat any rule. Agents preflight
with scopegate_can_i instead of learning from denials, and reconstruct
state after restarts with scopegate_recall.
Token minter
Real ephemeral credentials: gateway JWTs, GitHub App installation tokens, AWS STS session credentials, Google service-account tokens, Huly workspace tokens.
OAuth refresh daemon
Renews upstream tokens proactively at 80% of their TTL, retries transparently on 401, and uses RFC 8628 device-code for human re-auth. Zero broken sessions.
Signed audit trail
Append-only, hash-chained, Ed25519-signed JSONL. Inputs are hashed, never stored.
scopegate audit verify detects tampering in seconds.
Honeytokens
Canary credentials that trigger surgical revocation the moment an agent touches them — exfiltration attempts contain themselves.
Approval continuation
The agent queues the exact call with execute_on_approval; the gateway
runs it the moment a human approves — from the CLI or the panel. No polling
loops, no abandoned tasks: approvals complete work.
Machine-readable errors + circuit breaker
Every failure is a structured envelope — {kind, next_action, retry_after_s} —
so agents decide retry/renew/escalate without guessing. Dead upstreams fail
fast behind a per-upstream circuit breaker; 429s are absorbed server-side.
Task leases
Grants that survive hours-long tasks: a double budget (total time,
hard-clamped at 4 h; write count) with agent-driven renewal
(scopegate_renew_capability) and a structured warning at 20% TTL —
the task finishes instead of dying at 70%.
Idempotent writes
One _sg_idempotency_key per intention: the gateway dedupes retries
for 24 h — replayed results without a second upstream write, and an explicit
conflict when a key is reused for a different intention.
Result handles
An 80 KB tool response never floods the context window: the gateway persists
it (after policy redaction) and returns a preview + result_ref.
The agent pages with result_get and searches with result_grep.
One approval per plan
scopegate_request_plan submits the whole task at once: auto parts are
issued, guarded parts become a single aggregated approval with the full blast
radius — one informed human decision instead of seven popups.
Git credential helper
scopegate git-credential plugs into git credential fill:
every clone/push gets a freshly minted GitHub App installation token — never in
the remote URL, never in .git/config, governed by the same policies.
Arg-aware policies
when: clauses guard the call's arguments, not just the tool:
pushes to kimi/* branches auto-approve while main
escalates to a human. The guard sticks to the issued grant.
Approvals that don't break flow
wait: true long-polls the human decision inline and returns the grant
in the same call. Requests and decisions push to Slack, HMAC webhooks or Huly —
the human answers where they already are.
One gateway, many identities
The X-ScopeGate-Agent header selects the logical agent per request
(validated against the policies allowlist): one gateway serves many threads with
separate grants, audit trails and approval queues.
Any REST API, governed
Point the openapi transport at an OpenAPI 3 spec and every operation
becomes a governed MCP tool — schemas, policies, TTLs and audit included.
No custom bridge, no wrapper code.
Embeddable + testkit
import { createGatewayServer } from "scopegate" runs the gateway
in-process (no subprocess, no daemons). scopegate/testkit ships a
fake upstream so consumers test integrations with zero real credentials.
Host observability
scopegate_events and GET /events stream a metadata-only
tail for host UIs; /health reports readiness (upstreams, vault,
pending approvals); upstream state changes push MCP log notifications.
Governed file injection
Legacy CLIs read keys from files. scopegate inject materializes a
vault secret into a config file — human approval by default, atomic 0600 write,
sha256-only audit, one-command refresh after rotation.
The agent installs, configures and operates it — by itself
ScopeGate is designed so the agent is the installer and the operator.
Time from init to first proxied tool call: under 90 seconds, no human in the loop.
Self-onboarding protocol
A published SKILL.md teaches the agent the rules: never ask the user
for an API key in chat — ask them to run scopegate secret add.
Missing a tool? Call scopegate_request_capability.
Write asymmetry, by design
Agents can propose new policy rules; only humans approve privilege escalations — from their terminal, from Slack, or from the Cloud panel. That asymmetry is the heart of the security model.
Built for long agentic tasks
ScopeGate solves "the agent must never hold secrets" — and the second half too: "and it must still finish the task." Every one of these ships in the gateway today.
01 Task leases
Grants survive hours-long work: a double budget (total time, hard-clamped; write count) with agent-driven renewal and a 20%-TTL warning.
02 Approval continuation
execute_on_approval queues the call; the gateway runs it the moment a human approves — the task completes instead of waiting.
03 Policy preflight
scopegate_can_i answers allow / needs-approval / deny with zero side effects — the agent plans instead of learning from denials.
04 One approval per plan
The whole task submitted at once; guarded capabilities become a single aggregated human decision with the full blast radius.
05 Subagent delegation
Attenuated child grants (scope ⊆ parent, TTL ≤ parent) with the attribution chain — revoking the parent kills every child.
06 Idempotent writes
One idempotency key per intention; the gateway dedupes retries for 24 h — no duplicate issues, no double deploys.
07 Result handles
Oversized payloads truncate to a result_ref with preview + stats; the agent pages with result_get/result_grep instead of burning context.
08 Error taxonomy + health
Every failure is a machine-readable envelope (kind, next_action, retry_after) — plus a per-upstream circuit breaker and health as an MCP tool.
09 Audit recall
The agent's own signed audit becomes session memory: actions, writes, grants, pending approvals — rebuild state after any restart or compaction.
10 Taint tracking
Return-path prompt-injection defense: tainted responses mark the session, and cross-upstream writes degrade to human review automatically.
+1 Hot-reload
scopegate secret add while running re-injects fresh credentials on the next call — no agent-session restart, no context loss.
Native connectors & signed registry
Ready-to-run MCP bridges, each installable from the signed registry with
scopegate_register_upstream {from_registry}.
| Connector | Tools | Auth |
|---|---|---|
| github | Full GitHub MCP via gateway | GitHub App installation tokens, minted per task |
| aws | STS-scoped sessions | AssumeRole / GetSessionToken, TTL-clamped |
| huly | 16 tools — issues, projects, documents, channels, contacts | Workspace token minted from a vault blob |
| railway | 7 tools — services, deploy, logs, domains | Account token in vault; deploys can require human approval |
| cloudflare | 8 tools — zones, DNS, workers, pages, R2 | Scoped API token in vault |
| 7 tools — Drive, Gmail, Calendar | Service-account JWT → short-lived access token |
Plus any MCP server over stdio or HTTP behind the proxy, and agent-to-agent attestation (EdDSA JWT, ≤ 60 s) so third-party MCPs can tell agents apart.
ScopeGate Cloud — the management plane
Optional, multi-tenant, and structurally unable to hold your secrets: it syncs metadata only. If Cloud is down, your gateways keep enforcing the last signed policy — local-first is the design, not a fallback.
Fleet & capabilities
Every enrolled agent, its active grants and remaining TTLs, in one view.
Team policies
Versioned, cloud-signed YAML distributed to gateways. The effective policy is never more permissive than the local one.
Human approvals
Escalated capability requests land in a queue. Approve or deny from the panel or Slack — and approving can execute the agent's queued call on the spot, so the task completes instead of just unblocking.
Fleet revocation
Revoke one agent or the whole team with explicit blast-radius confirmation. Effective in under 30 seconds on online gateways.
Central audit
Hash-chain-verified ingest per gateway. Query by agent, kind, or window; export signed JSONL to your SIEM.
Active-agent billing
You pay for agents that actually did something in the month — not for installations.
Pricing
Open Source
$0
- Full gateway, vault, policy engine, minter
- OAuth refresh daemon & multi-harness init
- Signed audit, honeytokens, red-team suite
- Apache-2.0, self-hosted forever
Team
$20 / active agent / mo
- Cloud panel: fleet, capabilities, approvals
- Team policies, signed & versioned
- Central audit (90-day retention) & Slack alerts
- Fleet revocation < 30 s
Early access
Enterprise
Contact
- SSO / SAML, on-prem control plane
- SIEM export (CEF/syslog, signed webhooks)
- Unlimited audit retention
- SOC2 controls & evidence pack
Security model
- Secrets never enter the model's context. They arrive via CLI/stdin, live encrypted, and leave only on the upstream hop.
- Capability ≠ credential. Grants expire in minutes and are scoped to one task; what the vault keeps never enters the context.
- Write asymmetry. Agents propose policies; only humans approve escalations.
- Raw-secret smuggling is rejected. A
looksLikeSecret()guard refuses secret-shaped values passed as refs — at the gateway and at cloud ingest. - Fail-closed hard limits.
denyglobs andmax_ttlbeat any rule, any agent, any time. - Blast radius per agent. Revoking one agent touches nobody else — and everything it did is attributable in the signed audit.
FAQ
Does ScopeGate ever see my secrets?
The local vault does — encrypted at rest, never in the model's context. The Cloud control plane never does: it syncs metadata only (agent identities, policy documents, hashed audit events), and a guard at ingest rejects anything that even looks like a secret.
What happens if ScopeGate Cloud goes down?
Nothing, from the agent's point of view. Gateways keep enforcing their local
policies.yaml plus the last cloud-signed team policy from cache.
Zero tool calls are blocked by the control plane being unreachable.
Which agents and harnesses are supported?
Anything that speaks MCP. Init auto-detects Claude Code, Kimi Code, Cursor,
OpenCode and generic .mcp.json configs, and migrates existing
servers behind the gateway with a restorable backup.
How do I revoke a compromised agent?
From the Cloud panel (one click, reason required) or locally with
scopegate. Online gateways enforce it in under 30 seconds;
offline ones revoke on reconnect — and their outstanding tokens have already
expired by TTL anyway.
Can I self-host everything?
Yes. The gateway is local-first and the control plane ships in the same package:
scopegate cloud serve. Enterprise adds the on-prem packaging,
SAML and SIEM export.
What does a leaked ScopeGate token buy an attacker?
Minutes, at one scope — and a signed audit record of everything it touched. Compare that with a PAT in a transcript: full account access, forever, silently.