Agent Tools

My tools for working with AI coding agents: sandboxed execution and controlled external access that keeps upstream credentials on the host. Use individual tools or combine them to fit your workflow.

Tools at a Glance

Tool	Purpose	Runs on
Sandbox Manager (sb)	Manage a Lima VM for agent execution	macOS host
MCP Broker	Apply rules and per-call human approval to MCP tools	Host
MCP Gateway	Give agents scoped access to MCP tools	Host
HTTP Broker	Inject credentials into proxied HTTP/HTTPS requests	Host
Local Git MCP	Perform authenticated Git remote operations over MCP	Host subprocess
Local Gomod Proxy	Fetch private Go dependencies for sandboxed clients	Host

Choosing and Combining Tools

These tools are independent, not a mandatory stack:

• Execution: Sandbox Manager provides an optional Lima VM. The access tools do not require the Pi coding agent, and MCP Gateway does not depend on Lima or a particular agent harness.
• MCP access: Choose MCP Broker or MCP Gateway based on the permission model below. Both connect agents to backend MCP servers.
• Git access: Run Local Git MCP as a stdio backend behind either Broker or Gateway, using that service's access controls and invocation history.
• Non-MCP traffic: HTTP Broker handles ordinary HTTP/HTTPS clients; Local Gomod Proxy handles Go module downloads. They complement MCP access rather than routing through it.

MCP Broker or MCP Gateway?

Both keep upstream credentials outside the sandbox, but approval means different things:

	MCP Broker	MCP Gateway
Access model	Rules allow, deny, or require human approval for a tool call	Per-agent grants scope access to servers, tools, or matching arguments
Human approval	Resolves an individual waiting call	Grants permissions; does not approve a queued tool call
Agent workflow	Call tools under operator-defined rules	Discover tools, inspect access, and request additional permissions

They have separate configuration and state; Gateway does not migrate Broker settings.

Tool Summaries

Sandbox Manager (sb)

sb manages a lightweight Lima VM on macOS for running agents in a separate development environment.

• Creates an Ubuntu VM with a host-matching UID and writable workspace mounts.
• Applies repeatable provisioning scripts to install and configure the tools your agents need.
• Provides commands to enter, provision, and destroy the sandbox.

The sandbox protects host integrity and credential custody; it is not a data-loss-prevention boundary. Guest network egress is allowed by default, so do not put secrets or sensitive private data in the VM unless you accept that an agent can transmit them.

See the Sandbox Manager README for setup and usage.

MCP Broker

mcp-broker proxies MCP servers through a single host-side endpoint when you want rule-based access with optional per-call human approval.

• Applies allow, deny, or require-approval rules to tool calls.
• Collects human decisions through a web dashboard, with optional Telegram approval.
• Records tool calls in a searchable SQLite audit log and displays discovered tools and rules.

See the MCP Broker README for setup and usage.

MCP Gateway

mcp-gateway provides a local MCP endpoint when you want separate agent identities and scoped permissions that agents can request through MCP.

• Denies access unless granted, with scopes for servers, tools, or matching arguments and optional expiry.
• Manages upstream credentials and OAuth; agents receive a separate Gateway credential, not upstream service secrets.
• Provides a web application and CLI for administration, with redacted invocation history and control-plane audit records.

See the MCP Gateway README for setup and usage.

HTTP Broker

http-broker is a host-side HTTP/HTTPS forward proxy for clients such as curl and SDKs that need authenticated access outside MCP.

• Applies rules to intercept, tunnel, or deny traffic, injecting host-held credentials into intercepted requests.
• Binds each credential to allowed destination hosts, independently of request rules.
• Records proxy traffic in an audit log with a read-only web dashboard.

Enforcement is cooperative: clients must honour HTTP_PROXY/HTTPS_PROXY. Clients can bypass the proxy, so it is not a containment boundary. See the security model for details.

See the HTTP Broker README for setup and usage.

Local Git MCP

local-git-mcp exposes authenticated Git remote operations to agents through a host-side stdio MCP server.

• Supports pushing, pulling, fetching, cloning GitHub repositories, and inspecting remotes and remote refs.
• Uses the host's existing Git, SSH keys, and credential helpers without copying those credentials into the sandbox.
• Runs as a subprocess behind MCP Broker or MCP Gateway, with no separate config, persistent state, or network listener.

See the Local Git MCP README for setup and usage.

Local Gomod Proxy

local-gomod-proxy serves Go modules from the host so sandboxed clients can resolve private dependencies without the host's Git credentials.

• Forwards public module requests to proxy.golang.org by default.
• Fetches private modules matched by GOPRIVATE through the host's Go toolchain and Git credentials.
• Serves sandbox clients over TLS with separate proxy authentication, configured through GOPROXY.

Keep the proxy local and share its client credentials only with trusted sandboxes; do not expose it to the public internet.

See the Local Gomod Proxy README for setup and usage.

Installation

Requirements:

• Go 1.25.13 or later and GNU Make
• macOS and Lima for Sandbox Manager (brew bundle installs Lima from the repository root)
• A supported operating-system keyring for MCP Gateway server credentials

From the repository root, run the install command for the tools you need:

make -C sandbox-manager install
make -C mcp-broker install
make -C mcp-gateway install
make -C http-broker install
make -C local-git-mcp install
make -C local-gomod-proxy install

Or install all tools:

make install

Each tool's README covers its configuration and runtime requirements.

Development

In addition to the installation requirements, development uses Node.js/npm for hooks and formatting, and Python 3 for CI selection and gate tests.

npm install  # install development dependencies and Git hooks
make build  # build all Go tools
make check  # check CI selection, formatting, lint, and ordinary tool correctness

On macOS, make setup combines Homebrew dependencies, development dependencies, and installation of all tools.

GitHub Actions checks affected tools on pull requests and all tools on main, manual runs, and a weekly schedule. See the contributor guidance for test ownership and focused checks, and CI guidance for selection, caching, and required checks.

Deprecated Tools

Unmaintained tools and their final versions

These tools are no longer maintained, but their final versions remain available in the repository history.

Tool	Last commit	Reason
worktree-manager	20b0fb924c	Deprecated in favor of Herdr for workspace and worktree management.
worktree-sync	20b0fb924c	Deprecated in favor of Herdr for workspace and worktree management.
pi-session-analyzer	7f52e38085	Built as an experiment and not carried forward.
pi-dispatcher	d1f7ae3da4	Replaced by the scheduled-tasks Pi extension.
pi-orchestrator	3e799fa7c1	Replaced by the scheduled-tasks Pi extension.
telegram-mcp	3d9dc4338b	Retired; the standalone notification server is no longer maintained.
agent-mailbox	4378f6ef71	Replaced by telegram-mcp, which is now also retired.
local-gh-mcp	1f7cfd126f	Deprecated in favor of the official GitHub MCP server.
broker-cli	0251368f3b	Replaced by the mcp-broker Pi extension.
hindsight	164ffccbc0	An experimental memory solution that was ultimately abandoned.

Related

• agent-config — My configuration for working with AI coding agents

License

MIT