Quick Start

Get tf running in under 10 minutes. The proxy model requires zero code changes to your agent.

Prerequisites

| Requirement | Version | Check | |---|---|---| | Node.js | ≥ 18 | node --version | | pnpm | ≥ 8 | pnpm --version | | Go | ≥ 1.22 | go version |

OS support: Linux, macOS, Windows. On Windows, the Go gateway compiles natively (no WSL required). All CLI commands work in PowerShell and CMD.

Option A: Dashboard Setup (recommended)

1. Install and start

git clone https://github.com/tameflare/tameflare.git
cd agent-firewall
pnpm install
pnpm dev          # Starts the Next.js control plane on port 3000

2. Create your account

Open http://localhost:3000/register. The first user becomes org owner.

3. Create a gateway

Go to Gateways → Create gateway. The wizard walks you through 4 steps:

1. Configure gateway — name, host (127.0.0.1), port (9443), enforcement level (monitor / soft enforce / full enforce)
2. Assign an agent — pick an existing agent or create a new one inline
3. Select connectors — enable GitHub, OpenAI, Stripe, Slack, or Generic HTTP and paste API keys
4. Set access rules — per connector: Allow all, Read only, Require approval, or Custom patterns

The wizard creates the gateway, agent, connectors, and permissions in one step.

4. Run your agent

Copy the run command from the wizard:

npx tf run --name "DevOps Bot" python my_agent.py

All outbound HTTP traffic from my_agent.py is now routed through the TameFlare proxy. The agent never sees real API keys.

5. Verify it works

# Check gateway + control plane health
curl http://localhost:3000/api/health
# Expected: {"status":"ok","services":{"database":"ok","gateway":"ok"}}
 
# Check gateway status via CLI
npx tf status

6. Monitor and approve

Open the Traffic page for live requests, or use the CLI:

npx tf status                  # Gateway + agent stats
npx tf logs                    # Live traffic log
npx tf approvals list          # Pending approvals
npx tf approvals approve <id>  # Approve a held request

Option B: CLI Setup (for automation / CI)

git clone https://github.com/tameflare/tameflare.git
cd agent-firewall
pnpm install
npx tf init
npx tf connector add github --token-env GITHUB_TOKEN   # reads from env var (avoids shell history)
npx tf permissions set --gateway "Bot" --connector github \
    --action "github.pr.*" --decision allow
npx tf run --name "Bot" python my_agent.py

Option C: Docker Compose

git clone https://github.com/tameflare/tameflare.git
cd agent-firewall
cp apps/web/.env.example apps/web/.env.local
docker compose up -d

This starts two services:

• web — Next.js control plane (dashboard + API) on port 3000
• gateway — Go proxy on port 9443

Dashboard at http://localhost:3000/dashboard.

How the proxy works

tf run --name "Bot" python agent.py
  │
  │  Sets HTTP_PROXY / HTTPS_PROXY → all traffic routed through gateway
  ▼
┌──────────────────────────────────────────────────┐
│  TameFlare Gateway (Go binary, localhost:9443)          │
│                                                  │
│  domain → connector → parse action → check perm  │
│                                                  │
│  allowed:          inject creds → forward        │
│  denied:           return 403                    │
│  require_approval: hold connection → wait        │
└──────────────────────────────────────────────────┘
  │
  ▼
External APIs (GitHub, Stripe, AWS...)

Key concepts:

• Deny-all default — no connector configured = no access. The agent cannot reach any domain you haven't explicitly set up.
• Connectors parse raw HTTP requests into structured actions (e.g., github.pr.merge).
• Permissions are per-agent, per-connector, per-action. Most specific rule wins.
• Credential vault stores API keys encrypted (AES-256-GCM). Injected by the proxy at request time.
• Kill switch blocks all traffic instantly. Supports scoping to a connector or agent.

Config files

After tf init, a .TameFlare/ directory is created:

| File | Purpose | Safe to commit? | |---|---|---| | .TameFlare/config.yaml | Gateway configuration | Yes | | .TameFlare/gateway.db | Gateway SQLite database (traffic logs, permissions) | No (generated) | | .TameFlare/credentials.enc | Encrypted credential vault | No (secrets) | | .TameFlare/ca.crt | TLS CA certificate (agents trust this) | Yes | | .TameFlare/ca.key | TLS CA private key | No (keep secret) |

Environment variables

Required for first run

None. TameFlare works out of the box with sensible defaults for local development:

• SQLite database at apps/web/local.db (auto-created)
• ES256 signing keys auto-generated (ephemeral — see below)
• No dashboard password required (first user registers via email/password)

Recommended for production

| Variable | Purpose | Generate with | |---|---|---| | SETTINGS_ENCRYPTION_KEY | Encrypts secrets at rest (AES-256-GCM) | openssl rand -hex 32 | | SIGNING_KEY_PRIVATE | Persistent ES256 signing key (PEM, base64) | See Environment Variables | | SIGNING_KEY_PUBLIC | Corresponding public key | See Environment Variables | | MAINTENANCE_SECRET | Protects cleanup endpoint | Any random string |

Optional

| Variable | Purpose | |---|---| | DASHBOARD_PASSWORD | Shared password for dashboard (legacy — prefer email/password auth) | | REGISTRATION_OPEN | Set to true to allow new user signups (closed after first user) | | SLACK_BOT_TOKEN | Slack bot token for approval notifications | | NEXT_PUBLIC_DOCS_URL | Docs site URL (for cross-app links) |

See the Environment Variables page for the full reference.

Troubleshooting

Port conflicts

If port 3000 or 9443 is already in use:

# Change the Next.js port:
PORT=3001 pnpm dev
 
# Change the gateway port (in .TameFlare/config.yaml):
port: 9444

System requirements

TameFlare is lightweight. Approximate resource usage:

• Gateway (Go): ~20-50 MB RAM
• Control plane (Next.js): ~200-400 MB RAM
• Disk: ~100 MB for dependencies + database grows with traffic

Common issues

"Invalid API key" — Make sure the API key prefix (first 8 chars) matches what's in the database. Re-run node scripts/seed.js if needed.

Dashboard shows no data — Create a gateway and run an agent, or use the demo sandbox on the Overview page.

Slack messages not sending — Check that SLACK_BOT_TOKEN is set in .env.local and the bot is invited to the channel.

Gateway not executing — Make sure your connector API keys are configured in the gateway wizard.