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

# devbox service

> Create, inspect, and control supervised services on a Devbox.

Use `devbox service` to run long-lived commands, such as dev servers, as services on a Devbox. A service starts when you create it and again every time the Devbox boots. The Devbox restarts it after failures and retains its logs.

Every subcommand takes the Devbox and the service as optional positional arguments. On a terminal, omitting either opens a picker. The service picker lists only services you created. Without a terminal, pass both arguments explicitly.

<h2 id="service-usage">
  Usage
</h2>

```bash theme={null}
devbox service [command]
```

<h2 id="service-options">
  Options
</h2>

<ResponseField name="--show_all" type="boolean" default="false">
  Include Devboxes owned by other workspace members in the Devbox picker. Every `devbox service` subcommand accepts this option.
</ResponseField>

## `devbox service create`

Create a service that starts now and on each boot, and restarts after failures. Pass the command after `--`. It runs without a shell, so wrap shell features such as `&&` and pipes in `sh -c '...'`. If you omit the name or the command, the CLI prompts for them, and it also prompts for the working directory.

The command runs in the Devbox's default directory. Relative `--cwd` paths start there.

On a terminal, the CLI prints the service details and then streams its logs for five seconds, so you can see whether it started cleanly. The command fails if the service was created but could not start.

<h3 id="create-usage">
  Usage
</h3>

```bash theme={null}
devbox service create [devbox] [-- <command> [args...]] [flags]
```

### Create a dev server

```bash theme={null}
devbox service create my-devbox --name web -- npm run dev
```

### Use shell features

```bash theme={null}
devbox service create my-devbox --name web --cwd frontend -- sh -c 'npm install && npm run dev'
```

<h3 id="create-options">
  Options
</h3>

<ResponseField name="--cwd" type="string">
  Run the command in this directory. Relative paths start at the Devbox's default directory.
</ResponseField>

<ResponseField name="--logs_for" type="int" default="5">
  Stream logs for this many seconds after creating the service.
</ResponseField>

<ResponseField name="--name" type="string">
  Name the service. Names must be unique on the Devbox. The CLI prompts for a name if you omit it.
</ResponseField>

<ResponseField name="--no_logs" type="boolean" default="false">
  Skip log streaming after creating the service.
</ResponseField>

***

## `devbox service list`

List the services on a Devbox. The default table shows each service's name, status, and command, plus its ports when any service has them. Status is `starting`, `running`, `restarting`, `failed`, `stopping`, `stopped`, or `not started`.

<h3 id="list-usage">
  Usage
</h3>

```bash theme={null}
devbox service list [devbox] [flags]
```

### List services as JSON

```bash theme={null}
devbox service list my-devbox --output json
```

The JSON output is an object with a `services` array. Each entry has the same fields as [`devbox service describe --output json`](#devbox-service-describe).

<h3 id="list-options">
  Options
</h3>

<ResponseField name="-o, --output" type="string" default="text">
  Set the output format to `text` or `json`.
</ResponseField>

***

## `devbox service describe`

Show a service's configuration, current status, and how to reach it. The output ends with the commands to open its ports, start it if it is stopped, and stream its logs.

<h3 id="describe-usage">
  Usage
</h3>

```bash theme={null}
devbox service describe [devbox] [service] [flags]
```

### Describe a service

```bash theme={null}
devbox service describe my-devbox web
```

```text Output nocopy theme={null}
Service web on my-devbox

  ID        svc_ihb6ipl2tgkbnkmp
  Command   npm run dev
  Directory /workspaces/my-repo
  Status    running (PID 42)
  Starts    on boot, restarts on failure

Stream logs:
  devbox service logs my-devbox web
```

When a service is restarting, `Status` includes the last exit code and the restart count. When a service is stopped, the output shows the `devbox service start` command that brings it back.

### Describe a service as JSON

```bash theme={null}
devbox service describe my-devbox web --output json
```

```json Output nocopy theme={null}
{
  "id": "svc_ihb6ipl2tgkbnkmp",
  "name": "web",
  "status": "running",
  "command": ["npm", "run", "dev"],
  "cwd": "/workspaces/my-repo",
  "start_policy": "on-boot",
  "restart_policy": "on-failure",
  "stopped": false,
  "process": {
    "status": "running",
    "pid": 42,
    "restarts": 0
  }
}
```

`ports` is included when the service has ports. `process.last_exit` is included after the service has exited at least once.

<h3 id="describe-options">
  Options
</h3>

<ResponseField name="-o, --output" type="string" default="text">
  Set the output format to `text` or `json`.
</ResponseField>

***

## `devbox service logs`

Replay the output retained for a service's latest run, then follow new output. Following ends when that run exits. It does not continue into the next run after a restart.

<h3 id="logs-usage">
  Usage
</h3>

```bash theme={null}
devbox service logs [devbox] [service] [flags]
```

### Read the retained logs

```bash theme={null}
devbox service logs my-devbox web --no_follow
```

<h3 id="logs-options">
  Options
</h3>

<ResponseField name="--no_follow" type="boolean" default="false">
  Return after printing the retained logs instead of following new output.
</ResponseField>

***

## `devbox service stop`

Stop a service until you start it again. A stopped service does not start when the Devbox boots, and its ports are closed. By default, the service receives `SIGTERM` and is killed if it has not exited after 15 seconds.

<h3 id="stop-usage">
  Usage
</h3>

```bash theme={null}
devbox service stop [devbox] [service] [flags]
```

### Stop a service

```bash theme={null}
devbox service stop my-devbox web
```

```text Output nocopy theme={null}
Stopped service web on my-devbox. It won't start again until you run:
  devbox service start my-devbox web
```

<h3 id="stop-options">
  Options
</h3>

<ResponseField name="--force" type="boolean" default="false">
  Kill the service immediately instead of letting it shut down gracefully.
</ResponseField>

***

## `devbox service start`

Start a stopped service. The service starts again on each boot.

<h3 id="start-usage">
  Usage
</h3>

```bash theme={null}
devbox service start [devbox] [service]
```

### Start a service

```bash theme={null}
devbox service start my-devbox web
```

***

## `devbox service delete`

Stop a service and permanently remove it, together with its ports. The CLI asks for confirmation. Without a terminal, pass `--force`.

<h3 id="delete-usage">
  Usage
</h3>

```bash theme={null}
devbox service delete [devbox] [service] [flags]
```

### Delete without confirmation

```bash theme={null}
devbox service delete my-devbox web --force
```

```text Output nocopy theme={null}
Deleted service web from my-devbox.
```

<h3 id="delete-options">
  Options
</h3>

<ResponseField name="--force" type="boolean" default="false">
  Skip the confirmation prompt.
</ResponseField>

## Related topics

<CardGroup cols={2}>
  <Card title="Devbox Services" icon="server" href="/docs/devbox/services">
    Run dev servers and other long-lived processes on a Devbox.
  </Card>

  <Card title="devbox logs" icon="scroll" href="/docs/reference/devbox-cli/logs">
    Stream the output of detached executions.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.