Production multitenancy
This walkthrough shows you what Sagewai enforces when you put it in front of multiple tenants' credentials: a healthcare worker cannot reach finance tasks at the dispatch layer, vendor credentials are injected into a containerised agent at sandbox start and scrubbed on release, and every credential resolution and pool reset lands in the audit log.
Read this page if you are evaluating Sagewai for a production security review, or if you are building the first multi-tenant feature on top of the platform and need to map the controls to what your security team will ask about.
Five guarantees this walkthrough exercises
- The boundary is real, not policy. Tenant credentials live in encrypted Sealed profiles. They are injected into the sandbox env at sandbox start and scrubbed on release. The worker host process never sees them.
- Fleet dispatch enforces scope at the boundary. Workers register with
project_idin their capability labels; the dispatcher matches tasks against those labels. A healthcare worker is unreachable from a finance task. Example 26 ships the dispatch matcher; Example 33 ships the full integration. - Per-CLI workload identity. Each agent run has a verifiable, scoped identity — not a shared
OPENAI_API_KEYlifted from the parent process. - Vault-backed credentials. Sagewai resolves secrets from HashiCorp Vault, AWS Secrets Manager, AgentCore Identity, or the encrypted built-in store at the moment of need, not at process start.
- Every secret-injection event is in the audit log. The admin Audit view records cascade resolutions, identity revocations, and pool resets. Compliance reads the trail directly.
Architecture
Run it
Multi-tenant fleet integration
pip install sagewai
python 33_fleet_sealed_integration.py
The script seeds two tenants (healthcare, finance), registers four workers (two per tenant) with scoped capability labels, enqueues mixed-tenant tasks, and proves the dispatcher refuses cross-tenant claims. The output shows the cross-tenant attempt being rejected at the dispatch boundary.
Sandbox and scoped credentials
python 39_sandbox_scoped_credentials.py
Runs an agent inside a sandbox container with credentials provided by the Sealed Identity layer, calls a third-party API, and confirms the credential bytes are unreachable from the worker host. The _smoke_test_credential_leak block verifies the scrub.
Agent governance (approval flow and audit)
python 16_agent_governance.py
Foundation-level companion: agent approval flow with audit trail before exposing the agent to users.
Where you'd use this
The pattern here — Sealed profiles per tenant, capability-scoped Fleet workers, sandbox credential injection at run time, audit at the boundary — is what you reach for when your first multi-tenant feature ships and the security review starts.
Healthcare SaaS with HIPAA-bound customers
You serve 30 clinics. Each has a separate EHR token. PHI cannot leak across clinic boundaries.
| Concern | How this pattern solves it |
|---|---|
| HIPAA forbids tenant A's PHI being readable from tenant B's process space | Each clinic has a Sealed profile; the healthcare worker pool runs only healthcare tasks; the sandbox env is per-task and scrubbed on release |
| BAA auditor wants to see the credential boundary | The Audit view shows every credential resolution and revocation with timestamps |
| Compliance forbids credentials in source code or env files on the host | Credentials live encrypted at rest in ~/.sagewai/profiles.json; resolved JIT at sandbox start; never in process memory for long |
Multi-tenant fintech with PCI scope
Your AI feature runs across 50 finance customers. Each customer's Stripe and QB tokens must stay scoped to their own AI runs. PCI scope must be minimised.
| Concern | How this pattern solves it |
|---|---|
| PCI scope expands if any non-payment process can read the Stripe key | The Stripe key lives in the customer's Sealed profile, injected only into their sandbox; non-finance workers cannot see it |
| You need to revoke a customer's keys instantly when they cancel | Sealed has a revocation API; future enqueues fail closed and in-flight runs abort or expire |
| Auditor asks "show me the path of this credential from your secret store to the customer's running agent" | The Security tiers page documents the path; the Audit view records each step |
Enterprise SaaS with customer-specific Anthropic keys
Your customer wants to bring their own Anthropic key for cost attribution. You need to honour it without leaking other customers' keys.
| Concern | How this pattern solves it |
|---|---|
Customer A's ANTHROPIC_API_KEY must reach Claude Code in customer A's sandbox, no further | Sealed profile holds it; sandbox start injects it into env; sandbox release scrubs it |
| Customer wants their bill to come from their own account | The Anthropic call uses customer A's key; the bill goes there |
| Cross-customer pollution would be a critical incident | Capability labels enforce per-customer worker pools; the dispatcher refuses cross-customer claims |
Hybrid SaaS with on-prem customers
Some of your customers run agents on their own VPC. Their credentials must never leave their network.
| Concern | How this pattern solves it |
|---|---|
| Customer's vendor keys must never leave their VPC | Sealed profile is on-prem; the worker on-prem reads it; the control plane sees the run, not the credentials |
| Centralised observability without centralising secrets | The control plane receives telemetry events — redacted; secrets stay in the customer profile |
| Onboarding a new on-prem customer must not require code changes | Drop in a new Sealed profile; register a worker with the right capability labels; done |
Internal multi-team platform
Your platform team runs a shared agent platform for engineering, customer success, and sales. Each team has different vendor accounts.
| Concern | How this pattern solves it |
|---|---|
| Engineering's GitHub token must not be reachable from a customer-success agent | Per-team profile; per-team worker pool with capability labels; cross-team claim refused |
| You want one shared cost dashboard with per-team rollups | Observatory tags every span with sagewai.project_id; the Grafana board has per-project rollups |
| Audit committee wants to see who used what when | The Audit view records resolution, identity, run ID, timestamp |
Companion examples
| # | Example | What it adds |
|---|---|---|
| 33 | fleet_sealed_integration | Multi-tenant fleet + Sealed boundary, full integration |
| 39 | sandbox_scoped_credentials | Sandbox + scoped creds, credential-leak smoke test |
| 16 | agent_governance | Approval flow + audit trail |
| 26 | fleet_scoped_dispatch | Capability-based dispatch, project-scoped routing |
| 20 | fleet_workers | Foundation — distributed worker registration |
See also
- Fleet: Fleet — workers, dispatch, and scoped routing.
- Security model: Security overview — the cross-cutting credential, redaction, replay, and audit story.
- Related tutorial: Observability and cost — the audit and per-tenant cost rollup that pairs with this one.
- Related tutorial: Moderation and classification — the same boundary applied to a different workload.
- Prerequisite foundation: Example 20 — fleet_workers.
- Architecture pages: Security tiers, Sandbox backends, Execution modes.