Skip to main content

Execution Tiers

Every agent run needs somewhere to execute. Waxell gives you three options, and you choose per agent — in the same waxell.yaml that defines the agent itself.

The governance model does not change between them. Policies evaluate, spans are written, costs are attributed, and the audit trail is complete at every tier. What changes is isolation, dependencies, and cost.

TierRuns onChoose it whenBilling
SharedPooled workersDefault. Fast, cheap, no cold start.1.0×
Warm slotA Fargate slot claimed for one runYou need per-execution isolation with per-tenant credentials.1.0× (or 0.7× reserved)
Self-containedA container built from your dependenciesYour agent needs libraries or system packages the platform image doesn't carry.1.5×

You do not have to pick up front. Agents start shared, and moving one is a manifest change plus a push.

Shared workers (default)​

Your agent runs on the pooled worker fleet. No cold start, lowest cost, and it is the right answer for most agents most of the time.

Nothing to configure — this is what you get by default.

Warm slots — per-execution isolation​

For regulated workloads (insurance, financial services, healthcare), shared workers can be made safe but are hard to prove safe to a CISO or an auditor. Warm slots move each execution onto its own Fargate task with:

  • STS-tagged credentials scoped to your tenant, minted per run
  • Per-cell KMS encryption context — a wrong-tenant decrypt is denied by KMS itself, not by application code, and the denial is an auditable event
  • No cross-run reuse — a slot handles one execution, then drains

Selecting it​

Your tenant's sensitivity tier decides the floor:

SensitivityRouting
standardShared workers. Default for new tenants.
sensitiveWarm slot minimum — per-execution isolation, per-tenant credentials.
regulatedWarm slot minimum, plus an always-on pool (no scale-to-zero).

You can also raise a single agent without moving the whole tenant:

agents:
  - name: claims_reviewer
    execution:
      tier: warm

Reserved capacity​

If you want slots held for you rather than shared with other tenants, a dedicated cluster reserves them. You pay a monthly fee for the standing capacity, and per-run compute drops to 0.7× — cheaper per run the more capacity you commit to.

Self-contained agents — bring your own dependencies​

Some agents need libraries the platform image doesn't carry: a PDF parser, a legacy document converter, a domain-specific SDK. Rather than asking us to add them to a shared image, declare them and the platform builds your agent its own container.

agents:
  - name: doc_intake
    framework: pydantic_ai
    dependencies:
      apt: [antiword]                                  # system packages
      pip: [pypdf>=4.0, python-docx>=1.1, olefile]     # python packages
      python: "3.11"
    execution:
      mode: isolated
      tier: ephemeral

On wax push, Waxell builds an image layered on the governed runtime base, registers it, and routes that agent's runs to it. The agent gets its dependencies; you get the same policy evaluation, span tree, and cost attribution as every other tier.

Ephemeral by default. Each run launches a fresh task and exits — no warm pool, no idle cost. You pay for the run, plus a 1.5× multiplier that covers the cold start (image pull and boot). We charge a flat premium rather than metering startup, so the number is predictable.

What to expect​

  • Cold start of roughly 30–60 seconds per run, before your agent's own work. Excellent for document pipelines and background processing; noticeable for anything a person is watching. If latency matters, use a warm slot.
  • Rebuilds are automatic when your dependencies change. Unchanged dependencies reuse the existing image.
  • A failed build does not break the agent — it keeps running on the shared tier until the build succeeds.

Choosing between isolated and warm​

Self-contained (isolated)Warm slot
Custom dependenciesYesNo — platform image
Cold start~30–60sNone
Idle costNonePool or reserved
Best forDocument/batch pipelinesInteractive, latency-sensitive

Verifying which tier a run used​

Every run records the tier it executed on. You can see it three ways:

  1. Observe → Runs. Open any run; the execution tier is on the run header.
  2. Traces. The root span carries waxell.execution.tier — tier-0-celery, tier-1-warm-fargate, or tier-3-isolated.
  3. Billing → Usage. Compute lines carry the runtime disposition (event_driven, dedicated_cluster, ephemeral) and the multiplier applied, so the rate on your invoice traces back to where the run executed.

For self-contained agents, Agents → [your agent] → Build shows the build status, the image, and which dependencies were installed.

Failure behaviour​

Worth knowing before you need it:

  • Pool exhausted. Burst traffic can empty the warm pool. Runs fall back to shared workers with a logged warning rather than failing.
  • Credential expiry mid-run. Slot credentials last an hour and refresh transparently. If refresh fails, the run fails cleanly with claim_failed rather than continuing with stale credentials.
  • Encryption-context mismatch. A wrong-tenant decrypt attempt is denied by KMS, the run stops, and it is raised as a security incident — never a silent retry.
  • Task crash (OOM, host failure). The run is marked failed and downstream signals fire. A reconciler sweeps any task that dies before finalising, so a run does not sit unfinished.
  • Build failure on a self-contained agent. The agent continues on the shared tier; the build error is on the agent's Build panel.

Current limits and what's next​

Stated plainly, so you can plan around them:

  • Bulk fan-out. Self-contained agents launch one task per run. A very large backfill dispatched all at once can hit cloud API rate limits. Normal intake volume is unaffected; for large backfills, stagger the load.
  • First isolated run for a new tenant requires a one-time log-group provisioning step, handled during onboarding.
  • Customer-managed keys (BYOK) and per-tenant egress allowlists are on the roadmap; today the platform uses per-cell managed keys and a restricted egress policy.
  • Sub-second cold start (microVM-class) is planned. The tier interface was designed so this arrives as an additional tier, not a migration.