Core Concepts

This page explains the key terms and ideas behind TameFlare. TameFlare operates in two modes — proxy enforcement (v2, recommended) and SDK advisory (v1). Both can coexist.

Proxy Mode (v2)

Deny-all default

All outbound traffic from your agent is blocked unless a connector is configured for the target domain. No connector = no access. This eliminates data exfiltration, unauthorized API access, and supply chain attacks by default.

Connectors

A connector is a domain-specific parser that converts raw HTTP requests into structured actions. When your agent makes an HTTP call, the proxy matches the target domain to a connector.

| Connector | Domains | Actions | Example | |---|---|---|---| | GitHub | api.github.com | 20+ | github.pr.merge, github.issue.create | | OpenAI | api.openai.com | 24+ | openai.chat.create, openai.file.upload | | Anthropic | api.anthropic.com | 2+ | anthropic.message.create | | Stripe | api.stripe.com | 40+ | stripe.charge.create, stripe.refund.create | | Slack | slack.com, api.slack.com | 35+ | slack.message.send, slack.channel.archive | | Generic HTTP | Any domain | Method-based | http.get, http.post, http.delete |

Add connectors via the CLI:

npx tf connector add github --token ghp_xxx
npx tf connector add openai --token sk-xxx
npx tf connector add stripe --token sk_xxx
npx tf connector add slack --token xoxb-xxx
npx tf connector add generic --domains api.example.com --token xxx

Permissions

Permissions control what each agent can do with each connector. They are per-agent, per-connector, per-action.

# Allow all PR operations
npx tf permissions set --gateway "Bot" --connector github \
    --action "github.pr.*" --decision allow
 
# Require approval for merges
npx tf permissions set --gateway "Bot" --connector github \
    --action "github.pr.merge" --decision require_approval
 
# Block repo deletion
npx tf permissions set --gateway "Bot" --connector github \
    --action "github.repo.delete" --decision deny

Resolution order (most specific wins):

1. Exact match: agent=Bot, connector=github, action=github.pr.merge
2. Wildcard: agent=Bot, connector=github, action=github.pr.*
3. All actions: agent=Bot, connector=github, action=*
4. Global: agent=Bot, connector=*, action=*
5. Default: DENY

Credential vault

API keys are stored in an AES-256-GCM encrypted vault on disk. The proxy injects credentials at request time — the agent never sees real API keys. If the agent is compromised, the attacker cannot extract credentials.

Approval workflow (proxy)

When a permission returns require_approval, the proxy holds the HTTP connection open and waits for a human to respond:

1. Agent makes request → connector parses → permission = require_approval
2. Proxy creates approval request, blocks the goroutine
3. Human approves via CLI (tf approvals approve <id>) or dashboard
4. Approved: credentials injected, request forwarded, response returned
5. Denied or timeout (5 min): 403 returned to agent

Scoped kill switch

The kill switch blocks traffic immediately. It supports scoping:

npx tf kill-switch activate --reason "incident"                 # Block ALL traffic
npx tf kill-switch activate --reason "incident" --scope github  # Block one connector
npx tf kill-switch activate --reason "incident" --scope "Bot"   # Block one agent
npx tf kill-switch deactivate                                   # Resume

Rate limiting

The proxy enforces a 120 requests/minute sliding window per agent. Exceeding the limit returns 429 Too Many Requests with a Retry-After header. Rate limiting is checked before kill switch and permission evaluation.

Platform templates

Quick-start templates for popular agent platforms:

npx tf init --platform openclaw     # OpenAI + Anthropic, deny all else
npx tf init --platform langchain    # LLM APIs + search tools
npx tf init --platform n8n          # OpenAI + Slack + GitHub workflows
npx tf init --platform claude-code  # GitHub + package registries

Observability

The gateway exposes Prometheus-compatible metrics at GET /internal/metrics:

• aaf_traffic_total{gateway, connector, decision} — request counter
• aaf_traffic_latency_ms_sum{gateway, connector} — total latency
• aaf_traffic_latency_ms_max{gateway, connector} — max latency
• aaf_processes_active — registered process count
• aaf_connectors_total — configured connector count
• aaf_gateway_uptime_seconds — uptime

All proxied responses include TameFlare headers:

| Header | Description | |---|---| | X-TameFlare-Decision | allowed, denied, would_deny, rate_limited | | X-TameFlare-Gateway | Gateway name | | X-TameFlare-Connector | Connector type (e.g. github, openai) | | X-TameFlare-Action | Parsed action name (e.g. github.pr.merge) |

SDK Mode (v1)

The following concepts apply to the SDK-based advisory mode, where the agent voluntarily checks with TameFlare before acting.

Action spec

An action spec describes what an agent wants to do. Every request to TameFlare includes one. It has four parts:

{
  "type": "github.pr.merge",
  "resource": {
    "provider": "github",
    "account": "my-org",
    "target": "my-org/api-service",
    "environment": "production"
  },
  "parameters": {
    "pull_number": 42,
    "merge_method": "squash"
  },
  "context": {
    "reason": "Deploy hotfix for payment processing"
  }
}

• type — A dot-separated identifier for the action. You define these yourself. Examples: github.pr.merge, payment.transfer.initiate, infra.server.provision, email.send.
• resource — Where the action targets. provider is the service (github, stripe, aws), target is the specific resource, and environment distinguishes production from development.
• parameters — Action-specific data. For a PR merge, this might be the pull number. For a payment, the amount and currency. Policies can match on any parameter field.
• context — Optional metadata like the reason for the action. Not used in policy evaluation but recorded in the audit trail.

Risk hints

Action specs can include risk hints — boolean flags that help the policy engine assess risk without understanding the action's domain:

{
  "risk_hints": {
    "contains_pii": false,
    "external_recipient": true,
    "production_target": true,
    "financial_impact": true,
    "irreversible": true,
    "estimated_blast_radius": "high"
  }
}

The policy engine uses these to calculate a risk score (0.0 to 1.0). You can write policies that match on individual risk hints or on the computed score.

| Hint | Meaning | |---|---| | contains_pii | Action involves personally identifiable information | | external_recipient | Data leaves your organization | | production_target | Targets a production environment | | financial_impact | Involves money or billing | | irreversible | Cannot be undone | | estimated_blast_radius | low, medium, or high — how many systems are affected |

Decisions

When TameFlare evaluates an action, it returns one of three decisions:

allow

The action is permitted. TameFlare returns a decision token — a signed JWT that the agent uses to execute the action. The token contains:

• The action request ID
• A hash of the action spec (so the token can't be reused for a different action)
• A nonce (so the token can't be replayed)
• An expiration time

requires_approval

The action needs human review. TameFlare sends a notification to Slack with approve/deny buttons. The agent can poll for the result or provide a webhook_url to be notified when a decision is made.

Once approved, the agent receives a decision token and can proceed. If rejected, the action is permanently blocked.

deny

The action is blocked. TameFlare returns the reason (from the matching policy rule) so the agent knows why. No token is issued. The agent cannot execute this action.

Decision tokens

Decision tokens are ES256-signed JWTs issued by the control plane. They serve as cryptographic proof that an action was evaluated and approved.

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJqdGlfYWN0X2FiYzEyMyIsInN1YiI6ImFnZW50XzEiLCJvcmciOiJvcmdfZGVtbyIsImFjdCI6ImFjdF9hYmMxMjMiLCJhc2giOiI3ZjgzYjE2NTdmZjEiLCJjc3QiOm51bGx9...

Key properties:

• Tamper-proof — Signed with ECDSA P-256. The gateway verifies the signature with the control plane before executing.
• Single-use — Each token has a unique nonce (jti). Once verified, the nonce is marked as used in the database. Replay attempts are rejected.
• Action-bound — The token contains a hash of the action spec (ash). If the action spec changes after approval, the token becomes invalid.

Why agents can't bypass TameFlare

A common question: if the agent is autonomous, what stops it from ignoring the policy and acting directly?

The answer is architecture, not trust. TameFlare doesn't inject policies into the agent's prompt or ask the agent to follow rules. Instead, it removes the agent's ability to act without going through TameFlare.

The locked gate model

Think of TameFlare as a security checkpoint between the agent and the tools it wants to use:

• The agent does not have credentials to external tools (GitHub tokens, email API keys, payment APIs). Those credentials live in the TameFlare Gateway.
• The agent only has an TameFlare API key. It can request actions, but it cannot execute them directly.
• The Gateway only executes actions with a valid decision token — a cryptographically signed, single-use proof that the action was evaluated and approved.
• The agent cannot forge a token. Tokens are signed with ES256 (ECDSA P-256) and verified by the control plane before execution.

This means it doesn't matter what the agent "wants" to do. Without a valid token, the Gateway won't act. And the only way to get a token is through the policy engine.

What if the agent misreports risk hints?

If an agent says external_recipient: false when the recipient is actually external, there are three safeguards:

1. Match on parameters directly. Instead of relying on risk hints, write policies that inspect the actual data — e.g., parameters.to not_matches "*@yourcompany.com".
2. Gateway-side validation. The Gateway can inspect the action before executing and reject it if the parameters don't match what was declared.
3. Audit trail. Every action, its parameters, and the decision are logged immutably. If an agent consistently misreports, it shows up in the audit trail and the agent can be revoked.

Enforcement levels

TameFlare supports three enforcement levels, configurable per organization:

| Level | Name | Behavior | |---|---|---| | L0 | Monitor | All actions are allowed. Decisions are logged but not enforced. Useful for initial rollout. | | L1 | Soft enforce | deny decisions are logged as warnings but the action is still allowed. requires_approval works normally. | | L2 | Full enforce | All decisions are enforced. This is the production-ready mode. |

You can change the enforcement level from the dashboard Settings page. It takes effect immediately.

Kill switch

The kill switch is an emergency control that blocks all agent activity organization-wide. When activated:

• All new action requests return deny with reason "Kill switch active"
• Pending approvals are not affected (already in-flight)
• The activation is logged in the audit trail with a reason and timestamp

Activate it from the dashboard overview or via the API:

curl -X POST http://localhost:3000/api/v1/kill-switch \
  -H "Authorization: Bearer <api_key>" \
  -d '{ "active": true, "reason": "Security incident" }'

Agents

An agent is any automated system that calls the TameFlare API. Each agent has:

• A unique API key (prefixed with aaf_test_ or aaf_live_)
• An environment (e.g., development, staging, production)
• A status (active, suspended, revoked)

Policies can scope rules to specific agents or agent environments. For example, you might allow all actions in development but require approval in production.

Roles and permissions (RBAC)

TameFlare enforces role-based access control on dashboard API routes. Each user has one of four roles, organized in a hierarchy:

| Role | Level | Permissions | |---|---|---| | owner | 4 | Everything. Toggle kill switch, manage org settings. | | admin | 3 | Create/revoke agents, create/enable/disable policies. | | member | 2 | Approve/reject actions, view all data. | | viewer | 1 | Read-only access to dashboard, actions, audit log. |

Higher roles inherit all permissions of lower roles. For example, an admin can do everything a member and viewer can do, plus manage agents and policies.

The first user to register becomes the org owner. Subsequent users default to viewer (configurable via DEFAULT_USER_ROLE env var). Promote users from the Users page.

Manage users from the Users page in the dashboard sidebar. Admins can change roles and suspend/activate accounts. Only owners can promote or demote other owners.

If a user attempts an action above their role, TameFlare returns:

{ "error": "Forbidden", "required_role": "admin", "your_role": "viewer" }

Dashboard features

The TameFlare dashboard provides several operational views beyond basic configuration:

Action investigation

Click any action row in the Actions table to open a detail page showing the full lifecycle:

• Action spec — the raw JSON the agent submitted
• Policy evaluation — which policies matched, risk factors, constraints applied
• Decision — outcome, reason, and risk score
• Approval flow — required groups, responses, escalation level, timestamps
• Execution — connector type, duration, response summary, errors
• Audit timeline — every event for this action in chronological order

Analytics

The Overview page shows Recharts-powered charts when you have action data:

• Actions over time — 7-day stacked area chart grouped by outcome (allowed, denied, pending)
• Decision breakdown — pie chart showing the proportion of each outcome
• Top agents — horizontal bar chart of the most active agents
• Top denied types — horizontal bar chart of the most frequently denied action types

Health monitoring

The dashboard header shows real-time system health. The GET /api/health endpoint checks database connectivity and gateway latency. A tooltip on hover shows per-service status with latency in milliseconds.

Audit trail

Every interaction with TameFlare is recorded in the audit trail:

• action.requested — An agent submitted an action for evaluation
• action.allowed / action.denied — The policy engine made a decision
• action.approved / action.rejected — A human responded to an approval request
• action.executed — An approved action was executed via the gateway
• agent.registered / agent.revoked — Agent lifecycle events
• policy.created / policy.updated — Policy changes
• org.kill_switch.activated / org.kill_switch.deactivated — Kill switch events

The audit trail is append-only and immutable. You can search, filter by event type, and export to CSV from the dashboard.