moat

module

v0.2.0 Latest Latest Go to latest Published: Feb 11, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/majorcontext/moat

Links

Open Source Insights

README ¶

Moat

Early Release: This project is in active development. APIs and configuration formats may change.

Run agents in containers with credential injection and full observability.

moat claude ./workspace

This starts Claude Code in an isolated container with your workspace mounted. Credentials are injected at runtime—Claude authenticates normally but never sees your tokens. Every API call, log line, and network request is captured.

For design rationale and principles, see VISION.md, for pretty version of the docs/content/ files see majorcontext.com/moat.

Installation

brew tap majorcontext/moat
brew install moat

Or with Go:

go install github.com/majorcontext/moat/cmd/moat@latest

Requirements: Docker or Apple containers (macOS 15+ with Apple Silicon—auto-detected).

Quick start

1. Grant credentials (one time)

$ moat grant github

Found gh CLI authentication
Use token from gh CLI? [Y/n]: y
Validating token...
Authenticated as: your-username
GitHub credential saved to ~/.moat/credentials/github.enc

2. Run a command with injected credentials

$ moat run --grant github -- curl -s https://api.github.com/user
{
  "login": "your-username",
  "id": 1234567,
  "name": "Your Name"
}

No GITHUB_TOKEN in the command. No secrets in environment variables. The token is injected at the network layer by a TLS-intercepting proxy.

3. Verify the agent never saw your token

$ moat run --grant github -- env | grep -i token
# (nothing)

4. See what happened

$ moat trace --network

[10:23:44.512] GET https://api.github.com/user 200 (89ms)

Why this matters

Traditional approach	With Moat
`GITHUB_TOKEN=xxx` in env	Token never in container
Agent could log/exfiltrate credentials	Token injected at network layer only
No visibility into API calls	Full network trace for auditing
Runs directly on your machine	Isolated container sandbox
Manage Docker, volumes, networks	Just run the agent

Running AI coding agents

Claude Code

moat grant anthropic   # One-time: imports your Claude Code credentials
moat claude            # Interactive mode
moat claude -p "fix the failing tests"  # Non-interactive

Codex

moat grant openai      # One-time: imports your Codex credentials
moat codex             # Interactive mode
moat codex -p "explain this codebase"   # Non-interactive

Both agents run in isolated containers with credentials injected at the network layer. See the Running Claude Code and Running Codex guides for details.

Configuration

Create agent.yaml when you need more control:

name: my-agent

dependencies:
  - node@20
  - git

grants:
  - github
  - anthropic

network:
  policy: strict
  allow:
    - "api.github.com"
    - "api.anthropic.com"

command: ["npm", "test"]

Then run:

moat run ./my-project

See the agent.yaml reference for all options.

Commands

Command	Description
`moat claude [workspace]`	Run Claude Code
`moat codex [workspace]`	Run Codex
`moat run [path] [-- cmd]`	Run an agent
`moat attach <run-id>`	Attach to a running agent
`moat grant <provider>`	Store credentials (github, anthropic, openai, aws, ssh)
`moat grant list`	List stored credentials
`moat revoke <provider>`	Remove credentials
`moat list`	List all runs
`moat snapshot <run-id>`	Create/manage workspace snapshots
`moat logs [run-id]`	View logs
`moat trace [run-id]`	View network requests
`moat audit [run-id]`	Verify audit log integrity
`moat stop [run-id]`	Stop a run
`moat destroy [run-id]`	Remove a run and its artifacts
`moat deps list/info`	Browse available dependencies

Common flags:

moat run --grant github         # Inject credentials
moat run -d ./my-project        # Run detached (background)
moat run -i -- bash             # Interactive shell
moat run -p "prompt"            # Run with prompt (Claude/Codex)

See the CLI reference for all commands and flags.

How it works

Container runtimes: Auto-detects Apple containers (macOS 15+, Apple Silicon) or Docker.

Credential injection: A TLS-intercepting proxy sits between the container and the internet. It inspects requests and injects Authorization headers for granted services. The proxy binds to localhost (Docker) or uses per-run token auth (Apple containers).

SSH agent proxy: For SSH grants, moat runs a filtering SSH agent proxy. Sign requests are forwarded to your SSH agent, but only for granted hosts. Private keys never enter the container.

Image selection: The dependencies field determines the base image—node@20 uses node:20-slim, python@3.11 uses python:3.11-slim. No dependencies defaults to ubuntu:22.04.

Audit logging: Events are hash-chained for tamper evidence. Ed25519 attestations provide cryptographic proof of authenticity.

Setup notes

Trusting the CA certificate (for HTTPS inspection)

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.moat/proxy/ca/ca.crt

# Linux
sudo cp ~/.moat/proxy/ca/ca.crt /usr/local/share/ca-certificates/moat.crt && sudo update-ca-certificates

Optional CLI dependencies

1Password CLI: brew install 1password-cli (for op:// secrets)
AWS CLI: brew install awscli (for ssm:// secrets)

Documentation

Getting started — Installation, quick start, tool comparison
Concepts — Sandboxing, credentials, audit logs, networking, dependencies
Guides — Claude Code, Codex, SSH, secrets, multi-agent, snapshots
Reference — CLI, agent.yaml, environment variables

Contributing

See CONTRIBUTING.md for development setup, testing, and architecture details.

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
moat command
moat/cli cmd/moat/cli/grant.go	cmd/moat/cli/grant.go
internal
audit Package audit provides tamper-proof logging with cryptographic verification.	Package audit provides tamper-proof logging with cryptographic verification.
buildkit
cli Package cli provides shared types and utilities for CLI commands.	Package cli provides shared types and utilities for CLI commands.
config Package config handles agent.yaml manifest parsing.	Package config handles agent.yaml manifest parsing.
container Package container provides an abstraction over container runtimes.	Package container provides an abstraction over container runtimes.
container/output Package output provides consistent user-facing messages for container operations.	Package output provides consistent user-facing messages for container operations.
credential Package credential provides credential management for Moat.	Package credential provides credential management for Moat.
credential/keyring Package keyring provides secure storage for the credential encryption key.	Package keyring provides secure storage for the credential encryption key.
deps internal/deps/builder.go	internal/deps/builder.go
deps/versions Package versions provides version resolution for runtime dependencies.	Package versions provides version resolution for runtime dependencies.
doctor Package doctor provides diagnostic output for debugging Moat.	Package doctor provides diagnostic output for debugging Moat.
id Package id provides unique identifier generation for moat resources.	Package id provides unique identifier generation for moat resources.
image Package image handles container image selection.	Package image handles container image selection.
log
name Package name generates random agent names.	Package name generates random agent names.
provider Package provider defines interfaces for credential and agent providers.	Package provider defines interfaces for credential and agent providers.
provider/util Package util provides shared utilities for provider implementations.	Package util provides shared utilities for provider implementations.
providers Package providers provides explicit registration of all credential and agent providers.	Package providers provides explicit registration of all credential and agent providers.
providers/aws Package aws implements the AWS credential provider for moat.	Package aws implements the AWS credential provider for moat.
providers/claude Package claude implements the Claude Code credential and agent provider.	Package claude implements the Claude Code credential and agent provider.
providers/codex Package codex implements the Codex credential and agent provider.	Package codex implements the Codex credential and agent provider.
providers/gemini Package gemini provides Google Gemini CLI integration for Moat.	Package gemini provides Google Gemini CLI integration for Moat.
providers/github Package github implements the GitHub credential provider.	Package github implements the GitHub credential provider.
providers/npm
proxy Package proxy provides a TLS-intercepting HTTP proxy for credential injection.	Package proxy provides a TLS-intercepting HTTP proxy for credential injection.
routing Package routing provides hostname-based reverse proxy routing.	Package routing provides hostname-based reverse proxy routing.
run
secrets Package secrets provides pluggable secret resolution from external backends.	Package secrets provides pluggable secret resolution from external backends.
snapshot Package snapshot provides types and interfaces for workspace snapshots.	Package snapshot provides types and interfaces for workspace snapshots.
sshagent Package sshagent implements a filtering SSH agent proxy.	Package sshagent implements a filtering SSH agent proxy.
storage Package storage provides run storage infrastructure for Moat.	Package storage provides run storage infrastructure for Moat.
system
term Package term provides terminal utilities for interactive sessions.	Package term provides terminal utilities for interactive sessions.
trace Package trace provides execution tracing for containerized processes.	Package trace provides execution tracing for containerized processes.
tui internal/tui/statusbar.go	internal/tui/statusbar.go
ui
worktree Package worktree provides git worktree management for moat runs.	Package worktree provides git worktree management for moat runs.