Manual contents

Sprites

sprites.dev is the first of the two sandbox providers, and the instance default (SANDBOX_PROVIDER=sprites). It is a hosted service. A Managoat instance needs at least one provider credential. With none configured, each conversation fails at provision time.

The Sprites transport reference writes down the exact API surface Managoat consumes. It also says what a compatible replacement behind SPRITES_BASE_URL would have to provide.

Summary

Role Sandbox provider, and the instance default.
Turned on by SPRITES_TOKEN
Env vars SPRITES_TOKEN, SPRITES_BASE_URL, SPRITES_TIMEOUT_MS
Suspend Parks on its own. The sprite scales itself to zero and keeps its disk.
Capabilities advertised :suspend, :network_policy, :attach, :tty and :public_url.
Billed to One platform token, so the operator and not the tenant.

The provider side

Create a sprites.dev organization for this instance, then issue an API token. That token is the whole setup on the provider side.

One organization per instance

The Sprites organization behind SPRITES_TOKEN belongs to one Managoat instance. Do not share it, or the token, with another application or a second Managoat instance. That setup is unsupported, and Managoat does not defend against it (ADR 0005).

Managoat assumes that each sprite at a name it minted is its own:

  • It adopts by name. A create that gets a 409 uses the sprite already there, because that is how a retry after a lost response looks. The provision then writes the tenant's environment and vault values to that sprite's disk.
  • It destroys by name. A conversation's teardown, a provision that discards an interrupted attempt, and the hourly reaper's sweep of finished sandboxes all destroy the sprite at the name the row holds. None of them checks who made it.

A sprite whose name Managoat never minted is never destroyed. The reaper counts such sprites and leaves them alone. So the damage needs a name clash, which in practice means a second instance on the same organization. The token is the larger reason: whatever holds it can list, run commands in and destroy every sprite in the organization, including each tenant's machine. A shared organization also shares its concurrent-sprite limit, which SANDBOX_FLEET_CEILING_SPRITES does not see.

Env vars

Variable Default Effect
SPRITES_TOKEN — The platform token. Managoat does not check it at boot, so the app starts without it and the first conversation fails at provision time.
SPRITES_BASE_URL https://api.sprites.dev Repoints the Sprites API. Whatever you point it at must implement the same transport. E2B is a separate provider, and not a replacement behind this variable.
SPRITES_TIMEOUT_MS 30000 Bounds each HTTP call to the Sprites API. A long command, such as a package install or a clone, sets its own timeout for that call. Boot refuses a value that is not positive.

The cost model

One platform token pays for each Sprites sandbox. Managoat provisions every tenant's Sprites sandboxes with SPRITES_TOKEN, and the bill lands on that token's account, which is yours. Two results follow.

  • Each signup that can start a conversation can spend your money. Close registration, or restrict it, before you put an instance on the internet.
  • Managoat caps live sprites across every account, at 20 by default (SANDBOX_FLEET_CEILING_SPRITES, falling back to SANDBOX_FLEET_CEILING; the $20 Sprites plan's limit); a start past it gets 503 fleet_full. Sandboxes on other providers do not count against it. There is no per-account cap. A sandbox counts from the moment a provision starts, because that is the moment it starts to cost money.

Managoat never shows the token to a tenant, to the admin UI, or to a sandbox. A sprite receives a scoped token that expires, and its only audience is your Managoat instance's own API.

Verify

Start a conversation. Progress streams as stage events. A token that is bad or absent shows up as a failure at the provision stage, in the conversation's log view.

A Sprites outage affects nothing else. Sign-in, dashboards and configuration all still work, and the health endpoints deliberately ask Sprites no question.