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.

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
systemctl --user status rigbox-svc-api-server

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

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

Services run under the developer user’s systemd instance, so use systemctl --user (not sudo systemctl).

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.

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

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

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

Next Steps

​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

​Next Steps

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

Next Steps