Architecture
This page gives you the mental model you need to deploy Sagewai with confidence: how planning and execution split across processes, where credentials live, and which option to set per workflow step. After reading, you'll know which of the four chapters that follow you need.
If you just want to ship your first agent, start with the Quickstart. The architecture here is what's underneath — you don't need to internalise it to begin building.
The split: control plane and worker fleet
Sagewai runs as two cooperating processes:
- The control plane (the admin server, the CLI, autopilot) plans, persists, and dispatches work. It never runs a workflow step itself.
- The worker fleet claims work from the control plane and executes it. Workers don't allocate work to themselves — they pull what's available.
You scale the two independently. Add workers when execution capacity is tight; the control plane keeps planning regardless of how busy the fleet is. A saturated fleet does not stall planning, and a slow planning step does not block other workers.
How a workflow step runs
Three behaviors govern every run. Know them before you deploy — each one maps to a configuration choice.
Each step picks its own execution mode
A workflow run is not pinned to one mode. A single run can:
- Plan in Bare mode on the worker (cheap, no sandbox).
- Run an isolated tool call in a sandboxed step with no identity.
- Hit a customer database in a sandboxed step with customer credentials injected.
- Dispatch a CLI agent like Claude Code in a full sandboxed step.
You don't pay sandbox startup cost for cheap planning steps, and you don't lose isolation for sensitive ones. See Execution modes for the per-step decorator API and a worked example.
The sandbox is the trust boundary when present
When a step runs in any sandboxed mode, the sandbox container is the security boundary in this design. Customer secrets are designed to exist only inside it — injected from your chosen identity backend at sandbox-start time and scrubbed on release.
In the design, the worker host knows the names of secret keys (so it can dispatch the right step) but never holds plaintext values, and the control plane sees neither names nor values. This is the trust boundary the sandbox is built to defend.
Implementation status (v1.0). The pieces that resolve a workload's identity and secret references — the per-workload identity model, the external secret backend (HashiCorp Vault), admin profile/secret controls, enqueue-time cascade resolution, and fail-closed revocation checks at enqueue — ship today. The runtime enforcement described above — live secret injection into the running sandbox, redaction at the RPC boundary, per-key / per-CLI ACL filtering, replay-safe injection, and mid-run (hard-revoke) abort — is designed and partially built, but is not wired into the default worker path in v1.0 (
SealedSecretProviderisNoneby default). Treat those runtime guarantees as experimental and maturing, not as a shipped runtime control. See the v1.0 status for the full breakdown.
Workers advertise what they can run
When a worker starts, it registers with the control plane and advertises capability labels (which sandbox backend it has, which sandbox images it can pull, which models it supports). The control plane uses those labels to match runs to workers. You can run heterogeneous fleets — a Docker pool for general work, a Kubernetes pool for high-throughput, a GPU-equipped pool for inference — and let workflow steps target whichever pool fits.
Two backend choices to make
Sagewai has two pluggable backend types. They're independent — choose each one to fit your existing infrastructure.
| Backend type | What it picks | Examples |
|---|---|---|
| Sandbox backend | Where the sandbox container, pod, or function lives | Docker, Kubernetes, Lambda |
| Identity backend | Where customer credentials come from at sandbox-start time | Built-in (file-based), Vault — with 1Password, AWS Secrets Manager, SOPS, and Bitwarden on the roadmap |
A single deployment can mix freely: Kubernetes sandbox + Vault identity, Docker sandbox + built-in identity, and so on. In v1.0, the identity backend that ships beyond the built-in file-based store is HashiCorp Vault; the other listed backends are designed but not yet implemented. See Sandbox backends for the sandbox decision guide. Identity backend selection is covered in the Sealed Identity guide.
Which chapter you need
Pick based on what you're trying to do.
| If you want to... | Read |
|---|---|
| Trace a workflow run from enqueue to completion | Runtime topology |
| Reason about credential isolation, audit, and what's exposed where | Security tiers |
| Pick the right execution mode for each step in a workflow | Execution modes |
| Decide between Docker, Kubernetes, or a serverless sandbox backend | Sandbox backends |
Next steps
- Quickstart — install the SDK and run a real workflow end-to-end.
- Runtime topology — the full life of a workflow run.
- Security tiers — how Sagewai keeps customer credentials off the worker host.