Services

Services are long-running processes managed by the Sprite runtime that automatically restart when your Sprite boots. Unlike detachable sessions, services survive full Sprite restarts and are ideal for background daemons, development servers, and databases.

Overview

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

# List all services
sprite-env services list

# Get help and see all endpoints
sprite-env services --help

Creating Services

Create a service with a PUT request:

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

# Service with dependencies
sprite-env curl -X PUT /v1/services/webapp -d '{
  "cmd": "npm",
  "args": ["run", "dev"],
  "needs": ["database"]
}'

Service Configuration

Field	Type	Description
cmd	string	Path to executable (required)
args	string[]	Command arguments
needs	string[]	Services that must start first

Streaming Logs on Creation

When you create a service, the API streams logs in NDJSON format:

# Stream logs for 10 seconds after creation
sprite-env curl -X PUT '/v1/services/myapp?duration=10s' -d '{
  "cmd": "npm",
  "args": ["run", "dev"]
}'

The default streaming duration is 5 seconds. Set duration=0 to return immediately without streaming.

Managing Services

List Services

sprite-env services list

Returns a JSON array of services with their current states:

[
  {
    "name": "webapp",
    "cmd": "npm",
    "args": ["run", "dev"],
    "needs": [],
    "state": {
      "name": "webapp",
      "status": "running",
      "pid": 1234,
      "started_at": "2024-01-15T10:30:00Z"
    }
  }
]

Get Service State

sprite-env services get webapp

Delete a Service

sprite-env services delete webapp

Send Signals

Send Unix signals to a service:

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

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

# Reload configuration (for services that support it)
sprite-env curl -X POST /v1/services/signal -d '{
  "name": "nginx",
  "signal": "HUP"
}'

Services vs Detachable Sessions

Choose the right approach for your use case:

Feature	Services	Detachable Sessions
Survives Sprite restart	Yes	No
Auto-starts on boot	Yes	No
Managed via	Internal API	External CLI/SDK
Dependencies	Supported (needs)	Not supported
Best for	Daemons, servers	One-off tasks, builds

When to Use Services

• Development servers that should always be running
• Databases like PostgreSQL, Redis, or SQLite servers
• Background workers processing queues
• Reverse proxies or other infrastructure

When to Use Detachable Sessions

• Build processes that run once
• Long-running scripts you want to monitor
• Interactive sessions you might reconnect to

Common Patterns

Development Server

# Create a Node.js dev server service
sprite-env curl -X PUT /v1/services/devserver -d '{
  "cmd": "npm",
  "args": ["run", "dev"]
}'

Database with Dependent Service

# First, create the database service
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
sprite-env curl -X PUT /v1/services/webapp -d '{
  "cmd": "npm",
  "args": ["start"],
  "needs": ["postgres"]
}'

Python Background Worker

sprite-env curl -X PUT /v1/services/worker -d '{
  "cmd": "python",
  "args": ["-m", "celery", "worker", "-A", "tasks"]
}'

LLM Integration

AI coding agents can manage services through the internal API. Point your LLM at /.sprite/llm.txt for environment documentation, then it can:

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

# Check if it's running
sprite-env services get devserver

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

Troubleshooting

Service Won’t Start

1. Check the command path is correct and executable exists
2. Verify working directory exists
3. Check dependencies are running if using needs

Service Keeps Restarting

The service manager will restart crashed services. If a service exits immediately:

1. Check logs during creation with duration=30s
2. Verify environment variables are set correctly
3. Test the command manually first

Viewing Service Logs

Stream logs when creating the service:

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

Or check system logs:

journalctl -f  # If available
# or
tail -f /var/log/syslog

Related Documentation

Lifecycle and Persistence

Understanding sprite hibernation and state management

Checkpoints

Save and restore sprite state with checkpoints

Base Images

Pre-installed tools and available images

CLI Commands

Service management commands