Service Specs

Service specs define long-running background processes that run inside your workspaces. Each spec becomes a systemd unit file, giving you process management, automatic restarts, and log capture out of the box.

Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account. Create, update, and delete service specs from your local terminal. Inside a workspace, rig service-spec ls works, but the commands that change a spec refuse: an account spec also applies to your other workspaces, so a workspace can’t change one.

How Service Specs Work

When you attach a service spec to a workspace, Rigbox generates a systemd service unit file inside the VM:

Unit name: rigbox-svc-{name}.service
Runs as: the developer user
Working directory: /home/developer
Environment: variables you define in env_vars, plus any workspace-level environment

If auto_enable is set to true, the service starts automatically when the workspace boots - after setup scripts have finished.

Create a Service Spec

Define a service spec in a YAML file with the command to run, environment variables, and restart behavior, then create it with the CLI.

cat > api-server.yaml <<'EOF'
name: api-server
exec_start: node /home/developer/app/server.js
env_vars:
  PORT: "3000"
  NODE_ENV: production
restart_policy: always
auto_enable: true
EOF

rig service-spec create --file api-server.yaml

See the Service Specs API reference for the full request and response schema.

Service Spec Fields

Field	Type	Required	Description
`name`	string	Yes	Service identifier. Must be unique within your account. Becomes part of the systemd unit name.
`exec_start`	string	Yes	The command to run. Use absolute paths.
`env_vars`	object	No	Key-value pairs of environment variables for the service.
`restart_policy`	string	No	One of `always`, `on-failure`, or `no`. Default: `on-failure`.
`auto_enable`	boolean	No	If `true`, the service starts automatically on workspace boot. Default: `false`.

Restart Policies

Policy	Behavior
`always`	Restart the service whenever it exits, regardless of exit code
`on-failure`	Restart only if the service exits with a non-zero exit code
`no`	Never restart - if the process exits, it stays stopped

Use always for servers and daemons that should run continuously. Use on-failure for tasks that should recover from crashes but not restart after a clean exit. Use no for one-shot tasks.

Attach to a Workspace

Pass --service-spec-id (repeatable) when spawning a workspace.

rig workspace spawn --name fullstack-app --template dev \
  --service-spec-id svc_abc123 \
  --service-spec-id svc_def456

All specified service specs are installed as systemd units inside the workspace. Those with auto_enable: true start automatically after boot and setup scripts complete.

Manage Services Inside the Workspace

Once inside the workspace VM, you can manage services using standard systemctl commands:

# Check status
sudo systemctl status rigbox-svc-api-server

# View logs
sudo journalctl -u rigbox-svc-api-server -f

# Manually start/stop/restart
sudo systemctl start rigbox-svc-api-server
sudo systemctl stop rigbox-svc-api-server
sudo systemctl restart rigbox-svc-api-server

Service specs create system units under /etc/systemd/system with User=developer. Use sudo systemctl to manage the unit; the service process runs as the developer user.

List Your Service Specs

rig service-spec ls

[
  {
    "id": "svc_abc123",
    "name": "api-server",
    "exec_start": "node /home/developer/app/server.js",
    "env_vars": {"PORT": "3000", "NODE_ENV": "production"},
    "restart_policy": "always",
    "auto_enable": true,
    "created_at": "2026-04-01T10:00:00Z"
  },
  {
    "id": "svc_def456",
    "name": "worker",
    "exec_start": "python /home/developer/app/worker.py",
    "env_vars": {"QUEUE": "default"},
    "restart_policy": "on-failure",
    "auto_enable": true,
    "created_at": "2026-04-02T14:30:00Z"
  }
]

See the List Service Specs API reference for details.

Update a Service Spec

cat > api-server.yaml <<'EOF'
name: api-server
exec_start: node /home/developer/app/server.js
env_vars:
  PORT: "3000"
  NODE_ENV: production
  LOG_LEVEL: debug
restart_policy: always
auto_enable: true
EOF

rig service-spec update --id svc_abc123 --file api-server.yaml

Changes to a service spec take effect on the next workspace start. Running workspaces will not pick up changes automatically - you need to restart the workspace.

Delete a Service Spec

rig service-spec rm --id svc_abc123

Combining with Setup Scripts

A common pattern is to use a setup script to install dependencies and a service spec to run the application. The setup script runs first, so your service spec can assume everything is installed. Step 1 - Create a setup script that installs dependencies:

cat > install-app-deps.sh <<'EOF'
#!/bin/bash
set -e
cd /home/developer/app
git pull origin main
npm ci
npm run build
EOF

rig setup-script create --name install-app-deps --file install-app-deps.sh

Step 2 - Create a service spec that runs the app:

cat > app-server.yaml <<'EOF'
name: app-server
exec_start: node /home/developer/app/dist/server.js
env_vars:
  PORT: "8080"
restart_policy: always
auto_enable: true
EOF

rig service-spec create --file app-server.yaml

Step 3 - Spawn a workspace with both:

rig workspace spawn --name production-app --template dev \
  --setup-script-id ss_install_deps \
  --service-spec-id svc_app_server

Execution order on workspace boot:

Setup scripts run (install dependencies, build the app)
Service specs with auto_enable: true start (launch the server)

Combining with Apps

To expose a service spec’s port to the internet, create an app that maps to the service’s port.

# Service spec runs a web server on port 3000
# Create an app to expose it

rig app new --name <APP_NAME> --port 3000 --workspace {workspace_id}

The app gets a unique URL of the form <APP_NAME>.rigbox.dev that routes to port 3000 inside the workspace where your service spec is running.

Example: Full-Stack Application

Here is a complete example that sets up a React frontend and Node.js backend as two separate services. Setup script - install everything:

#!/bin/bash
set -e

cd /home/developer
git clone https://github.com/acme/fullstack-app.git app
cd app

# Backend
cd backend && npm ci && cd ..

# Frontend
cd frontend && npm ci && npm run build && cd ..

Backend service spec:

{
  "name": "backend",
  "exec_start": "node /home/developer/app/backend/server.js",
  "env_vars": {
    "PORT": "4000",
    "DATABASE_URL": "sqlite:///home/developer/app/data.db"
  },
  "restart_policy": "always",
  "auto_enable": true
}

Frontend service spec:

{
  "name": "frontend",
  "exec_start": "npx serve /home/developer/app/frontend/dist -l 3000",
  "env_vars": {
    "API_URL": "http://localhost:4000"
  },
  "restart_policy": "always",
  "auto_enable": true
}

Both services start on workspace boot, and you can expose either or both via apps.

Verify and troubleshoot

Use the returned definition ID when attaching it to a workspace. After startup, inspect rig workspace logs --workspace WORKSPACE_ID; for service specs, check the installed unit with the commands above. A running VM does not prove a setup script or application completed successfully. For failures, start with runtime logs, health checks, or resource exhaustion.

Next Steps

Setup Scripts - automate dependency installation before services start
Snapshots - snapshot a workspace with running services for quick restore
Managed AI Proxy - add AI capabilities to your background services

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Before you begin

How Service Specs Work

Create a Service Spec

Service Spec Fields

Restart Policies

Attach to a Workspace

Manage Services Inside the Workspace

List Your Service Specs

Update a Service Spec

Delete a Service Spec

Combining with Setup Scripts

Combining with Apps

Example: Full-Stack Application

Verify and troubleshoot

Next Steps

​Before you begin

​How Service Specs Work

​Create a Service Spec

​Service Spec Fields

​Restart Policies

​Attach to a Workspace

​Manage Services Inside the Workspace

​List Your Service Specs

​Update a Service Spec

​Delete a Service Spec

​Combining with Setup Scripts

​Combining with Apps

​Example: Full-Stack Application

​Verify and troubleshoot

​Next Steps

Before you begin

How Service Specs Work

Create a Service Spec

Service Spec Fields

Restart Policies

Attach to a Workspace

Manage Services Inside the Workspace

List Your Service Specs

Update a Service Spec

Delete a Service Spec

Combining with Setup Scripts

Combining with Apps

Example: Full-Stack Application

Verify and troubleshoot

Next Steps