Agentgate Governed Writefile Demo

agentgate-governed-writefile-demo

This repo is the smallest outsider-readable proof path through AgentGate + MCP Firewall for one governed write_file call. It proves one narrow thing: a governed write_file call can be bonded, forwarded, independently checked on disk, and resolved from observed effect instead of upstream self-report.

It exists as a narrow entry point into the ecosystem: one concrete proof path you can read, run, and inspect quickly. It is not a framework, SDK, starter kit, or general-purpose demo.

Start Here

• Success run: npm run demo:success
• Failure run: npm run demo:failure
• Success file: ./demo/governed-root/success/hello-from-agentgate.txt
• Failure target that should stay missing: ./demo/governed-root/failure/expected-but-missing.txt
• Success audit JSON: ./demo/output/success-firewall-outcome.json
• Failure audit JSON: ./demo/output/failure-firewall-outcome.json

Each command starts AgentGate, the upstream, and MCP Firewall for that run, then shuts them down afterward. You do not start those services by hand.

Why This Repo Exists

This repo exists to be the smallest concrete proof path through AgentGate + MCP Firewall for governed write_file. The success run proves the file really appears on disk and resolves success. The failure run proves an upstream can report success, the target can still stay missing, and the firewall will resolve failed from the missing on-disk effect.

What You Can Verify Quickly

• npm run demo:success produces the expected file and resolves success.
• npm run demo:failure leaves the target path missing and resolves failed.
• The firewall decision comes from the observed file effect on disk, not upstream-reported success alone.
• Each run prints one raw FIREWALL_OUTCOME {...} line and saves parsed audit JSON under ./demo/output/.
• The demo starts what it needs automatically for the run and shuts it down afterward.

Quick Proof After Setup

Watch the real proof video: [assets/governed-writefile-proof-demo.mp4](assets/governed-writefile-proof-demo.mp4)

The video shows the success run, the real file appearing on disk, the success audit JSON, the failure run, the target file staying missing, and the failure audit JSON.

• success file appears
• success audit resolves success / verified
• failure target file stays missing
• failure audit resolves failed / target_missing

Agent-readable UI surface: buttons for humans, manifests for agents, proof for both

A normal UI button tells a human what action is available. An agent-readable manifest tells an agent what action exists, what authority is required, what scope is allowed, and what counts as success.

This repo includes a small example manifest at ./demo/ui-surface-manifest.example.json for the existing notes write_file demo surface. It does not introduce a new protocol or UI framework. The manifest is only a presentation layer for the existing governed write_file proof.

This does not add a new proof surface. It re-expresses the existing governed write_file proof as an agent-readable action manifest.

Why this matters: future agent-native interfaces should not only expose actions; they should expose authority boundaries and verifiable success conditions. In this repo, the actual proof remains MCP Firewall's independent filesystem verification and AgentGate settlement.

What This Is Not

This is not a framework, starter kit, SDK, deployment story, or multi-tool demo. It is one governed write_file proof path, kept narrow on purpose.

This does not prove general MCP security. It does not prove general agent safety. This does not verify arbitrary tools. This does not make upstream servers trustworthy.

Inspect The Proof

• Success target file: ./demo/governed-root/success/hello-from-agentgate.txt
• Failure target path that should remain missing: ./demo/governed-root/failure/expected-but-missing.txt
• Saved parsed audit JSON files: ./demo/output/success-firewall-outcome.json, ./demo/output/failure-firewall-outcome.json
• Raw audit line: FIREWALL_OUTCOME {...} in stdout during each run

Prerequisites

• Node.js 20+
• A local checkout of agentgate
• A local checkout of agentgate-mcp-firewall
• npm install run in all three repos

By default the three repos sit next to each other:

parent-directory/
  agentgate/
  agentgate-mcp-firewall/
  agentgate-governed-writefile-demo/

If your checkouts live elsewhere, set AGENTGATE_REPO_PATH and MCP_FIREWALL_REPO_PATH in .env.

First Run

Initial setup takes longer because you need sibling repo checkouts and npm install in all three repos. The proof run itself is the quick part.

Install dependencies:

cd ../agentgate && npm install
cd ../agentgate-mcp-firewall && npm install
cd ../agentgate-governed-writefile-demo && npm install

If your repo paths or ports differ from the defaults:

cp .env.example .env

Run the proof:

npm run demo:success
npm run demo:failure

Success Demo

npm run demo:success

Expected result:

• one raw FIREWALL_OUTCOME line in stdout
• verification.status: verified
• finalResolution: success
• a real file at ./demo/governed-root/success/hello-from-agentgate.txt
• a saved parsed audit JSON file at ./demo/output/success-firewall-outcome.json

What the run does:

• starts a dedicated local AgentGate instance
• creates or loads demo identities from ./demo/output/identities/
• locks demo bonds
• starts the real filesystem-backed upstream
• starts MCP Firewall with a write_file-only policy and one governed root
• authenticates, performs one governed write_file call, verifies the file on disk, writes the audit JSON, and shuts everything down

Failure Demo

npm run demo:failure

Expected result:

• one raw FIREWALL_OUTCOME line in stdout
• verification.status: failed
• reasonCode: target_missing
• finalResolution: failed
• no file at ./demo/governed-root/failure/expected-but-missing.txt
• a saved parsed audit JSON file at ./demo/output/failure-firewall-outcome.json

What the run does:

• reuses the same local AgentGate DB and identities if they already exist
• locks fresh demo bonds
• starts the compromised upstream fixture in noop mode
• lets the firewall startup canary succeed
• makes one governed write_file call that upstream reports as successful
• observes that the target file never appears on disk, resolves failed, writes the audit JSON, and shuts everything down

Architecture

flowchart LR
  CLI["This demo CLI"] --> AG["AgentGaterepo-local DB"]
  CLI --> FW["MCP Firewall"]
  FW --> UP["Upstream write_file server"]
  UP --> ROOT["./demo/governed-root"]
  FW --> AUDIT["FIREWALL_OUTCOMEstdout + saved JSON"]

Local State

All generated state stays inside ./demo/:

• AgentGate DB: ./demo/output/agentgate.sqlite
• identity files: ./demo/output/identities/
• success audit JSON: ./demo/output/success-firewall-outcome.json
• failure audit JSON: ./demo/output/failure-firewall-outcome.json
• governed file output: ./demo/governed-root/

If You Want Implementation Depth, Then Read MCP Firewall And AgentGate

This repo only wires one proof path together. For the independent write_file effect verification, read agentgate-mcp-firewall next. For the underlying identity, bond, execute, resolve, and authentication logic, read agentgate after that.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: selfradiance
• Source: selfradiance/agentgate-governed-writefile-demo
• License: MIT
• Homepage: https://github.com/selfradiance/agentgate-mcp-firewall

Install and usage instructions live in the source repository linked above.