Run services - Namespace Documentation

Use devbox.services to run long-lived commands, such as development servers, that the Devbox agent supervises. The agent restarts a service according to its restart policy, retains its output, and by default starts it again when the Devbox boots. Use this page to create, inspect, start, stop, and delete services, and to read their logs.

Service operations start a stopped Devbox automatically. Service definitions persist with the Devbox and continue running after the client disconnects.

See Services for an overview of services, including how to manage them from the Devbox CLI.

`services.create()`

Use services.create() to define a supervised command and start it. The agent runs the executable directly, without a shell, so arguments are passed literally. Run sh -c as the command when the service needs pipelines, redirects, or command chaining.

Example

Create a service that runs a development server from the workspace:

const devbox = await client.devboxes.get("sdk-example");
const service = await devbox.services.create({
  name: "web",
  command: "npm",
  args: ["run", "dev"],
  cwd: "app",
});
console.log(service.id, service.process?.state);

API reference

services.create(input: CreateServiceInput, options?: OperationOptions): Promise<Service>

Arguments and options

CreateServiceInput

required

The service definition.

Hide properties

string

required

The service name. It must not be empty or contain only whitespace.

string

required

The executable name or path. It must not be empty. The command is not evaluated by a shell.

readonly string[]

Arguments passed literally to the executable.

string

The working directory. Absolute paths are used as provided. Relative paths resolve from the Devbox workspace directory.

Record<string, string | { secretId: string }>

Environment variable overrides. Each value is either a literal string or a { secretId } object that references a Vault secret, which the Devbox agent resolves when the process starts. Names must start with a letter or underscore and contain only letters, numbers, and underscores. A secret reference must have a non-empty secretId.

string

A description of the service.

boolean

Whether to start the service now. Omit it to follow startPolicy. true starts the service immediately. false creates the service in a durably stopped state, so it does not start until you call services.start().

"on-boot" | "manual"

default:"on-boot"

When the service starts automatically. on-boot starts the service on creation and whenever the Devbox agent boots. manual starts it only when requested.

"never" | "on-failure" | "always"

default:"on-failure"

When the agent restarts the service after its process exits.

boolean

default:"false"

Whether the Devbox stays active instead of shutting down for inactivity while the service process is running.

OperationOptions

Supports signal and timeoutMs. See Handle errors and timeouts.

Invalid input rejects with a TypeError before any request is sent.

Return value

services.create() resolves with the created Service. Its process field reflects the state the agent observed after its initial launch wait. It does not confirm that the process launched successfully or that the application is ready to accept requests. A launch failure is reported in process.state and process.lastExit rather than as a rejection.

More examples

Run a shell command with environment variables

const devbox = await client.devboxes.get("sdk-example");
await devbox.services.create({
  name: "api",
  command: "sh",
  args: ["-c", "npm install && npm start"],
  environment: {
    PORT: "8080",
    API_TOKEN: { secretId: "secret-id" },
  },
  restartPolicy: "always",
});

Create a service without starting it

const devbox = await client.devboxes.get("sdk-example");
await devbox.services.create({
  name: "worker",
  command: "node",
  args: ["worker.js"],
  startPolicy: "manual",
});

`services.get()`

Use services.get() to look up a single service by ID or name.

Example

const devbox = await client.devboxes.get("sdk-example");
const service = await devbox.services.get("web");
console.log(service.process?.state ?? "not started");

API reference

services.get(ref: string, options?: OperationOptions): Promise<Service>

Arguments and options

string

required

The exact service ID, or the name of a user-owned service. IDs are matched before names. The value must not be empty.

OperationOptions

Supports signal and timeoutMs. See Handle errors and timeouts.

Return value

services.get() resolves with the matching Service. It lists the Devbox’s services and selects the match on the client. It rejects with ServiceNotFoundError when no service matches.

`services.list()`

Use services.list() to list the services defined on the Devbox.

Example

const devbox = await client.devboxes.get("sdk-example");
const services = await devbox.services.list();
for (const service of services) {
  console.log(service.name, service.process?.state ?? "not started");
}

API reference

services.list(options?: OperationOptions): Promise<Service[]>

Arguments and options

OperationOptions

Supports signal and timeoutMs. See Handle errors and timeouts.

Return value

services.list() resolves with a Service for each service the Devbox agent reports, including services owned by Namespace. Check owner to distinguish them.

`services.start()`

Use services.start() to start a service, including one that was stopped or created with start: false. It clears the service’s durable stopped state and starts it regardless of its start policy.

Example

const devbox = await client.devboxes.get("sdk-example");
const serviceProcess = await devbox.services.start("web");
console.log(serviceProcess.state, serviceProcess.pid);

API reference

services.start(ref: string, options?: OperationOptions): Promise<ServiceProcess>

Arguments and options

string

required

The service ID or name. The value must not be empty.

OperationOptions

Supports signal and timeoutMs. See Handle errors and timeouts.

Return value

services.start() resolves with the ServiceProcess the agent observed after its initial launch wait. As with services.create(), this does not confirm that the process launched or that the application is ready. It rejects with ServiceNotFoundError when the agent has no matching service.

`services.stop()`

Use services.stop() to stop a service and keep it stopped. The service is durably marked as stopped, so it does not start again automatically, including when the Devbox boots, until you call services.start(). The promise resolves once termination is requested, without waiting for the process to exit.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.services.stop("web");

API reference

services.stop(ref: string, options?: StopServiceOptions): Promise<ServiceProcess | undefined>

Arguments and options

string

required

The service ID or name. The value must not be empty.

StopServiceOptions

Options for stopping the service.

Hide properties

"graceful" | "force"

default:"graceful"

graceful terminates the process in a way that allows it to clean up. force kills it immediately. Any other value rejects with a TypeError.

AbortSignal

Cancels the request when the signal is aborted.

number

The timeout in milliseconds for activating the Devbox, connecting, and sending the stop request.

Return value

services.stop() resolves with the ServiceProcess reported by the agent, or undefined when the response includes no process. The process may still be in the stopping state. Call services.get() to observe when it exits. The method rejects with ServiceNotFoundError when the agent has no matching service.

`services.delete()`

Use services.delete() to permanently remove a service. The agent stops the service gracefully and escalates to forced termination after 15 seconds.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.services.delete("web");

API reference

services.delete(ref: string, options?: OperationOptions): Promise<void>

Arguments and options

string

required

The service ID or name. The value must not be empty.

OperationOptions

Supports signal and timeoutMs. See Handle errors and timeouts.

Return value

services.delete() resolves when the service is removed. It rejects with ServiceNotFoundError when the agent has no matching service. If the agent cannot complete the deletion within 20 seconds, it rejects with a ConnectError whose code is DeadlineExceeded, even when your own timeoutMs has not elapsed.

`services.logs()`

Use services.logs() to stream a service’s output. The iterator first replays the output retained for the service’s latest run, then follows that run’s live output. It does not switch to runs that start later. Automatic restart attempts may share the same run.

Example

const devbox = await client.devboxes.get("sdk-example");
for await (const chunk of devbox.services.logs("web")) {
  process.stdout.write(chunk.stdout);
  process.stderr.write(chunk.stderr);
}

API reference

services.logs(ref: string, options?: OperationOptions): AsyncIterableIterator<ExecutionLogChunk>

Arguments and options

string

required

The exact service ID, or the name of a user-owned service. The value must not be empty.

OperationOptions

Supports signal and timeoutMs. Connecting to the Devbox is bounded by the client’s connectionTimeoutMs instead, and timeoutMs starts once the connection is established.

Return value

services.logs() returns an async iterator of the same ExecutionLogChunk objects as execution.logs(). A chunk with a result is delivered when the run ends. The iterator throws ServiceNotFoundError when no service matches ref, and ServiceLogsNotFoundError when the service has no retained run whose output can be read, for example because it has never started. Each call opens an independent reader. Breaking out of the loop or aborting signal closes only that reader and does not stop the service.

Service types

`Service`

services.create(), services.get(), and services.list() return a Service snapshot of the service’s state as observed from the Devbox agent. It does not update after it is returned.

interface Service {
  id: string;
  name: string;
  command: string;
  args: string[];
  cwd?: string;
  environment: Record<string, string | { secretId: string }>;
  description?: string;
  startPolicy: "on-boot" | "manual" | "on-http-ingress" | "unknown";
  restartPolicy: "never" | "on-failure" | "always" | "unknown";
  preventIdleShutdown: boolean;
  stopped: boolean;
  owner: "user" | "namespace" | "unknown";
  ports: ServicePort[];
  process?: ServiceProcess;
}

string

required

The service ID assigned by the Devbox agent.

string

required

The service name.

string

required

The executable name or path.

string[]

required

The arguments passed to the executable. Empty when the service has no arguments.

string

The configured working directory, either absolute or relative to the Devbox workspace directory.

Record<string, string | { secretId: string }>

required

The configured environment overrides. This is not the complete environment of the running process.

string

The service description, when one is set.

"on-boot" | "manual" | "on-http-ingress" | "unknown"

required

When the service starts automatically. on-http-ingress can be reported for services created outside the TypeScript SDK, but services.create() does not accept it.

"never" | "on-failure" | "always" | "unknown"

required

When the agent restarts the service after its process exits.

boolean

required

Whether the service keeps the Devbox active while its process is running.

boolean

required

Whether automatic starts are durably suppressed by services.stop() or start: false. It does not confirm that the process has exited. Check process.state for that.

"user" | "namespace" | "unknown"

required

Who manages the service. namespace identifies services managed by Namespace rather than created by a user.

ServicePort[]

required

The ports attached to the service. See ServicePort.

ServiceProcess

The state of the service’s process. See ServiceProcess. Absent when the agent reports no process.

`ServiceProcess`

services.start() and services.stop() return a ServiceProcess, and Service.process uses the same type.

interface ServiceProcess {
  state: "starting" | "running" | "stopping" | "stopped" | "failed" | "restarting" | "unknown";
  pid?: number;
  startedAt?: Date;
  restartCount: number;
  lastExit?: {
    exitCode: number;
    error?: string;
    exitedAt?: Date;
  };
}

required

The process state. restarting means the process exited and the agent is waiting to start it again. failed means the agent is no longer restarting it.

number

The process ID, when a process is running.

Date

When the current process started, when the agent reports it.

number

required

The number of automatic restarts since the service was last explicitly started. It is not a lifetime total.

{ exitCode: number; error?: string; exitedAt?: Date }

How the most recent process exited, including agent-reported failure detail in error. While the service is still active, it may describe an earlier attempt.

`ServicePort`

Ports are read-only in the TypeScript SDK. services.create() cannot attach ports to a service. To publish a service’s HTTP port, use devbox.exposedPorts.

interface ServicePort {
  id: string;
  name?: string;
  number: number;
  kind: "port-forward" | "http-ingress" | "unknown";
  owner: "user" | "namespace" | "unknown";
}

string

required

The port ID.

string

The port name, when one is set.

number

required

The port number.

"port-forward" | "http-ingress" | "unknown"

required

How the port is made reachable.

"user" | "namespace" | "unknown"

required

Who manages the port.

Services

Learn how Devbox services work.

Run commands

Run one-off and background commands.

Handle errors and timeouts

Cancel operations and handle SDK failures.

​services.create()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Run a shell command with environment variables

​Create a service without starting it

​services.get()

​Example

​API reference

​Arguments and options

​Return value

​services.list()

​Example

​API reference

​Arguments and options

​Return value

​services.start()

​Example

​API reference

​Arguments and options

​Return value

​services.stop()

​Example

​API reference

​Arguments and options

​Return value

​services.delete()

​Example

​API reference

​Arguments and options

​Return value

​services.logs()

​Example

​API reference

​Arguments and options

​Return value

​Service types

​Service

​ServiceProcess

​ServicePort

​Related documentation

Services

Run commands

Handle errors and timeouts

`services.create()`

Example

API reference

Arguments and options

Return value

More examples

Run a shell command with environment variables

Create a service without starting it

`services.get()`

Example

API reference

Arguments and options

Return value

`services.list()`

Example

API reference

Arguments and options

Return value

`services.start()`

Example

API reference

Arguments and options

Return value

`services.stop()`

Example

API reference

Arguments and options

Return value

`services.delete()`

Example

API reference

Arguments and options

Return value

`services.logs()`

Example

API reference

Arguments and options

Return value

Service types

`Service`

`ServiceProcess`

`ServicePort`

Related documentation