Team Rollout

This guide covers everything an engineering manager needs to plan team adoption of TameFlare: multi-environment deployment, RBAC, user management, multi-tenancy, and configuration migration.

Multi-environment deployment

Recommended topology

Run one TameFlare instance per environment. Each instance has its own control plane, gateway, database, and credentials.

| Environment | Control plane | Gateway | Database | Agents | |---|---|---|---|---| | Development | dev-TameFlare.internal:3000 | dev-TameFlare.internal:9443 | dev.db | Dev agents | | Staging | staging-TameFlare.internal:3000 | staging-TameFlare.internal:9443 | staging.db | Staging agents | | Production | prod-TameFlare.internal:3000 | prod-TameFlare.internal:9443 | prod.db | Production agents |

Why separate instances

  • Isolation — a misconfigured policy in dev cannot affect production
  • Independent kill switches — you can kill-switch staging without touching production
  • Different credentials — each environment uses its own API tokens and connector credentials
  • Independent upgrades — upgrade dev first, verify, then roll to staging and production

Sharing policies across environments

Use config export/import to promote policies between environments:

# Export policies from dev
curl -X GET -H "Cookie: session=$DEV_SESSION" \
  http://dev-TameFlare.internal:3000/api/dashboard/export > policies.json
 
# Import into staging
curl -X POST -H "Cookie: session=$STAGING_SESSION" \
  -H "Content-Type: application/json" \
  -d @policies.json \
  http://staging-TameFlare.internal:3000/api/dashboard/import

Or use the policy-as-code workflow: store policies in git, deploy via CI to each environment. See Writing Policies — Policy-as-Code.

Single-instance alternative

For small teams (<5 agents), a single instance is fine. Use policy scoping to differentiate environments:

metadata:
  name: production-safety
  scope:
    environments: [production]
rules:
  - name: require-approval-in-prod
    conditions:
      all:
        - field: resource.environment
          operator: equals
          value: production
    decision: requires_approval

RBAC (Role-Based Access Control)

Roles and permissions

TameFlare has 4 fixed roles in a strict hierarchy:

| Role | Level | Description | |---|---|---| | Owner | 4 | Full access. Can manage users, toggle kill switch, delete data. | | Admin | 3 | Manage agents, policies, gateways, connectors. Cannot manage users or toggle kill switch. | | Member | 2 | View everything. Can approve/deny pending actions. Cannot create or modify agents, policies, or gateways. | | Viewer | 1 | Read-only access to dashboard. Cannot approve actions or modify anything. |

Permissions matrix

| Action | Owner | Admin | Member | Viewer | |---|---|---|---|---| | View dashboard | Yes | Yes | Yes | Yes | | View audit log | Yes | Yes | Yes | Yes | | View agents | Yes | Yes | Yes | Yes | | View policies | Yes | Yes | Yes | Yes | | Create/edit agents | Yes | Yes | No | No | | Create/edit policies | Yes | Yes | No | No | | Create/edit gateways | Yes | Yes | No | No | | Approve/deny actions | Yes | Yes | Yes | No | | Manage users | Yes | No | No | No | | Toggle kill switch | Yes | No | No | No | | Export/import config | Yes | Yes | No | No | | Change settings | Yes | Yes | No | No |

Custom roles

Custom roles are not supported. The 4 built-in roles cover the most common access patterns.

Workaround: If you need finer-grained access (e.g., "can manage GitHub agents but not Stripe agents"), use separate TameFlare instances per team or domain, each with its own user list.

User registration flow

First user

The first user to register becomes the owner of the organization. This happens automatically — no setup required.

# First registration creates the org and assigns owner role
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@company.com", "password": "...", "name": "Admin"}'

Registration control

After the first user registers, registration is closed by default. Control this with the REGISTRATION_OPEN environment variable:

| REGISTRATION_OPEN | Behavior | |---|---| | Not set (default) | Open for the first user, then closed | | true | Anyone can register | | false | Registration closed. New users must be invited. |

Inviting new users

  1. Set REGISTRATION_OPEN=true temporarily, or
  2. Use the Copy Invite button on the Users page — this copies a registration link

Default role for new users

Set DEFAULT_USER_ROLE to control what role new registrations receive:

| DEFAULT_USER_ROLE | Effect | |---|---| | Not set (default) | New users get member role | | viewer | New users get read-only access | | member | New users can approve actions | | admin | New users can manage agents and policies |

Tip
For most teams, set DEFAULT_USER_ROLE=viewer and manually promote users who need more access.

New member onboarding

What new members see

When a non-admin user logs in for the first time:

  1. Dashboard overview — shows current stats (actions today, active agents, pending approvals)
  2. Audit log — full visibility into all actions and decisions
  3. Agents list — can view all agents and their status
  4. Approvals — members can approve/deny pending actions (viewers cannot)

What new members cannot do

  • Create or modify agents, policies, or gateways
  • Toggle the kill switch
  • Manage other users
  • Export or import configuration

Recommended onboarding steps

  1. Share the dashboard URL with the new team member
  2. Have them register (ensure REGISTRATION_OPEN=true or share the invite link)
  3. Assign the appropriate role — promote from the Users page if needed
  4. Point them to the audit log — this is the best way to understand what TameFlare is doing
  5. If they need to approve actions — ensure they have at least member role

Multi-tenancy

Current status

TameFlare supports one organization per instance. There is no multi-org or multi-tenant support.

| Feature | Status | |---|---| | Multiple orgs in one instance | Not supported | | Org switching | Not supported | | Shared user accounts across orgs | Not supported | | Per-org billing | Not supported |

Workaround

For platform teams managing multiple tenants:

  • Run one TameFlare instance per tenant (or per team)
  • Use Docker Compose or Kubernetes to manage multiple instances
  • Each instance has its own database, credentials, and user list

Planned improvements

  • Multi-org support (single instance, multiple orgs with isolated data)
  • Org-scoped API keys
  • Cross-org policy templates

SSO (Single Sign-On)

Current status

SSO is not currently supported. Authentication uses email/password with session tokens.

Roadmap

SSO via SAML and OIDC is planned for the Team tier. This will support:

  • Google Workspace
  • Okta
  • Azure AD / Entra ID
  • Generic SAML 2.0 and OIDC providers

Track progress on the GitHub issue for SSO support.

Current workaround

  • Use strong, unique passwords for each user
  • Set REGISTRATION_OPEN=false after onboarding to prevent unauthorized registrations
  • Use the DEFAULT_USER_ROLE=viewer to limit new user permissions

Agent-scoped visibility

Current state

All authenticated users can see all agents regardless of their role. There is no per-agent or per-team visibility scoping.

| What users see | Scoped? | |---|---| | All agents | No — everyone sees all agents | | All actions | No — everyone sees all actions | | All audit events | No — everyone sees all events | | All policies | No — everyone sees all policies |

Roadmap

Agent-scoped visibility is planned:

  • Agent groups — assign agents to teams (e.g., "DevOps agents", "Finance agents")
  • Team-scoped views — members only see agents in their group
  • Team-scoped approvals — only team members can approve actions from their agents

Current workaround

For teams that need visibility isolation, run separate TameFlare instances per team. Each instance has its own agent list, policies, and user access.

Configuration migration

What's included in export

curl -X GET -H "Cookie: session=$SESSION" \
  http://localhost:3000/api/dashboard/export > config.json

The export includes:

| Data | Included | Notes | |---|---|---| | Policies (YAML) | Yes | Full policy definitions | | Policy packs | Yes | Installed pack metadata | | Agent definitions | Yes | Name, description, status | | Agent API keys | No | Security — keys are never exported | | Connector configs | Yes | Connector type and settings | | Connector credentials | No | Security — credentials are never exported | | Gateway configs | Yes | Gateway settings and access rules | | User accounts | No | Users are per-instance | | Audit events | No | Use CSV export for audit data | | Settings | Yes | Org name, enforcement level, integrations |

Import into a new instance

curl -X POST -H "Cookie: session=$SESSION" \
  -H "Content-Type: application/json" \
  -d @config.json \
  http://new-instance:3000/api/dashboard/import

After import

You must manually configure:

  1. Agent API keys — create new keys for each agent on the new instance
  2. Connector credentials — re-enter credentials in the credential vault
  3. User accounts — have users register on the new instance
  4. Gateway connection — point the gateway to the new control plane URL

Migration checklist

| Step | Command / Action | |---|---| | 1. Export config | GET /api/dashboard/export | | 2. Export audit (optional) | GET /api/dashboard/audit-export | | 3. Set up new instance | Install TameFlare, run migrations | | 4. Import config | POST /api/dashboard/import | | 5. Create agent keys | Dashboard → Agents → Create Key | | 6. Add credentials | Dashboard → Gateways → Credential Vault | | 7. Register users | Share registration link | | 8. Verify | Run a test action, check audit log |

Next steps