Skip to content
Sprites

Type Definitions

This page documents the data types used throughout the Sprites API.

Types

Section titled “Types”

CheckpointInfo

Section titled “CheckpointInfo”
id:string

Checkpoint identifier (e.g., `v7`)

create_time:string (ISO 8601)

When the checkpoint was created

source_id:optionalstring

Parent checkpoint ID

comment:optionalstring

User-provided description

health:optionalstring

Health status (empty = healthy, "mount_failed" = unhealthy)

Example:

{
  "comment": "Before database migration",
  "create_time": "2026-01-05T10:30:00Z",
  "id": "v7"
}

ChmodRequest

Section titled “ChmodRequest”
path:string
workingDir:string
mode:string
recursive:boolean
asRoot:boolean

ChmodResponse

Section titled “ChmodResponse”
affected:ChmodResult[]
count:number

ChmodResult

Section titled “ChmodResult”
path:string
mode:string

ChownRequest

Section titled “ChownRequest”
path:string
workingDir:string
uid:any
gid:any
recursive:boolean
asRoot:boolean

ChownResponse

Section titled “ChownResponse”
affected:ChownResult[]
count:number

ChownResult

Section titled “ChownResult”
path:string
uid:number
gid:number

CopyRequest

Section titled “CopyRequest”
source:string
dest:string
workingDir:string
recursive:boolean
preserveAttrs:boolean
asRoot:boolean

CopyResponse

Section titled “CopyResponse”
copied:CopyResult[]
count:number
totalBytes:number

CopyResult

Section titled “CopyResult”
source:string
dest:string

CreateCheckpointRequest

Section titled “CreateCheckpointRequest”
comment:optionalstring

Example:

{
  "comment": "Before deploying v2.0"
}

DeleteRequest

Section titled “DeleteRequest”
path:string
workingDir:string
recursive:boolean
asRoot:boolean

DeleteResponse

Section titled “DeleteResponse”
deleted:string[]
count:number

Entry

Section titled “Entry”
name:string
path:string
type:string
size:number
mode:string
modTime:string (ISO 8601)
isDir:boolean

ExecKillCompleteEvent

Section titled “ExecKillCompleteEvent”
type:string

(const: `"complete"`)

exit_code:number

Process exit code

Example:

{
  "exit_code": 0,
  "type": "complete"
}

ExecKillErrorEvent

Section titled “ExecKillErrorEvent”
type:string

(const: `"error"`)

message:string

Error message

Example:

{
  "message": "Warning: process may not have terminated",
  "type": "error"
}

ExecKillExitedEvent

Section titled “ExecKillExitedEvent”
type:string

(const: `"exited"`)

message:string

Status message

Example:

{
  "message": "Process exited",
  "type": "exited"
}

ExecKillKilledEvent

Section titled “ExecKillKilledEvent”
type:string

(const: `"killed"`)

message:string

Status message

Example:

{
  "message": "Process killed",
  "type": "killed"
}

ExecKillSignalEvent

Section titled “ExecKillSignalEvent”
type:string

(const: `"signal"`)

message:string

Status message

signal:string

Signal name (e.g., `SIGTERM`)

pid:number

Target process ID

Example:

{
  "message": "Signaling SIGTERM to process group 1847",
  "pid": 1847,
  "signal": "SIGTERM",
  "type": "signal"
}

ExecKillTimeoutEvent

Section titled “ExecKillTimeoutEvent”
type:string

(const: `"timeout"`)

message:string

Status message

Example:

{
  "message": "Timeout after 10s, sending SIGKILL",
  "type": "timeout"
}

ExecSession

Section titled “ExecSession”
id:string

Session identifier

created:string (ISO 8601)

Session creation time

command:string

Command being executed

workdir:string

Working directory

tty:boolean

Whether the session has a TTY

bytes_per_second:number

Recent output rate

is_active:boolean

Whether the session has recent output or attached clients

last_activity:optionalstring (ISO 8601)?

Time of the most recent output

ExecSessionListResponse

Section titled “ExecSessionListResponse”
sessions:ExecSession[]

Active exec sessions

count:number

Number of active sessions

error:optionalstring

Present when the session manager is unavailable

ListResponse

Section titled “ListResponse”
path:string
entries:Entry[]
count:number

NetworkPolicyRequest

Section titled “NetworkPolicyRequest”
rules:NetworkPolicyRule[]

List of network policy rules

Example:

{
  "rules": [
    {
      "action": "allow",
      "domain": "github.com"
    },
    {
      "action": "allow",
      "domain": "*.npmjs.org"
    }
  ]
}

NetworkPolicyRule

Section titled “NetworkPolicyRule”
domain:optionalstring

Domain pattern (e.g., `*.github.com`)

action:optionalstring

`allow` or `deny`

include:optionalstring

Include rules from preset

Example:

{
  "action": "allow",
  "domain": "*.github.com"
}

PortNotificationMessage

Section titled “PortNotificationMessage”
type:PortNotificationType

Notification type

port:number

Port number

address:string

Proxy URL for accessing the port

pid:number

Process ID that opened/closed the port

PrivilegesPolicyDoc

Section titled “PrivilegesPolicyDoc”
profile:optionalstring

Capability profile: `minimal`, `standard` or `privileged`. Empty means unrestricted

devices:optionalstring[]

Device nodes the sprite may access

noNewPrivileges:optionalboolean

Prevent processes from gaining privileges through execve

RenameRequest

Section titled “RenameRequest”
source:string
dest:string
workingDir:string
asRoot:boolean

RenameResponse

Section titled “RenameResponse”
source:string
dest:string

ResourcesPolicyDoc

Section titled “ResourcesPolicyDoc”
memory:optionalResourcesPolicyMemory?

ResourcesPolicyMemory

Section titled “ResourcesPolicyMemory”
limit_mb:number
autoscale:optionalboolean?

Enable dynamic memory autoscaling (default: false)

ServiceLogCompleteEvent

Section titled “ServiceLogCompleteEvent”
type:string

(const: `"complete"`)

log_files:optionalRecord<string, string>

Log file paths

timestamp:number

Unix milliseconds

Example:

{
  "log_files": {
    "combined": "/.sprite/logs/services/webapp.log",
    "stderr": "/.sprite/logs/services/webapp.log",
    "stdout": "/.sprite/logs/services/webapp.log"
  },
  "timestamp": 1767609000000,
  "type": "complete"
}

ServiceLogErrorEvent

Section titled “ServiceLogErrorEvent”
type:string

(const: `"error"`)

data:string

Error message

timestamp:number

Unix milliseconds

Example:

{
  "data": "Failed to start service: command not found",
  "timestamp": 1767609000000,
  "type": "error"
}

ServiceLogExitEvent

Section titled “ServiceLogExitEvent”
type:string

(const: `"exit"`)

exit_code:number

Process exit code

timestamp:number

Unix milliseconds

Example:

{
  "exit_code": 0,
  "timestamp": 1767609000000,
  "type": "exit"
}

ServiceLogStartedEvent

Section titled “ServiceLogStartedEvent”
type:string

(const: `"started"`)

timestamp:number

Unix milliseconds

Example:

{
  "timestamp": 1767609000000,
  "type": "started"
}

ServiceLogStderrEvent

Section titled “ServiceLogStderrEvent”
type:string

(const: `"stderr"`)

data:string

Log line content

timestamp:number

Unix milliseconds

Example:

{
  "data": "Warning: deprecated API usage\n",
  "timestamp": 1767609000000,
  "type": "stderr"
}

ServiceLogStdoutEvent

Section titled “ServiceLogStdoutEvent”
type:string

(const: `"stdout"`)

data:string

Log line content

timestamp:number

Unix milliseconds

Example:

{
  "data": "Server listening on port 3000\n",
  "timestamp": 1767609000000,
  "type": "stdout"
}

ServiceLogStoppedEvent

Section titled “ServiceLogStoppedEvent”
type:string

(const: `"stopped"`)

exit_code:number

Process exit code

timestamp:number

Unix milliseconds

Example:

{
  "exit_code": 0,
  "timestamp": 1767609000000,
  "type": "stopped"
}

ServiceLogStoppingEvent

Section titled “ServiceLogStoppingEvent”
type:string

(const: `"stopping"`)

timestamp:number

Unix milliseconds

Example:

{
  "timestamp": 1767609000000,
  "type": "stopping"
}

ServiceRequest

Section titled “ServiceRequest”
cmd:string

Command to execute

args:string[]

Command arguments

env:optionalRecord<string, string>

Environment variables to add to the base service environment

dir:optionalstring

Working directory for the service

needs:string[]

Service dependencies (started first)

http_port:optionalnumber?

HTTP port for proxy routing

Example:

{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "needs": [
    "postgres"
  ]
}

ServiceResponse

Section titled “ServiceResponse”
name:string

Service name

cmd:string

Command to execute

args:string[]

Command arguments

needs:string[]

Service dependencies

http_port:optionalnumber?

HTTP port for proxy routing

state:optionalServiceState?

Current runtime state

Example:

{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "name": "webapp",
  "needs": [
    "postgres"
  ],
  "state": {
    "name": "webapp",
    "pid": 1567,
    "started_at": "2026-01-05T08:01:00Z",
    "status": "running"
  }
}

ServiceState

Section titled “ServiceState”
name:string

Service name

status:string

`stopped`, `starting`, `running`, `stopping`, or `failed`

pid:optionalnumber

Process ID when running

started_at:optionalstring

ISO 8601 timestamp

error:optionalstring

Error message if failed

Example:

{
  "name": "webapp",
  "pid": 1567,
  "started_at": "2026-01-05T08:01:00Z",
  "status": "running"
}

StreamCompleteEvent

Section titled “StreamCompleteEvent”
type:string

(const: `"complete"`)

data:string

Completion message

time:string (ISO 8601)

Timestamp

Example:

{
  "data": "Checkpoint v3 created successfully",
  "time": "2026-01-05T10:30:00Z",
  "type": "complete"
}

StreamErrorEvent

Section titled “StreamErrorEvent”
type:string

(const: `"error"`)

error:string

Error description

code:optionalstring

Machine-readable error class, empty when unclassified

time:string (ISO 8601)

Timestamp

Example:

{
  "error": "Checkpoint failed: disk full",
  "time": "2026-01-05T10:30:00Z",
  "type": "error"
}

StreamInfoEvent

Section titled “StreamInfoEvent”
type:string

(const: `"info"`)

data:string

Status message

time:string (ISO 8601)

Timestamp

Example:

{
  "data": "Creating checkpoint...",
  "time": "2026-01-05T10:30:00Z",
  "type": "info"
}

StreamKeepaliveEvent

Section titled “StreamKeepaliveEvent”
type:string

(const: `"keepalive"`)

time:string (ISO 8601)

Timestamp

WriteResponse

Section titled “WriteResponse”
path:string
size:number
mode:string

Enums

Section titled “Enums”

Handler

Section titled “Handler”

Handler identifies a handler function

Value
ExecHandler
ExecHTTPHandler
ExecAttachHandler
ExecKillHandler
HandleCheckpoint
HandleListCheckpoints
HandleGetCheckpoint
HandleCheckpointRestore
HandleDeleteCheckpoint
HandleProxy
HandlePolicyNetwork
HandlePolicyPrivileges
HandlePolicyResources
HandleListServices
HandleGetService
HandleCreateService
HandleStartService
HandleStopService
HandleRestartService
HandleDeleteService
HandleSuspend
HandleLogs
HandleSetSpriteEnvironment
HandleDebugCreateZombie
HandleDebugCheckProcess
HandleAdminResetState
HandleServiceLogs
HandlePortWatch
HandleControl
HandleFsRead
HandleFsWrite
HandleFsList
HandleFsDelete
HandleFsRename
HandleFsCopy
HandleFsChmod
HandleFsChown
HandleFsWatch

Middleware

Section titled “Middleware”

Middleware identifies a middleware function

Value
auth
wait_for_process
wait_for_storage
wait_for_policy
enrich_context
exec_ack

PortNotificationType

Section titled “PortNotificationType”

PortNotificationType represents the type of port notification

Value
port_opened
port_closed

WebSocket Messages

Section titled “WebSocket Messages”

These message types are used for WebSocket communication in exec and proxy endpoints.

ExitMessage

Section titled “ExitMessage”
type:string

(const: `"exit"`)

exit_code:number

Process exit code

Example:

{
  "exit_code": 0,
  "type": "exit"
}

PortListMessage

Section titled “PortListMessage”
type:string

(const: `"port_list"`)

ports:PortNotificationMessage[]

PortNotificationMessage

Section titled “PortNotificationMessage”
type:PortNotificationType

Notification type

port:number

Port number

address:string

Proxy URL for accessing the port

pid:number

Process ID that opened/closed the port

Example:

{
  "address": "https://my-sprite.sprites.dev:3000",
  "pid": 1847,
  "port": 3000,
  "type": "port_opened"
}

ProxyInitMessage

Section titled “ProxyInitMessage”
host:string

Target hostname (typically "localhost")

port:number

Target port (1-65535)

Example:

{
  "host": "localhost",
  "port": 5432
}

ResizeMessage

Section titled “ResizeMessage”
type:string

(const: `"resize"`)

cols:number

New column count

rows:number

New row count

Example:

{
  "cols": 180,
  "rows": 50,
  "type": "resize"
}

SessionInfoMessage

Section titled “SessionInfoMessage”
type:string

(const: `"session_info"`)

session_id:string

Session ID

command:string

Command being executed

created:number

Unix timestamp of session creation

cols:number

Terminal columns (TTY mode only)

rows:number

Terminal rows (TTY mode only)

is_owner:boolean

Whether this attachment owns the session

tty:boolean

Whether session is in TTY mode

Example:

{
  "cols": 120,
  "command": "bash",
  "created": 1767609000,
  "is_owner": true,
  "rows": 40,
  "session_id": "1847",
  "tty": true,
  "type": "session_info"
}

WatchMessage

Section titled “WatchMessage”
type:string
paths:optionalstring[]
recursive:optionalboolean
workingDir:optionalstring
path:optionalstring
event:optionalstring
timestamp:optionalstring
size:optionalnumber
isDir:optionalboolean
message:optionalstring
Was this page helpful?