Concepts & Terminology

This page explains the key terms and ideas behind TameFlare. TameFlare is a transparent proxy firewall - it intercepts all outbound HTTP traffic from your AI agent, enforces permissions, and injects credentials. Zero code changes required.

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`
MCP	Configurable	JSON-RPC	`mcp.tools.call`, `mcp.tools.list`
Webhook	Any domain	HTTP methods	`webhook.post`, `webhook.get`
Generic HTTP	Any domain	Method-based	`http.get`, `http.post`, `http.delete`

Connectors are configured in the dashboard gateway wizard when you create or edit a gateway. You select which connectors to enable and paste API keys into the encrypted vault.

See Connectors for full details on each connector.

Permissions

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

Permissions are set in the dashboard gateway wizard during the access rules step. You can choose from preset rules or define custom patterns:

Rule	Effect
Allow all	All actions for this connector are allowed
Read only	Only read operations (GET requests) are allowed
Require approval	All actions require human approval before forwarding
Custom	Define per-action rules (e.g., allow `github.pr.*` but deny `github.repo.delete`)

Resolution order (most specific wins):

Exact match: connector=github, action=github.pr.merge
Wildcard: connector=github, action=github.pr.*
All actions: connector=github, action=*
Default: DENY

Credential vault

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

You add credentials in the dashboard gateway wizard when configuring connectors. Remove API keys from your agent's environment variables - the gateway handles credential injection automatically.

Approval workflow

When a permission is set to Require approval (require_approval), the proxy holds the HTTP connection open and waits for a human to respond:

Agent makes request → connector parses → permission = Require approval
Proxy creates approval request, blocks the connection
Human approves via the dashboard
Approved: credentials injected, request forwarded, response returned
Denied or timeout (5 min): 403 returned to agent

Approval notifications can also be sent to Slack if configured in Settings.

Decisions

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

Decision	Effect	What the agent sees
allow	Request forwarded with injected credentials	Normal HTTP response from upstream API
Require approval (`require_approval`)	Connection held until human responds	Normal response (if approved) or 403 (if denied/timeout)
deny	Request blocked immediately	403 Forbidden with reason

Warning

TameFlare uses a deny-wins model. If multiple rules match an action and any one returns deny, the action is denied - even if other rules say allow.

Kill switch

The kill switch blocks traffic immediately. It can be scoped:

Scope	Effect
All	Blocks all traffic across all connectors
Connector (e.g., `github`)	Blocks all traffic to a specific connector
Gateway (e.g., `dev-bot`)	Blocks all traffic from a specific gateway

Activate via the dashboard: Settings → Kill Switch → Activate

See Kill Switch for full recovery procedures.

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.

Enforcement levels

TameFlare supports three enforcement levels, configurable per gateway in the dashboard:

Level	Name	Behavior
L0	Monitor	All actions are forwarded. Decisions are logged but not enforced. Useful for initial rollout.
L1	Soft enforce	`deny` decisions are logged as `would_deny` but the action is still forwarded. `require_approval` works normally.
L2	Full enforce	All decisions are enforced. Denied requests return 403. This is the production-ready mode.

Tip

Start with monitor mode to observe real agent behavior before enforcing. This prevents false positives that block legitimate work.

How TameFlare enforces access control

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 agent does not have credentials to external APIs. Those credentials live in the gateway's encrypted vault.
The agent's traffic is physically routed through the proxy via HTTP_PROXY/HTTPS_PROXY environment variables set by tf run.
The gateway enforces a deny-all default. No connector = no access.
Strong enforcement for proxy-aware HTTP clients. Most HTTP libraries (Python requests, Node.js axios/fetch, Go net/http) respect proxy env vars automatically. For full bypass-resistance, pair with OS-level egress controls (firewall rules, network namespaces) to block direct outbound traffic. See Security > Proxy bypass analysis for an honest limitations table.

Response headers

All proxied responses include TameFlare headers for observability:

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`)

Roles and permissions (RBAC)

TameFlare enforces role-based access control on the dashboard. Each user has one of four roles:

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

Higher roles inherit all permissions of lower roles. The first user to register becomes the org owner. Subsequent users default to viewer. Promote users from the Users page in the dashboard.

Dashboard features

Traffic log

Every proxied request is logged with agent, domain, action type, decision, latency, and status code. Searchable, filterable, and exportable from the dashboard.

Analytics

The Overview page shows charts when you have traffic data:

Actions over time - 7-day stacked area chart grouped by outcome
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 gateway health. Gateways that have checked in within the last 2 minutes show as online with a "Last seen: Xs ago" indicator.

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
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.