Container exec mode
By default spritzer runs a scripted interpreter behind exec (see
Fidelity). With SPRITZER_EXEC=container each sprite is a real
container instead, so a provisioning script, node, or a long-lived service can
run on it, and its URL reaches what it serves. The README lists the
environment variables.
How a sprite is built
flowchart LR
client[Sprites client] -->|REST, exec WebSocket, sprite URL| spritzer
spritzer -->|create / delete / exec| runtime["Docker or Kubernetes"]
runtime --> sprite
subgraph sprite [sprite container]
agent[spritzer agent] --> services[services]
agent --- sock["/.sprite/api.sock"]
envcli[sprite-env] --> sock
end
- The sprite image (
SPRITZER_SPRITE_IMAGE) is unmodified. Its entrypoint is replaced by/.sprite/bin/spritzer agent. /.sprite/binholds spritzer's Linux binary and asprite-envlink to it. On Kubernetes an init container fromSPRITZER_AGENT_IMAGEcopies it into anemptyDir; on Docker it is copied once into a named volume (spritzer-agent-<hash>) that every sprite mounts read-only.- The agent supervises services and serves wisp's guest API on
/.sprite/api.sock. It is not PID 1: Docker's init or the pod's pause container (withshareProcessNamespace) reaps orphans. - The container's hostname is the sprite's name.
How spritzer reaches into a sprite
Every interaction is an exec of the agent binary, so no port inside a sprite has
to be routable from spritzer. That matters on Docker Desktop, where container
IPs are not reachable from the host, and it keeps the Kubernetes permissions to
pods and pods/exec.
| API | What spritzer execs |
|---|---|
exec |
spritzer x-exec --id <id> [--dir] [--env]... -- argv, which sets the directory and environment, records its pid under the exec id, and becomes the command. If the client disconnects first, spritzer x-kill <id> stops the process group. |
| services | spritzer x-relay unix:/.sprite/api.sock, used as the connection of an HTTP transport; requests go to the agent verbatim. |
| sprite URL | spritzer x-relay url, which connects to the http_port service's port, else 8080, retrying for a few seconds while a service binds. |
| filesystem | spritzer x-fs <op> <path>, where op is read, write, list or delete. A write takes the query's mode as --mode <octal>, defaulting to 0644. |
| create | spritzer x-ping until the agent answers. |
On Kubernetes exec uses the v5.channel.k8s.io WebSocket protocol, which can
close stdin on its own; on Docker it uses the hijacked exec stream.
Services
The shapes are wisp's, so sprite-env scripts written for wisp or Sprites run
unchanged:
sprite-env services create door --cmd "$HOME/box/run-door.sh" --needs hud --http-port 8080 --duration 2s --no-stream
sprite-env services list
sprite-env services restart chud
From outside, /v1/sprites/{id}/services/... is forwarded to the same agent.
PUT creates or replaces a service and starts it, streaming NDJSON events
(started, stdout, stderr, exit, complete) for ?duration. needs
start first; a crash restarts with backoff up to 30s; every defined service
starts when the agent starts. Only one service may have an http_port.
Limits
- No checkpoints or restore:
501(#23). - No TTY exec, no detach and reattach; the exec session list is always empty.
- Logs are not rotated.
- The default image runs as root and has no
spriteuser orsudo. A box that expects them needs an image that provides them. - Network policy is stored and returned but not enforced.