> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Specs

> Define long-running background services that start automatically in your workspaces.

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.

```bash theme={null}
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](/api-reference/service-specs/create) 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         |

<Tip>
  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.
</Tip>

## Attach to a Workspace

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

```bash theme={null}
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:

```bash theme={null}
# 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
```

<Note>
  Services run under the `developer` user's systemd instance, so use `systemctl --user` (not `sudo systemctl`).
</Note>

## List Your Service Specs

```bash theme={null}
rig service-spec ls
```

```json theme={null}
[
  {
    "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](/api-reference/service-specs/list) for details.

## Update a Service Spec

```bash theme={null}
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
```

<Warning>
  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.
</Warning>

## Delete a Service Spec

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:

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](/api-reference/apps/create) that maps to the service's port.

```bash theme={null}
# 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:

```bash theme={null}
#!/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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/guides/setup-scripts) - automate dependency installation before services start
* [Snapshots](/guides/snapshots) - snapshot a workspace with running services for quick restore
* [Managed AI Proxy](/guides/managed-proxy) - add AI capabilities to your background services