Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 8 additions & 27 deletions src/content/docs/concepts/checkpoints.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -260,12 +260,6 @@ sprite checkpoint delete v3
# Output: Deleted
```
</TabItem>
<TabItem label="cURL">
```bash
# Delete via internal API (from inside the Sprite)
curl-sprite-api -X DELETE /v1/checkpoints/v3
```
</TabItem>
</Tabs>

### Delete Restrictions
Expand All @@ -290,25 +284,19 @@ To delete an active checkpoint, first restore to a different checkpoint, then de

You can create and restore checkpoints from within the Sprite itself using the internal API. This is particularly useful for LLMs and automation scripts.

### Using curl-sprite-api
### Using sprite-env

The `curl-sprite-api` command simplifies access to the internal API:
The `sprite-env` command simplifies access to the internal API:

```bash
# List all checkpoints
curl-sprite-api /v1/checkpoints

# Get details for a specific checkpoint
curl-sprite-api /v1/checkpoints/v2
sprite-env checkpoints list

# Create a new checkpoint (streams progress)
curl-sprite-api -X POST /v1/checkpoint
sprite-env checkpoints create

# Restore from a checkpoint
curl-sprite-api -X POST /v1/checkpoints/v1/restore

# Delete a checkpoint
curl-sprite-api -X DELETE /v1/checkpoints/v3
sprite-env checkpoints restore v1
```

### Direct API Access
Expand All @@ -325,10 +313,6 @@ curl --unix-socket /.sprite/api.sock \
curl --unix-socket /.sprite/api.sock \
-H "Content-Type: application/json" \
-X POST http://sprite/v1/checkpoint

# Delete checkpoint
curl --unix-socket /.sprite/api.sock \
-X DELETE http://sprite/v1/checkpoints/v3
```

### Checkpoint Creation Response
Expand All @@ -347,7 +331,7 @@ Restore requests return immediately with HTTP 202 (Accepted) and trigger the res

```bash
# This returns immediately, then the sprite restarts with restored state
curl-sprite-api -X POST /v1/checkpoints/v1/restore
sprite-env checkpoints restore v1
```

### LLM Self-Checkpointing
Expand All @@ -356,17 +340,14 @@ AI coding agents can checkpoint their own work. Point your LLM at `/.sprite/llm.

```bash
# Before risky operations
curl-sprite-api -X POST /v1/checkpoint
sprite-env checkpoints create
# Output: {"status": "complete", "id": "v4"}

# Try something risky...
rm -rf node_modules && npm install

# If things go wrong, restore
curl-sprite-api -X POST /v1/checkpoints/v4/restore

# Clean up old checkpoints when done
curl-sprite-api -X DELETE /v1/checkpoints/v3
sprite-env checkpoints restore v4
```

This enables autonomous recovery when experiments fail.
Expand Down
40 changes: 20 additions & 20 deletions src/content/docs/concepts/services.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ Services are long-running processes managed by the Sprite runtime that automatic

## Overview

Services are managed through the internal API at `/.sprite/api.sock`. The `curl-sprite-api` command provides a convenient wrapper:
Services are managed through the internal API at `/.sprite/api.sock`. The `sprite-env` command provides a convenient wrapper:

```bash
# List all services
curl-sprite-api /v1/services
sprite-env services list

# Get help and see all endpoints
curl-sprite-api --help
sprite-env services --help
```

## Creating Services
Expand All @@ -23,13 +23,13 @@ Create a service with a PUT request:

```bash
# Simple service
curl-sprite-api -X PUT /v1/services/myapp -d '{
sprite-env curl -X PUT /v1/services/myapp -d '{
"cmd": "/usr/bin/myapp",
"args": ["--port", "8080"]
}'

# Service with dependencies
curl-sprite-api -X PUT /v1/services/webapp -d '{
sprite-env curl -X PUT /v1/services/webapp -d '{
"cmd": "npm",
"args": ["run", "dev"],
"needs": ["database"]
Expand All @@ -50,7 +50,7 @@ When you create a service, the API streams logs in NDJSON format:

```bash
# Stream logs for 10 seconds after creation
curl-sprite-api -X PUT '/v1/services/myapp?duration=10s' -d '{
sprite-env curl -X PUT '/v1/services/myapp?duration=10s' -d '{
"cmd": "npm",
"args": ["run", "dev"]
}'
Expand All @@ -63,7 +63,7 @@ The default streaming duration is 5 seconds. Set `duration=0` to return immediat
### List Services

```bash
curl-sprite-api /v1/services
sprite-env services list
```

Returns a JSON array of services with their current states:
Expand All @@ -88,13 +88,13 @@ Returns a JSON array of services with their current states:
### Get Service State

```bash
curl-sprite-api /v1/services/webapp
sprite-env services get webapp
```

### Delete a Service

```bash
curl-sprite-api -X DELETE /v1/services/webapp
sprite-env services delete webapp
```

### Send Signals
Expand All @@ -103,19 +103,19 @@ Send Unix signals to a service:

```bash
# Graceful shutdown
curl-sprite-api -X POST /v1/services/signal -d '{
sprite-env curl -X POST /v1/services/signal -d '{
"name": "webapp",
"signal": "TERM"
}'

# Force kill
curl-sprite-api -X POST /v1/services/signal -d '{
sprite-env curl -X POST /v1/services/signal -d '{
"name": "webapp",
"signal": "KILL"
}'

# Reload configuration (for services that support it)
curl-sprite-api -X POST /v1/services/signal -d '{
sprite-env curl -X POST /v1/services/signal -d '{
"name": "nginx",
"signal": "HUP"
}'
Expand Down Expand Up @@ -152,7 +152,7 @@ Choose the right approach for your use case:

```bash
# Create a Node.js dev server service
curl-sprite-api -X PUT /v1/services/devserver -d '{
sprite-env curl -X PUT /v1/services/devserver -d '{
"cmd": "npm",
"args": ["run", "dev"]
}'
Expand All @@ -162,13 +162,13 @@ curl-sprite-api -X PUT /v1/services/devserver -d '{

```bash
# First, create the database service
curl-sprite-api -X PUT /v1/services/postgres -d '{
sprite-env curl -X PUT /v1/services/postgres -d '{
"cmd": "/usr/lib/postgresql/16/bin/postgres",
"args": ["-D", "/home/sprite/pgdata"]
}'

# Then create a service that depends on it
curl-sprite-api -X PUT /v1/services/webapp -d '{
sprite-env curl -X PUT /v1/services/webapp -d '{
"cmd": "npm",
"args": ["start"],
"needs": ["postgres"]
Expand All @@ -178,7 +178,7 @@ curl-sprite-api -X PUT /v1/services/webapp -d '{
### Python Background Worker

```bash
curl-sprite-api -X PUT /v1/services/worker -d '{
sprite-env curl -X PUT /v1/services/worker -d '{
"cmd": "python",
"args": ["-m", "celery", "worker", "-A", "tasks"]
}'
Expand All @@ -190,17 +190,17 @@ AI coding agents can manage services through the internal API. Point your LLM at

```bash
# LLM creates a service for the project it's working on
curl-sprite-api -X PUT /v1/services/devserver -d '{
sprite-env curl -X PUT /v1/services/devserver -d '{
"cmd": "npm",
"args": ["run", "dev"],
"dir": "/home/sprite/project"
}'

# Check if it's running
curl-sprite-api /v1/services/devserver
sprite-env services get devserver

# Restart after making changes
curl-sprite-api -X POST /v1/services/signal -d '{"name": "devserver", "signal": "TERM"}'
sprite-env curl -X POST /v1/services/signal -d '{"name": "devserver", "signal": "TERM"}'
# Service auto-restarts
```

Expand All @@ -225,7 +225,7 @@ The service manager will restart crashed services. If a service exits immediatel
Stream logs when creating the service:

```bash
curl-sprite-api -X PUT '/v1/services/myapp?duration=60s' -d '{...}'
sprite-env curl -X PUT '/v1/services/myapp?duration=60s' -d '{...}'
```

Or check system logs:
Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/reference/base-images.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -322,19 +322,19 @@ cat /.sprite/languages/rust/llm.txt

The base image includes several tools for interacting with the Sprite runtime from inside the environment.

### curl-sprite-api
### sprite-env

A convenience wrapper for accessing the internal API via Unix socket:
A convenience command for managing Sprite environment services and checkpoints:

```bash
# Instead of:
curl --unix-socket /.sprite/api.sock -H "Content-Type: application/json" http://sprite/v1/services

# You can use:
curl-sprite-api /v1/services
sprite-env services list

# See all available endpoints
curl-sprite-api --help
# See all available commands
sprite-env --help
```

The internal API manages:
Expand Down Expand Up @@ -362,7 +362,7 @@ Launches the appropriate login shell based on your local environment. When you r

### Internal API Socket

The Sprite runtime exposes a Unix socket at `/.sprite/api.sock` for internal management. While `curl-sprite-api` is the recommended way to interact with it, you can also use it directly:
The Sprite runtime exposes a Unix socket at `/.sprite/api.sock` for internal management. While `sprite-env` is the recommended way to interact with it, you can also use the socket directly with `sprite-env curl` or raw curl:

```bash
# Using curl directly
Expand Down