Type Definitions

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

Types

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

Example:

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

ChmodRequest

path:string

workingDir:string

mode:string

recursive:boolean

asRoot:boolean

ChmodResponse

affected:ChmodResult[]

count:number

ChmodResult

path:string

mode:string

ChownRequest

path:string

workingDir:string

uid:any

gid:any

recursive:boolean

asRoot:boolean

ChownResponse

affected:ChownResult[]

count:number

ChownResult

path:string

uid:number

gid:number

CopyRequest

source:string

dest:string

workingDir:string

recursive:boolean

preserveAttrs:boolean

asRoot:boolean

CopyResponse

copied:CopyResult[]

count:number

totalBytes:number

CopyResult

source:string

dest:string

CreateCheckpointRequest

comment:optionalstring

Example:

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

DeleteRequest

path:string

workingDir:string

recursive:boolean

asRoot:boolean

DeleteResponse

deleted:string[]

count:number

Entry

name:string

path:string

type:string

size:number

mode:string

modTime:string (ISO 8601)

isDir:boolean

ExecKillCompleteEvent

type:string

(const: `"complete"`)

exit_code:number

Process exit code

Example:

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

ExecKillErrorEvent

type:string

(const: `"error"`)

message:string

Error message

Example:

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

ExecKillExitedEvent

type:string

(const: `"exited"`)

message:string

Status message

Example:

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

ExecKillKilledEvent

type:string

(const: `"killed"`)

message:string

Status message

Example:

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

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

type:string

(const: `"timeout"`)

message:string

Status message

Example:

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

ListResponse

path:string

entries:Entry[]

count:number

NetworkPolicyRequest

rules:NetworkPolicyRule[]

List of network policy rules

Example:

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

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"
}

RenameRequest

source:string

dest:string

workingDir:string

asRoot:boolean

RenameResponse

source:string

dest:string

ServiceLogCompleteEvent

type:string

(const: `"complete"`)

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

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

type:string

(const: `"exit"`)

exit_code:number

Process exit code

timestamp:number

Unix milliseconds

Example:

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

ServiceLogStartedEvent

type:string

(const: `"started"`)

timestamp:number

Unix milliseconds

Example:

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

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

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

type:string

(const: `"stopped"`)

exit_code:number

Process exit code

timestamp:number

Unix milliseconds

Example:

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

ServiceLogStoppingEvent

type:string

(const: `"stopping"`)

timestamp:number

Unix milliseconds

Example:

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

ServiceRequest

cmd:string

Command to execute

args:string[]

Command arguments

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

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

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

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

type:string

(const: `"error"`)

error:string

Error description

time:string (ISO 8601)

Timestamp

Example:

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

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"
}

WriteResponse

path:string

size:number

mode:string

Enums

Handler

Handler identifies a handler function

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

Middleware

Middleware identifies a middleware function

Value
auth
wait_for_process
wait_for_storage
wait_for_policy
enrich_context

PortNotificationType

PortNotificationType represents the type of port notification

Value
port_opened
port_closed

WebSocket Messages

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

ExitMessage

type:string

(const: `"exit"`)

exit_code:number

Process exit code

Example:

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

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

host:string

Target hostname (typically "localhost")

port:number

Target port (1-65535)

Example:

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

ResizeMessage

type:string

(const: `"resize"`)

cols:number

New column count

rows:number

New row count

Example:

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

SessionInfoMessage

type:string

(const: `"session_info"`)

session_id:number

Process PID

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

type:string

paths:optionalstring[]

recursive:optionalboolean

workingDir:optionalstring

path:optionalstring

event:optionalstring

timestamp:optionalstring

size:optionalnumber

isDir:optionalboolean

message:optionalstring