Skip to main content

​
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 with the command to run, environment variables, and restart behavior. 
curl -X POST https://api.rigbox.dev/api/service-specs \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-server",
    "exec_start": "node /home/developer/app/server.js",
    "env_vars": {
      "PORT": "3000",
      "NODE_ENV": "production"
    },
    "restart_policy": "always",
    "auto_enable": true
  }'
See the Service Specs API reference for the full request and response schema.

​
Service Spec Fields

FieldTypeRequiredDescription
namestringYesService identifier. Must be unique within your account. Becomes part of the systemd unit name.
exec_startstringYesThe command to run. Use absolute paths.
env_varsobjectNoKey-value pairs of environment variables for the service.
restart_policystringNoOne of always, on-failure, or no. Default: on-failure.
auto_enablebooleanNoIf true, the service starts automatically on workspace boot. Default: false.

​
Restart Policies

PolicyBehavior
alwaysRestart the service whenever it exits, regardless of exit code
on-failureRestart only if the service exits with a non-zero exit code
noNever 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

Include service_spec_ids when creating a workspace. 
curl -X POST https://api.rigbox.dev/api/workspaces \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fullstack-app",
    "template_id": "tpl_node",
    "service_spec_ids": ["svc_abc123", "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

curl -s https://api.rigbox.dev/api/service-specs \
  -H "Authorization: Bearer $RIGBOX_TOKEN" | jq .

[
  {
    "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

curl -X PUT https://api.rigbox.dev/api/service-specs/svc_abc123 \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'
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

curl -X DELETE https://api.rigbox.dev/api/service-specs/svc_abc123 \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

​
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: 
curl -X POST https://api.rigbox.dev/api/setup-scripts \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "install-app-deps",
    "content": "#!/bin/bash\nset -e\ncd /home/developer/app\ngit pull origin main\nnpm ci\nnpm run build",
    "run_on": "first_boot"
  }'
Step 2 — Create a service spec that runs the app: 
curl -X POST https://api.rigbox.dev/api/service-specs \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app-server",
    "exec_start": "node /home/developer/app/dist/server.js",
    "env_vars": {"PORT": "8080"},
    "restart_policy": "always",
    "auto_enable": true
  }'
Step 3 — Create a workspace with both: 
curl -X POST https://api.rigbox.dev/api/workspaces \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-app",
    "template_id": "tpl_node",
    "setup_script_ids": ["ss_install_deps"],
    "service_spec_ids": ["svc_app_server"]
  }'
Execution order on workspace boot:
  1. Setup scripts run (install dependencies, build the app)
  2. 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

curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/apps \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-app",
    "port": 3000
  }'
The app gets a unique URL (e.g., my-web-app-ws123.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