Sprites

Swamp models for Fly.io Sprites. Run commands, read and write files, manage services and checkpoints, and control network access.

Installation

Install the extension in your Swamp repository:

swamp extension pull @josh/sprites

Usage

You need a Sprites organization token and an existing Swamp vault. These examples use a vault named sprites-secrets. The vault put command prompts for the token.

The create method below creates a remote Sprite; provider charges apply. To use an existing Sprite, set name to its name and run lookup instead.

swamp vault put sprites-secrets API_TOKEN
swamp model create @josh/sprites/sprite build-sprite \
  --global-arg name=build-worker \
  --global-arg 'token=${{ vault.get("sprites-secrets", "API_TOKEN") }}'
swamp model method run build-sprite create

The token determines the organization. Use separate model instances and vault keys for different organizations.

Check the Python version on the Sprite:

swamp model method run build-sprite exec --input '{"cmd":["python3","--version"]}'
swamp data get build-sprite execStdout

Define an HTTP service using the Sprite's saved name:

swamp model create @josh/sprites/service build-web \
  --global-arg 'sprite=${{ data.latest("build-sprite", "state").attributes.name }}' \
  --global-arg service_name=web \
  --global-arg 'token=${{ vault.get("sprites-secrets", "API_TOKEN") }}'
swamp model method run build-web put --input '{"service":{"cmd":"python3","args":["-m","http.server","8080"],"http_port":8080}}'

Check that the service responds at the Sprite's URL:

swamp model method run build-sprite probeUrl
swamp data get build-sprite probeUrl

probeUrl requires an HTTP 200 response and saves the response size and SHA-256 hash.

The Sprite model saves the remote ID during create or lookup. Later changes check that ID and refuse to act on a replacement Sprite with the same name. When you are done, inspect the saved ID and name before deleting the Sprite:

swamp model get build-sprite --json
swamp model method run build-sprite delete

Models

Inspect any model type's methods, arguments, and output schemas:

swamp model type describe @josh/sprites/sprite --json

File writes, command input (stdin), and HTTP gateway request bodies accept {"kind":"text","text":"hello\n"} or {"kind":"base64","base64":"AP8="}. Supply the contents directly; these methods do not read files from the Swamp host.

Sprite exec saves an exec record and binary execStdout and execStderr files. By default, a nonzero exit fails the method before it saves output. Set failOnNonZero: false to save the exit code and output instead.

Operational limits

Stored data and request limits

Store credentials in vaults and restrict access to the Swamp repository and server. Binary output files may contain application secrets and expire after seven days. A failed method can leave some files or records saved and others missing.

Responses have a default 64 MiB cap. Organization requests default to a 30-second timeout per request; other models default to five minutes. Set timeoutMs and maxResponseBytes in model global arguments to change these limits. After a failed change, check the remote resource before retrying.

Services and runtime changes

A successful Sprite upgrade or restart only means that the API accepted the request. Check the runtime to confirm the change took effect. After a service startup event, check that the application is ready to handle requests.

A stopped service can start again after reboot. Delete its definition to prevent that. To resume an explicitly stopped HTTP service, run service start; an incoming HTTP request alone will not start it.

Commands inside the Sprite

Some methods require programs inside the Sprite:

• Service signal, Sprite listTasks, and task methods require /usr/bin/curl.
• Sprite proxy, gatewayList, and gatewayRequest require /.sprite/bin/python3.
• Starting a TTY session with an explicit terminal size through exec or controlExec also requires /.sprite/bin/python3.

Service, checkpoint, and task models save the Sprite's ID and reject a replacement with the same name on later calls. The organization token stays outside the Sprite.

Checkpoints, tasks, and connectors

Restoring a checkpoint replaces the writable filesystem overlay and leaves /tmp unchanged. Before restoring, inspect the checkpoint model and verify its saved Sprite ID and checkpoint ID.

Checkpoint creation saves the newest checkpoint returned by the API. Avoid concurrent checkpoint creation on the same Sprite: the model could save a checkpoint created by another caller.

Task holds expire after at most one hour. Reading a task or saving its state does not extend the hold. Use refresh to renew it or delete to release it early.

Connector policy updates replace the whole policy. Provisioning a connection alone does not grant Sprite access; an empty policy denies access.

Operations across multiple Sprites

Organization methods that act on multiple Sprites select them by prefix or labels when called. They process one Sprite at a time and continue after recording a failure. They use the current inventory without checking IDs saved by individual Sprite models. Before a bulk restart, service deletion, or policy change, run listSprites and verify the target names and IDs.

Each method saves its summary under the method name. Per-Sprite results use <method>-<sprite-id>, including service methods. Service results also store serviceName. Organization exec saves execStdout-<sprite-id> and execStderr-<sprite-id>. It records nonzero exits rather than failing the whole run.

Each command gets the organization model's timeoutMs, which defaults to 30 seconds. Raise it for slow commands; it limits each command, not the full run.

Inline every public model schema so registry extraction sees complete global arguments, methods, resources, and files. Add a source-level gate that rejects shared schema references in exported contracts.