Exec API

WebSocket Endpoints — Some endpoints in this section use WebSocket for bidirectional communication. The SDK handles the connection protocol automatically.

Execute Command

WSS/v1/sprites/{name}/exec

Execute a command in the sprite environment via WebSocket. Commands continue running after disconnect; use `max_run_after_disconnect` to control timeout. Supports TTY and non-TTY modes.

Query Parameters

cmd:string

Command to execute (can be repeated for command + args)

id:optionalstring

Session ID to attach to an existing session

path:optionalstring

Explicit path to executable (defaults to first `cmd` value or `bash`)

tty:optionalbool

Enable TTY mode (default: `false`)

stdin:optionalbool

Enable stdin. TTY default: `true`, non-TTY default: `false`

cols:optionalint

Initial terminal columns (default: `80`)

rows:optionalint

Initial terminal rows (default: `24`)

max_run_after_disconnect:optionalduration

Max time to run after disconnect. TTY default: `0` (forever), non-TTY default: `10s`

env:optionalstring

Environment variables in `KEY=VALUE` format (can be repeated). If set, replaces the default environment.

Responses

Status	Description
101	Switching Protocols - WebSocket connection established
400	Bad Request - Invalid WebSocket upgrade or missing parameters
404	Not Found - Resource not found

Client → Server Messages

ResizeMessage

Field	Type	Description
type	string	(const: "resize")
cols	uint16	New column count
rows	uint16	New row count

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

Server → Client Messages

SessionInfoMessage

Field	Type	Description
type	string	(const: "session_info")
session_id	int	Process PID
command	string	Command being executed
created	int64	Unix timestamp of session creation
cols	uint16	Terminal columns (TTY mode only)
rows	uint16	Terminal rows (TTY mode only)
is_owner	bool	Whether this attachment owns the session
tty	bool	Whether session is in TTY mode

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

ExitMessage

Field	Type	Description
type	string	(const: "exit")
exit_code	int	Process exit code

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

PortNotificationMessage

Field	Type	Description
type	PortNotificationType	Notification type
port	int	Port number
address	string	Proxy URL for accessing the port
pid	int	Process ID that opened/closed the port

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

Request

CLI

sprite exec echo hello world

token := os.Getenv("SPRITE_TOKEN")
spriteName := os.Getenv("SPRITE_NAME")

client := sprites.New(token)
sprite := client.Sprite(spriteName)

cmd := sprite.Command("echo", "hello", "world")
output, err := cmd.Output()
if err != nil {
log.Fatal(err)
}

fmt.Print(string(output))

// Example: Execute Command
// Endpoint: WSS /v1/sprites/{name}/exec


const token = process.env.SPRITE_TOKEN!;
const spriteName = process.env.SPRITE_NAME!;

const client = new SpritesClient(token);
const sprite = client.sprite(spriteName);

const result = await sprite.exec('echo', ['hello', 'world']);

process.stdout.write(result.stdout);

import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

cmd = sprite.command("echo", "hello", "world")
output = cmd.output()

print(output.decode(), end="")

token = System.get_env("SPRITE_TOKEN")
sprite_name = System.get_env("SPRITE_NAME")

client = Sprites.new(token)
sprite = Sprites.sprite(client, sprite_name)

{output, _exit_code} = Sprites.cmd(sprite, "echo", ["hello", "world"])

IO.write(output)

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://$SPRITE_NAME.sprites.app/v1/sprites/$SPRITE_NAME/exec"

---

List Exec Sessions

GET/v1/sprites/{name}/exec

List active exec sessions.

Responses

Status	Description
200	Success
404	Not Found - Resource not found
500	Internal Server Error

Request

Python

import json
import os

from sprites import SpritesClient

token = os.environ["SPRITE_TOKEN"]
sprite_name = os.environ["SPRITE_NAME"]

client = SpritesClient(token)
sprite = client.sprite(sprite_name)

sessions = sprite.list_sessions()

result = []
for s in sessions:
  item = {
      "id": s.id,
      "command": s.command,
      "is_active": s.is_active,
      "tty": s.tty,
  }
  result.append(item)

print(json.dumps(result, indent=2))

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://$SPRITE_NAME.sprites.app/v1/sprites/$SPRITE_NAME/exec"

Response

[
{
  "bytes_per_second": 125.5,
  "command": "bash",
  "created": "2026-01-05T10:30:00Z",
  "id": 1847,
  "is_active": true,
  "last_activity": "2026-01-05T10:35:00Z",
  "tty": true,
  "workdir": "/home/sprite/myproject"
},
{
  "bytes_per_second": 0,
  "command": "python -m http.server 8000",
  "created": "2026-01-05T09:15:00Z",
  "id": 1923,
  "is_active": false,
  "last_activity": "2026-01-05T09:20:00Z",
  "tty": false,
  "workdir": "/home/sprite/webapp"
}
]

---

Attach to Exec Session

WSS/v1/sprites/{name}/exec/{session_id}

Attach to an existing exec session via WebSocket.

Responses

Status	Description
101	Switching Protocols - WebSocket connection established
400	Bad Request - Invalid WebSocket upgrade or missing parameters
404	Not Found - Resource not found

Client → Server Messages

ResizeMessage

Field	Type	Description
type	string	(const: "resize")
cols	uint16	New column count
rows	uint16	New row count

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

Server → Client Messages

SessionInfoMessage

Field	Type	Description
type	string	(const: "session_info")
session_id	int	Process PID
command	string	Command being executed
created	int64	Unix timestamp of session creation
cols	uint16	Terminal columns (TTY mode only)
rows	uint16	Terminal rows (TTY mode only)
is_owner	bool	Whether this attachment owns the session
tty	bool	Whether session is in TTY mode

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

ExitMessage

Field	Type	Description
type	string	(const: "exit")
exit_code	int	Process exit code

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

Request

cURL

curl \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://$SPRITE_NAME.sprites.app/v1/sprites/$SPRITE_NAME/exec/$SESSION_ID"

---

Kill Exec Session

POST/v1/sprites/{name}/exec/{session_id}/kill

Kill an exec session by session ID. Returns streaming NDJSON with kill progress.

Query Parameters

signal:optionalstring

Signal to send (default: `SIGTERM`)

timeout:optionalduration

Timeout waiting for process to exit (default: `10s`)

Responses

Status	Description
200	Success - Streaming NDJSON response
404	Not Found - Resource not found
500	Internal Server Error

Streaming Events

This endpoint returns streaming NDJSON. Each line is one of these event types:

signal

Field	Type	Description
type	string	(const: "signal")
message	string	Status message
signal	string	Signal name (e.g., SIGTERM)
pid	int	Target process ID

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

timeout

Field	Type	Description
type	string	(const: "timeout")
message	string	Status message

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

exited

Field	Type	Description
type	string	(const: "exited")
message	string	Status message

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

killed

Field	Type	Description
type	string	(const: "killed")
message	string	Status message

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

error

Field	Type	Description
type	string	(const: "error")
message	string	Error message

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

complete

Field	Type	Description
type	string	(const: "complete")
exit_code	int	Process exit code

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

Request

cURL

curl -X POST \
-H "Authorization: Bearer $SPRITE_TOKEN" \
"https://$SPRITE_NAME.sprites.app/v1/sprites/$SPRITE_NAME/exec/$SESSION_ID/kill"

Response

[
{
  "message": "Signaling SIGTERM to process group 1847",
  "pid": 1847,
  "signal": "SIGTERM",
  "type": "signal"
},
{
  "message": "Process exited",
  "type": "exited"
},
{
  "exit_code": 0,
  "type": "complete"
}
]

---