Get Started

Let’s get Maybe Don’t running. Pick your installation method, then follow the same first-run steps regardless of how you installed.

Install

Recommended for MCP server mode. Docker keeps the gateway isolated and is the easiest way to get started if you’re proxying MCP tool calls.

docker pull ghcr.io/maybedont/maybe-dont:v1.1.0

Recommended for CLI gateway and local development. Homebrew installs maybe-dont as a native binary — ideal if you’re validating CLI commands or want the fastest startup.

brew install maybedont/tap/maybe-dont

All platforms

Multi-platform packages from the releases repository. Supports macOS, Linux, and Windows.

After downloading, extract the archive and place the maybe-dont binary somewhere on your PATH.

First Run

On first startup, Maybe Don’t writes the default configuration and policy files to your config directory. You don’t need to create anything from scratch — just modify the defaults.

mkdir -p ./config

# Run once to bootstrap defaults
docker run --rm \
  -v $(pwd)/config:/config \
  ghcr.io/maybedont/maybe-dont:v1.1.0 start --config-dir /config

Stop the container after it starts up — the defaults are now written to ./config/.

# Run once to bootstrap defaults
maybe-dont start

Stop the process after it starts up. The defaults are now written to your config directory — ~/.config/maybe-dont by default, or $XDG_CONFIG_HOME/maybe-dont if set. Run maybe-dont config info to see the resolved paths.

Read-only environments? If your config directory isn’t writable (e.g., mounted read-only in a container), use maybe-dont defaults export -o <dir> to extract the defaults to a writable location.

Configure

Open maybe-dont.yaml and make two changes:

1. Add a downstream MCP server (if you’re proxying MCP tool calls):

downstream_mcp_servers:
  github:
    type: http
    url: "https://api.githubcopilot.com/mcp/"
    auth:
      pass_through:
        enabled: true
        headers:
          - source_header: "X-GitHub-Token"
            target_header: "Authorization"
            format: "Bearer {value}"

2. Set your AI provider for policy validation:

validation:
  ai:
    provider: openai
    endpoint: "https://api.openai.com/v1/chat/completions"
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"

Don’t have an AI API key yet? You can skip this step and run with just CEL policies. Set ai.enabled: false under request_validation in your config. You’ll still get audit logging and deterministic policy evaluation.

Start

export OPENAI_API_KEY="your-api-key-here"

docker run \
  -e OPENAI_API_KEY \
  -v $(pwd)/config:/config \
  -p 8080:8080 \
  ghcr.io/maybedont/maybe-dont:v1.1.0 start --config-dir /config

export OPENAI_API_KEY="your-api-key-here"

maybe-dont start

Everything starts in audit_only mode by default — observe before enforcing. This means policies evaluate and log decisions, but nothing gets blocked until you’re ready.

Verify

Check the audit log for entries. If you see log output, the gateway is intercepting and evaluating operations.

You can also test with curl:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Token: your-github-token" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

What’s Next?

Two paths depending on what you’re here for:

“I want to proxy MCP tool calls” — Set up your downstream servers and connect your AI agent
“I want to validate CLI commands” — Set up the CLI gateway

Then explore:

Policies — Define what’s allowed and what isn’t
Audit Log — See what your agents are doing
Configuration — All configuration options
Testing — Test your policies before deploying

MCP