Devbox Services

A service is a command that a Devbox keeps running for you. The Devbox starts it when you create it and again every time the Devbox boots. If the command exits with an error, the Devbox restarts it. Its output is retained, so you can read the logs of a crashed dev server long after you closed the terminal that started it. Use services for the processes your work depends on, for example:

A dev server: pnpm dev
Your favorite coding agent in a remote session: amp --no-tui or claude --remote-control
A file watcher, a local database, or an API mock

Manage Services

A service needs a name and a command. The command runs in the Devbox’s default directory unless you choose another one. Service names must be unique on a Devbox. Deleting a service stops it first.

CLI
TS SDK
Dashboard

# Create a service. Pass its command after --.
devbox service create my-devbox --name web -- pnpm dev

# List the services on the Devbox, with their status.
devbox service list my-devbox

# Show one service's command, directory, status, and how to reach it.
devbox service describe my-devbox web

# Stop the service and remove it permanently.
devbox service delete my-devbox web

The command runs without a shell. For shell syntax or built-ins, use sh -c '...' on Linux and macOS, or powershell.exe -Command '...' on Windows. list and describe accept --output json. delete asks for confirmation; pass --force when running without a terminal. See devbox service for every option.

const devbox = await client.devboxes.get("my-devbox");

// Create a service. Pass the executable and its arguments separately.
await devbox.services.create({
  name: "web",
  command: "pnpm",
  args: ["dev"],
});

// List the services on the Devbox, with their status.
for (const service of await devbox.services.list()) {
  console.log(service.name, service.process?.state ?? "not started");
}

// Fetch one service by name or ID.
const web = await devbox.services.get("web");
console.log(web.process?.state, web.process?.restartCount, web.process?.lastExit);

// Stop the service and remove it permanently.
await devbox.services.delete("web");

See devbox.services for every option and field.

Open the Devbox in the dashboard, and press Add service in the Services section. Enter a Name and a Command, such as pnpm dev. Press Add service to create and start it.

The Add service dialog with the name web and the command pnpm dev

The Services page of a Devbox lists every service with its status. Select a service to see its details and logs.

The Services page of a Devbox listing a running web service with a Stop service button

To delete a service, open the menu next to it on the Services page and select Delete.

The Delete Service confirmation dialog for the web service

A service is in one of these states:

Status	Meaning
`starting`	The process is launching.
`running`	The process is running.
`restarting`	The process exited and is waiting to be restarted.
`failed`	The process exited and will not be restarted.
`stopping`	The service was stopped and the process is shutting down.
`stopped`	The service is stopped and will not start until you start it.
`not started`	The service has no process, for example a `manual` service that has not been started.

Start and Stop Services

Start and stop a service yourself, or let its policies decide when the Devbox starts it automatically and restarts it after it exits. On a persistent Devbox, a stopped service stays stopped across Devbox restarts until you start it again. By default, the process receives SIGTERM on Linux and macOS, or CTRL_BREAK on Windows, and is killed if it has not exited by the end of the grace period. Stopping an ephemeral Devbox removes its services and logs. Blueprint services are recreated on its next start.

CLI
TS SDK
Dashboard

devbox service stop my-devbox web

Add --force to kill the process immediately. Start it again with:

devbox service start my-devbox web

await devbox.services.stop("web");
await devbox.services.stop("web", { mode: "force" });

await devbox.services.start("web");

stop() returns once the stop is requested, so the process may still be stopping. start() fails while a service is still stopping. If the service is already running, start() returns its current process.

Start and Restart Policies

When a Devbox boots, it starts its services after checking out repositories and running the init script. A service that keeps failing is restarted with an increasing delay, up to about a minute between attempts. The delay resets once the service has run for a minute. Two policies control this behavior:

Start policy: on-boot (default) starts the service when it is created and every time the Devbox boots. manual starts it only when you start it explicitly.
Restart policy: on-failure (default) restarts the service after a non-zero exit. always restarts it after any exit. never leaves it stopped, and its status becomes failed after a non-zero exit.

CLI
TS SDK
Dashboard

Services created with the CLI use the defaults: they start on boot and restart on failure.

await devbox.services.create({
  name: "worker",
  command: "./scripts/worker.sh",
  startPolicy: "manual",
  restartPolicy: "always",
  start: true,
});

start overrides the start policy at creation time: true starts the service now, and false creates it stopped. Omit it to follow startPolicy.

View Service Logs

The Devbox retains the output of each service run. Logs replay what has already been captured, then follow new output until that run exits. After a restart, read the logs again to see the new run.

CLI
TS SDK
Dashboard

devbox service logs my-devbox web

Add --no_follow to print the retained output and return.Each service run is also an execution, so it appears in devbox logs list.

for await (const chunk of devbox.services.logs("web")) {
  process.stdout.write(chunk.stdout);
  process.stderr.write(chunk.stderr);
}

The loop ends when the run exits. Break out of it, or pass an abort signal, to stop reading earlier. See services.logs().

Expose a Service

Expose a service’s HTTP port on a shareable URL to open it in your browser. For a dev server listening on port 3000:

Create the service

CLI
TS SDK
Dashboard

devbox service create my-devbox --name web -- pnpm dev

await devbox.services.create({
  name: "web",
  command: "pnpm",
  args: ["dev"],
});

Press Add service in the Services section of the Devbox, and enter the command that starts your dev server as the Command, for example pnpm dev.

Expose the port

CLI
TS SDK
Dashboard

devbox url expose my-devbox --port 3000 --name web

The CLI prints the devbox.so URL of the service.

const port = await devbox.exposedPorts.create({ name: "web", number: 3000 });
console.log(port.url);

Next Steps

devbox service

Every devbox service subcommand and option.

Blueprints

Define services for every Devbox created from a blueprint.

TS SDK: Run services

Manage services from TypeScript.

Products

Platform

Administration