Node API

The devsandboxes npm package: the native devsandbox binary plus a typed, promise-based API over its JSON output. Generated from the package's index.d.ts.

Install

The package ships the devsandbox binary for your platform next to the typed API, so one dependency covers both.

TERMINAL

npm i devsandboxes

Usage

example.ts

import { spawn } from 'node:child_process';
import * as devsandbox from 'devsandboxes';

const { name, worktree } = await devsandbox.run('web', { dir: './sandboxes', stderr: 'inherit' });
const { instances } = await devsandbox.status({ dir: './sandboxes' });
for (const i of instances) console.log(i.name, i.status.state, i.drift);

const { exitCode, stdout } = await devsandbox.exec(name, ['git', 'status']);

// Your own process or pty (node-pty takes the same file/args): a login shell.
const { file, args } = devsandbox.execArgv(name, [], { interactive: true, tty: true });
spawn(file, args, { stdio: 'inherit' });

await devsandbox.rm(name, { deleteBranch: true });

Every function takes { dir, cwd, env, signal, stderr }, except the synchronous binaryPath() and execArgv(), and connect() (below). dir is the config root (-C). A failed command rejects with DevsandboxError (exitCode, stdout, stderr).

At a glance

Function	Resolves to	Description
`binaryPath()`	`string`sync	Absolute path of the native binary for this platform (`DEVSANDBOX_BINARY` overrides)
`cli()`	`CliResult`	Run the CLI with raw arguments
`ls()`	`SandboxRow[]`	Sandbox configs in devsandboxes.toml
`ps()`	`ContainerRow[]`	Running devsandbox containers (`all` includes stopped ones)
`stats()`	`StatsRow[]`	CPU/memory of running devsandbox containers
`status()`	`Snapshot`	Sandboxes, instances, and services in one snapshot
`inspect()`	`T`	The runtime's own inspect document (docker/podman: an array of containers)
`run()`	`RunRecord`	Create and start an instance of `sandbox`
`start()`	`void`	—
`stop()`	`void`	—
`rebuild()`	`void`	Recreate from current config when drifted (`force`: even without drift)
`rename()`	`void`	—
`done()`	`void`	Mark an instance done: kept as is (container, worktree), shown dimmed until removed
`undone()`	`void`	Clear an instance's done mark
`rm()`	`void`	Remove container, worktree, and state entry
`gc()`	`void`	Remove unreferenced services (`force`: also orphaned shell-history files)
`logs()`	`string`	Last `lines` (default 50) lines of a container's merged stdout/stderr
`exec()`	`CliResult`	Run `command` in an instance
`execArgv()`	`ExecInvocation`sync	Argv for running `cmd` in an instance under your own process or pty (node-pty, `child_process.spawn`)
`service.ls()`	`ServiceRow[]`	—
`service.rebuild()`	`void`	Recreate a service's containers and rewire running sandboxes in place
`connect()`	`Api`	Connect to the host daemon through `devsandbox api --stdio`, starting the daemon if needed, and say hello

Functions

Named exports of devsandboxes. Everything but binaryPath() and execArgv() runs the CLI and returns a promise.

binaryPath()function

Absolute path of the native binary for this platform (DEVSANDBOX_BINARY overrides).

function binaryPath(): string

Returnsstring

cli()function

Run the CLI with raw arguments.

function cli(args: readonly string[], opts?: CliOptions): Promise<CliResult>

function cli(
  args: readonly string[],
  opts?: CliOptions,
): Promise<CliResult>

Parameter	Type
`args`	`readonly string[]`
`opts`optional	`CliOptions`

ReturnsPromise<CliResult>

ls()function

Sandbox configs in devsandboxes.toml.

function ls(opts?: CommonOptions): Promise<SandboxRow[]>

function ls(
  opts?: CommonOptions,
): Promise<SandboxRow[]>

Parameter	Type
`opts`optional	`CommonOptions`

ReturnsPromise<SandboxRow[]>

ps()function

Running devsandbox containers (all includes stopped ones).

function ps(opts?: CommonOptions & { all?: boolean }): Promise<ContainerRow[]>

function ps(
  opts?: CommonOptions & { all?: boolean },
): Promise<ContainerRow[]>

Parameter	Type	Description
`opts`optional	`CommonOptions & { all?: boolean }`	Every option of `CommonOptions`, plus:
`opts.all`optional	`boolean`	—

ReturnsPromise<ContainerRow[]>

stats()function

CPU/memory of running devsandbox containers.

function stats(opts?: CommonOptions): Promise<StatsRow[]>

function stats(
  opts?: CommonOptions,
): Promise<StatsRow[]>

Parameter	Type
`opts`optional	`CommonOptions`

ReturnsPromise<StatsRow[]>

status()function

Sandboxes, instances, and services in one snapshot.

function status(opts?: CommonOptions): Promise<Snapshot>

function status(
  opts?: CommonOptions,
): Promise<Snapshot>

Parameter	Type
`opts`optional	`CommonOptions`

ReturnsPromise<Snapshot>

inspect()function

The runtime's own inspect document (docker/podman: an array of containers).

function inspect<T = unknown>(name: string, opts?: CommonOptions): Promise<T>

function inspect<T = unknown>(
  name: string,
  opts?: CommonOptions,
): Promise<T>

Parameter	Type
`name`	`string`
`opts`optional	`CommonOptions`

ReturnsPromise<T>

run()function

Create and start an instance of sandbox; resolves with where it lives.

function run(sandbox: string, opts?: RunOptions): Promise<RunRecord>

function run(
  sandbox: string,
  opts?: RunOptions,
): Promise<RunRecord>

Parameter	Type
`sandbox`	`string`
`opts`optional	`RunOptions`

ReturnsPromise<RunRecord>

start()function

function start(target: Target, opts?: CommonOptions): Promise<void>

function start(
  target: Target,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`target`	`Target`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

stop()function

function stop(target: Target, opts?: CommonOptions): Promise<void>

function stop(
  target: Target,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`target`	`Target`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

rebuild()function

Recreate from current config when drifted (force: even without drift).

function rebuild(
  target: Target,
  opts?: CommonOptions & { force?: boolean },
): Promise<void>

Parameter	Type	Description
`target`	`Target`	—
`opts`optional	`CommonOptions & { force?: boolean }`	Every option of `CommonOptions`, plus:
`opts.force`optional	`boolean`	—

ReturnsPromise<void>

rename()function

function rename(name: string, newName: string, opts?: CommonOptions): Promise<void>

function rename(
  name: string,
  newName: string,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`name`	`string`
`newName`	`string`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

done()function

Mark an instance done: kept as is (container, worktree), shown dimmed until removed.

function done(name: string, opts?: CommonOptions): Promise<void>

function done(
  name: string,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`name`	`string`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

undone()function

Clear an instance's done mark.

function undone(name: string, opts?: CommonOptions): Promise<void>

function undone(
  name: string,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`name`	`string`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

rm()function

Remove container, worktree, and state entry. Rejects, removing nothing, when the worktree has uncommitted or untracked changes, unless force.

function rm(
  name: string,
  opts?: CommonOptions & { /** * The worktree branch `run` created: `true` deletes it (`git branch -D`, * unmerged commits too), `false` or omitted keeps it. Branches `run` * reused are always kept. */ deleteBranch?: boolean; /** * Remove anyway: uncommitted or untracked worktree changes are * discarded, and a failed step (logged on stderr) is skipped so the * instance still leaves state; what failed stays on disk. */ force?: boolean; },
): Promise<void>

Parameter	Type	Description
`name`	`string`	—
`opts`optional	CommonOptions & { /** * The worktree branch `run` created: `true` deletes it (`git branch -D`, * unmerged commits too), `false` or omitted keeps it. Branches `run` * reused are always kept. / deleteBranch?: boolean; /* * Remove anyway: uncommitted or untracked worktree changes are * discarded, and a failed step (logged on stderr) is skipped so the * instance still leaves state; what failed stays on disk. */ force?: boolean; }	Every option of `CommonOptions`, plus:
`opts.deleteBranch`optional	`boolean`	The worktree branch `run` created: `true` deletes it (`git branch -D`, unmerged commits too), `false` or omitted keeps it. Branches `run` reused are always kept.
`opts.force`optional	`boolean`	Remove anyway: uncommitted or untracked worktree changes are discarded, and a failed step (logged on stderr) is skipped so the instance still leaves state; what failed stays on disk.

ReturnsPromise<void>

gc()function

Remove unreferenced services (force: also orphaned shell-history files).

function gc(opts?: CommonOptions & { force?: boolean }): Promise<void>

function gc(
  opts?: CommonOptions & { force?: boolean },
): Promise<void>

Parameter	Type	Description
`opts`optional	`CommonOptions & { force?: boolean }`	Every option of `CommonOptions`, plus:
`opts.force`optional	`boolean`	—

ReturnsPromise<void>

logs()function

Last lines (default 50) lines of a container's merged stdout/stderr.

function logs(
  name: string,
  opts?: CommonOptions & { lines?: number },
): Promise<string>

Parameter	Type	Description
`name`	`string`	—
`opts`optional	`CommonOptions & { lines?: number }`	Every option of `CommonOptions`, plus:
`opts.lines`optional	`number`	—

ReturnsPromise<string>

exec()function

Run command in an instance. Resolves with its exit code rather than rejecting on non-zero.

function exec(
  name: string,
  command: readonly string[],
  opts?: ExecOptions,
): Promise<CliResult>

Parameter	Type
`name`	`string`
`command`	`readonly string[]`
`opts`optional	`ExecOptions`

ReturnsPromise<CliResult>

execArgv()function

Argv for running cmd in an instance under your own process or pty (node-pty, child_process.spawn). Without cmd, a login shell (zsh, bash, or sh). With neither flag set the CLI picks: -i, plus -t when its stdin is a TTY (as under a pty); setting either passes exactly what you set, so set both for an interactive shell.

function execArgv(
  name: string,
  cmd?: readonly string[],
  opts?: ExecArgvOptions,
): ExecInvocation

Parameter	Type
`name`	`string`
`cmd`optional	`readonly string[]`
`opts`optional	`ExecArgvOptions`

ReturnsExecInvocation

connect()function

Connect to the host daemon through devsandbox api --stdio, starting the daemon if needed, and say hello. Rejects with DevsandboxApiError: unsupported on Windows (the daemon is unix only), protocol when the daemon speaks another protocol, closed when the relay exits first.

function connect(opts?: ConnectOptions): Promise<Api>

function connect(
  opts?: ConnectOptions,
): Promise<Api>

Parameter	Type
`opts`optional	`ConnectOptions`

ReturnsPromise<Api>

`service`

Methods of the exported service object: devsandbox.service.ls().

service.ls()method

ls(opts?: CommonOptions): Promise<ServiceRow[]>

ls(
  opts?: CommonOptions,
): Promise<ServiceRow[]>

Parameter	Type
`opts`optional	`CommonOptions`

ReturnsPromise<ServiceRow[]>

service.rebuild()method

Recreate a service's containers and rewire running sandboxes in place.

rebuild(name: string, opts?: CommonOptions): Promise<void>

rebuild(
  name: string,
  opts?: CommonOptions,
): Promise<void>

Parameter	Type
`name`	`string`
`opts`optional	`CommonOptions`

ReturnsPromise<void>

Types

Payloads mirror the CLI's --json output field for field: names stay snake_case and a Rust Option<T> arrives asT | null.

Payloads

ContainerStatustype

Container liveness; text is the runtime's raw status (e.g. "Up 3 minutes"). unknown: the runtime wasn't asked (instances.list with depth: 'disk'); never in status().

type ContainerStatus =
  | { state: 'running'; text: string }
  | { state: 'exited'; text: string }
  | { state: 'missing' }
  | { state: 'unknown' };

Used byInstanceRow ServiceRow

PhaseRowtype

Where an instance's creation stands while it isn't ready. step is preparing, building, creating or a lifecycle step's name (postCreateCommand, …); a failed one is kept until rebuild retries it or rm removes it (error is interrupted when its process died).

type PhaseRow =
  | { state: 'in-flight'; step: string }
  | { state: 'failed'; step: string; error: string };

Used byInstanceRow ContainerRow

InstanceRowinterface

One instance (status().instances).

Property	Type	Description
`name`	`string`	—
`sandbox`	`string`	—
`container`	`string`	—
`status`	`ContainerStatus`	—
`uptime_secs`	`number`	—
`cpu`	`string \| null`	—
`mem`	`string \| null`	—
`folder`	`string`	—
`worktree`	`boolean`	—
`services`	`string[]`	—
`workspace`	`string`	—
`remote_user`	`string \| null`	—
`remote_env_len`	`number`	—
`base_folder`	`string`	—
`drift`	`boolean`	Container no longer matches the current config/dockerfile; `rebuild` recreates it.
`done`	`boolean`	Marked done (`done()`); kept as is until removed.
`phase`optional	`PhaseRow`	Still being created, or failed; absent once ready. Shown instead of `status` while set.
`root`	`string \| null`	The config root it was made from; `null` for instances older than that record.
`machine`optional	`string`	The machine it's on, in a federated snapshot (`instances.watch` with `machines`); absent for this host's.

Used bySnapshot

SandboxRowinterface

One [sandbox.*] from devsandboxes.toml (ls(), status().sandboxes).

Property	Type	Description
`name`	`string`	—
`source`	`string`	`image X`, `dockerfile Y`, or `?` when the sandbox failed to resolve.
`folder`	`string \| null`	—
`services`	`string[]`	—
`extends`	`string[]`	`extends` template chain.
`config_hash`	`string`	—
`build_hash`	`string`	—
`issues`	`string[]`	Config-validation problems (folder / mount resolution).
`dispatcher`	`boolean`	Has a `dispatcher` table (docs/architecture/automations/dispatchers.md).
`worktree_branch`	`string \| null`	The resolved `worktree-branch`; `null` when unset or unresolved.
`root`	`string \| null`	The config root it was read from.
`machine`optional	`string`	As `InstanceRow.machine`.

Used bySnapshot ls()

ServiceRowinterface

One [services.*] from devsandboxes.toml (service.ls(), status().services).

Property	Type	Description
`name`	`string`	—
`scope`	`'global' \| 'isolated'`	—
`source`	`string`	—
`ports`	`string[]`	—
`containers`	`Array<[string, ContainerStatus]>`	Backing containers as `[containerName, status]` pairs.
`used_by`	`string[]`	Instances whose sandbox references this service.
`env_len`	`number`	—
`command`	`string \| null`	—
`config_hash`	`string`	—
`drift`	`boolean`	—
`root`	`string \| null`	The config root it was read from.
`machine`optional	`string`	As `InstanceRow.machine`.

Used bySnapshot service.ls()

Snapshotinterface

Full snapshot (status()), the same data the TUI renders.

Property	Type	Description
`instances`	`InstanceRow[]`	—
`sandboxes`	`SandboxRow[]`	—
`services`	`ServiceRow[]`	—
`sandbox_count`	`number`	—
`runtime_name`	`'docker' \| 'podman' \| 'container'`	—
`runtime_version`	`string \| null`	—
`error`	`string \| null`	Collection problem (e.g. runtime down); rows still come from local state.

Used byInstancesList status()

SnapshotDepthtype

How much of the runtime instances.list asks: full (the default) adds cpu/mem.

type SnapshotDepth = 'disk' | 'listing' | 'full';

Used byApiMethods

InstancesListinterface

instances.list: the Snapshot plus the dispatchers' children.

ExtendsSnapshotinherits instances sandboxes services sandbox_count runtime_name runtime_version error

Property	Type	Description
`thread_children`	`Record<string, Record<string, string>>`	Dispatcher `instance_id` → thread key → child instance name.

Used byInstancesSnapshot ApiMethods ApiInstances

InstancesSnapshotinterface

instances.snapshot: a watched root's InstancesList, pushed on every poll (about every 2 s; cpu/mem refreshed at most every 7 s and carried over in between), so its arrival says how fresh it is.

ExtendsInstancesListinherits thread_children instances sandboxes services sandbox_count runtime_name runtime_version error

Property	Type	Description
`dir`	`string`	The config root, as `instances.watch` named it.
`machines`optional	`SnapshotMachine[]`	With `instances.watch`'s `machines`: every registered machine, sorted by name. The rows then include each machine's (tagged `machine`), last known while it isn't `connected`.

Used byApiEvents

LinkStatetype

Where a machine's link stands. idle: not wanted, so not connected.

type LinkState = 'idle' | 'connecting' | 'connected' | 'unreachable';

Used bySnapshotMachine MachineRow

SnapshotMachineinterface

One machine of a federated InstancesSnapshot.

Property	Type	Description
`name`	`string`	—
`target`	`string`	What ssh takes, or an `ssh://` URL.
`state`	`LinkState`	—
`error`	`string \| null`	Why it's `unreachable` (or a root it refused).
`version`	`string \| null`	Its devsandbox semver, once reached.
`runtime`	`string \| null`	Its runtime (`runtime_name`), once a snapshot came.
`command`	`string \| null`	The remote devsandbox as shell text; `null` is `devsandbox` on its `PATH` (for an ssh argv).
`agent`	`boolean`	This host's ssh-agent is relayed to it (`machines.set`).

Used byInstancesSnapshot

RunRecordinterface

The instance run() just created (run --json). Fields match InstanceRow where they overlap, except worktree, which is the path.

Property	Type	Description
`name`	`string`	Instance name; what every `name` argument accepts.
`instance_id`	`string`	Persistent id; differs from `name` after a rename.
`sandbox`	`string`	—
`container`	`string`	—
`workspace`	`string`	Workspace folder inside the container.
`folder`	`string`	Host folder mounted as the workspace (the worktree for a worktree instance).
`base_folder`	`string`	Host base repo folder the instance derives from.
`worktree`	`string \| null`	Host worktree path; `null` when the instance runs on `base_folder`.
`branch`	`string \| null`	Worktree branch; `null` without a worktree.

Used byrun() VerbDetached

ContainerRowinterface

One container from the runtime listing (ps()).

Property	Type	Description
`name`	`string`	—
`image`	`string`	—
`status`	`string`	Human status (`Up 3 minutes`, `Exited (0) 1 hour ago`, …).
`state`	`string`	`running`, or anything else (stopped/exited/created…).
`labels`	`Record<string, string>`	—
`host_ports`	`string[]`	—
`done`	`boolean`	The container's instance is marked done (`false` for service containers).
`phase`optional	`PhaseRow`	The container's instance is still being created, or failed; absent once ready.

Used byps()

StatsRowinterface

Resource usage of one running container (stats()), pre-rendered.

Property	Type
`name`	`string`
`cpu`	`string`
`mem`	`string`

Used bystats()

Options & results

CommonOptionsinterface

Property	Type	Description
`dir`optional	`string`	Config root containing devsandboxes.toml (the CLI's `-C`). Defaults to `cwd`.
`cwd`optional	`string`	—
`env`optional	`NodeJS.ProcessEnv`	—
`signal`optional	`AbortSignal`	—
`stderr`optional	`'pipe' \| 'inherit'`	`inherit` streams the CLI's progress output to this process's stderr. Default `pipe`.

Used byCliOptions ls() ps() stats() status() inspect() RunOptions start() stop() rebuild() rename() done() undone() rm() gc() logs() ExecOptions service.ls() service.rebuild()

CliOptionsinterface

ExtendsCommonOptionsinherits dir cwd env signal stderr

Property	Type	Description
`input`optional	`string \| Buffer`	Written to the process's stdin; stdin is closed otherwise.
`reject`optional	`boolean`	Reject with `DevsandboxError` on a non-zero exit. Default `true`.

Used bycli()

CliResultinterface

Property	Type	Description
`exitCode`	`number \| null`	—
`signal`	`NodeJS.Signals \| null`	—
`stdout`	`string`	—
`stderr`	`string`	Empty when `stderr: 'inherit'`.

Used bycli() exec()

Targettype

An instance name (or sandbox / folder name), or every instance.

type Target = string | { all: true };

Used bystart() stop() rebuild()

API

RunOptionsinterface

ExtendsCommonOptionsinherits dir cwd env signal stderr

Property	Type	Description
`name`optional	`string`	Instance name; generated when omitted.
`branch`optional	`string`	Worktree branch (supports `${instance}`).
`base`optional	`string`	Start point for the worktree branch, e.g. `origin/develop`.

Used byrun()

ExecOptionsinterface

ExtendsCommonOptionsinherits dir cwd env signal stderr

Property	Type	Description
`input`optional	`string \| Buffer`	Piped to the command's stdin (passes `-i`).

Used byexec()

ExecArgvOptionsinterface

Property	Type	Description
`tty`optional	`boolean`	Pass `-t` (allocate a pseudo-TTY).
`interactive`optional	`boolean`	Pass `-i` (keep stdin open).

Used byexecArgv()

ExecInvocationinterface

A spawnable devsandbox exec invocation: spawn(file, args), no shell quoting.

Property	Type	Description
`file`	`string`	The native binary, as `binaryPath()` returns it.
`args`	`string[]`	—

Used byexecArgv()

Daemon API

HelloParamsinterface

hello params: what connect() sends first.

Property	Type	Description
`version`	`string`	The client's devsandbox version; `connect()` sends `0.0.0` (the relay already handled any version handoff).
`build`	`number`	Unix mtime of a dev build; 0 otherwise.
`client`	`string`	Who's calling (`npm:<name>`), for `serve.log`.

HelloResultinterface

The daemon's answer to hello (api.daemon).

Property	Type	Description
`version`	`string`	—
`build`	`number`	—
`protocol`	`number`	The API protocol number; see `PROTOCOL`.
`handoff`optional	`boolean`	The client is newer: the daemon is exiting.

Used byApi

ApiErrorBodyinterface

An error response's body: code is stable, message is for humans.

Property	Type	Description
`code`	`string`	—
`message`	`string`	—
`data`optional	`unknown`	Details some codes carry: `VerbFailedData` for `failed`.

OkResultinterface

What a mutation answers.

Property	Type
`ok`	`true`

Used byApiMethods

ThreadStatetype

A thread state; needs-you is waiting on the user.

type ThreadState = 'needs-you' | 'active' | 'done';

Used byThreadSummary

InboxViewtype

An inbox.threads.list view, as in the dashboard.

type InboxView = 'needs-you' | 'active' | 'done' | 'all';

Used byApiMethods ApiInbox

ApiTopictype

A notification topic for subscribe.

type ApiTopic = 'inbox' | 'instances' | 'forwards';

Used byApiMethods Api

ThreadSummaryinterface

One Inbox thread (inbox.list()), and the head of ThreadDetail.

Property	Type	Description
`id`	`number`	Store id, stable for the thread's life: what `{ thread: id }` takes.
`owner`	`string`	Owner's `instance_id`.
`owner_name`	`string`	Owner's instance name when it last wrote.
`key`	`string \| null`	Thread key; `null` on an unkeyed notification.
`kind`	`'thread' \| 'notify'`	`thread` (`devsbd thread put`) or `notify` (`devsbd notify` records).
`state`	`ThreadState \| null`	`null` on a notification.
`status`	`string \| null`	The owner's status line.
`title`	`string`	A thread's title; a notification's newest message, first line.
`level`	`'info' \| 'warn' \| 'error' \| null`	A notification's newest level.
`unread`	`boolean`	—
`archived`	`boolean`	The owner was removed: read-only history.
`needs_you`	`boolean`	In the `needs-you` view (what badges count).
`changed_at`	`number`	Unix seconds of the last change.

Used byThreadDetail ApiMethods ApiInbox

ThreadDetailinterface

A thread with everything the dashboard's pane shows (inbox.get()).

ExtendsThreadSummaryinherits id owner owner_name key kind state status title level unread archived needs_you changed_at

Property	Type	Description
`link`	`string \| null`	`http(s)` link.
`child`	`string \| null`	The key, among the owner's dispatcher children, of the child it's about; `null`: the owner itself.
`compose`	`ThreadCompose \| null`	Set when the thread takes replies (`inbox.reply()`).
`actions`	`ThreadAction[]`	—
`feed`	`FeedItem[]`	An owner thread's feed, oldest first (first-insert order).
`notes`	`ThreadNote[]`	A notification's records, newest first.
`events_pending`	`number`	Events the owner hasn't acked yet.

Used byApiMethods ApiInbox

ThreadComposeinterface

How a thread takes free-text replies.

Property	Type	Description
`placeholder`	`string \| null`	—
`hint`	`string \| null`	What sending does now, shown under the box.

Used byThreadDetail

ThreadActioninterface

An owner's action button (inbox.act()).

Property	Type	Description
`id`	`string`	—
`label`	`string`	—
`done`	`boolean`	Pressing it also sets the thread done.
`host`	`'vscode' \| 'terminal' \| 'logs' \| 'forward' \| 'open' \| 'rm' \| null`	The host verb it runs in the client that shows it; the API runs none.
`sends_event`	`boolean`	`false`: host-only, which `inbox.act()` refuses.

Used byThreadDetail

FeedItemtype

One item of a thread's feed, by type.

type FeedItem = FeedMessage | FeedReply | FeedAction | FeedSubmission | FeedMarker;

Used byThreadDetail

FeedItemBaseinterface

What every feed item carries.

Property	Type	Description
`seq`	`number`	Arrival order across the whole Inbox.
`at`	`number`	Unix seconds of first insert.

Used byFeedMessage FeedReply FeedAction FeedSubmission FeedMarker

FeedMessageinterface

A message from the thread's owner.

ExtendsFeedItemBaseinherits seq at

Property	Type	Description
`type`	`'message'`	—
`id`	`string`	The owner's id for it, unique in the thread.
`blocks`	`MessageBlock[]`	—
`edited`	`boolean`	Replaced in place since it was first sent.
`withdrawn`	`boolean`	The owner took it back.

Used byFeedItem

FeedReplyinterface

The user's reply (inbox.reply()).

ExtendsFeedItemBaseinherits seq at

Property	Type
`type`	`'reply'`
`text`	`string`

Used byFeedItem

FeedActioninterface

The user pressed an action (inbox.act()).

ExtendsFeedItemBaseinherits seq at

Property	Type	Description
`type`	`'action'`	—
`action`	`string`	The action's id.
`label`	`string`	Its label when pressed.

Used byFeedItem

FeedSubmissioninterface

The user submitted a form (inbox.form.submit).

ExtendsFeedItemBaseinherits seq at

Property	Type	Description
`type`	`'submission'`	—
`message`	`string`	The message holding the form.
`form`	`string`	The form's id.
`answers`	`Record<string, FormAnswer \| null>`	Every question's answer; `null` for an optional one left unanswered, or a follow-up that doesn't apply.

Used byFeedItem

FeedMarkerinterface

A one-line marker: the user's done/reopen, the owner's state or status change.

ExtendsFeedItemBaseinherits seq at

Property	Type	Description
`type`	`'marker'`	—
`marker`	`'done' \| 'reopen' \| 'state' \| 'status'`	—
`from`	`string \| null`	`state`/`status`: the value before; `null` otherwise (or no status).
`to`	`string \| null`	`state`/`status`: the value after; `null` otherwise (or no status).

Used byFeedItem

MessageBlocktype

One block of a message, by type.

type MessageBlock = MarkdownBlock | FieldsBlock | FormBlock;

Used byFeedMessage

MarkdownBlockinterface

Markdown text.

Property	Type
`type`	`'markdown'`
`text`	`string`

Used byMessageBlock

FieldsBlockinterface

A compact key/value list, shown as aligned label value rows.

Property	Type
`type`	`'fields'`
`items`	`MessageField[]`

Used byMessageBlock

MessageFieldinterface

One row of a fields block.

Property	Type
`label`	`string`
`value`	`string`

Used byFieldsBlock

FormBlockinterface

Questions for the user, answered once (inbox.form.submit). A submitted form is frozen: re-sends of its message never change it.

Property	Type	Description
`type`	`'form'`	—
`id`	`string`	—
`title`	`string \| null`	—
`submit`	`string`	The submit button's label.
`questions`	`FormQuestion[]`	—
`state`	`'open' \| 'submitted' \| 'withdrawn'`	`withdrawn`: the owner withdrew the message or dropped the form.
`draft`	`Record<string, FormAnswer>`	Saved partial answers (`inbox.form.saveDraft`) of an open form; `{}` otherwise.
`answers`	`Record<string, FormAnswer \| null> \| null`	Once submitted, every question's answer (`null`: optional and unanswered, or a follow-up that doesn't apply); `null` before.

Used byMessageBlock

FormQuestiontype

One question of a form, by type.

type FormQuestion = ChoiceQuestion | TextQuestion | ConfirmQuestion;

Used byFormBlock

FormAnswertype

An answer: an option id (choice), option ids (multiple choice), text, or a confirm's yes/no.

type FormAnswer = string | string[] | boolean;

Used byFeedSubmission FormBlock FormParams

QuestionBaseinterface

What every question carries.

Property	Type	Description
`id`	`string`	Unique in the form; what answers are keyed by.
`label`	`string`	Inline markdown, one line.
`context`	`string \| null`	Markdown shown above the input.
`required`	`boolean`	Must be answered to submit (text: not blank; `multiple`: one pick at least).
`under`	`string \| null`	A follow-up of this earlier question, shown under it; `null`: top-level.
`when`	`string \| null`	With `under` a choice: the option this follow-up is for. It applies only while that option is picked (else hidden, never required, answered `null`).

Used byChoiceQuestion TextQuestion ConfirmQuestion

ChoiceQuestioninterface

Pick one option, or several when multiple.

ExtendsQuestionBaseinherits id label context required under when

Property	Type	Description
`type`	`'choice'`	—
`options`	`ChoiceOption[]`	—
`multiple`	`boolean`	—
`default`	`string \| string[] \| null`	An option id, or ids when `multiple`.

Used byFormQuestion

ChoiceOptioninterface

One option of a choice question.

Property	Type
`id`	`string`
`label`	`string`
`description`	`string \| null`

Used byChoiceQuestion

TextQuestioninterface

Free text.

ExtendsQuestionBaseinherits id label context required under when

Property	Type	Description
`type`	`'text'`	—
`placeholder`	`string \| null`	—
`default`	`string \| null`	Prefilled, editable.
`multiline`	`boolean`	—
`max`	`number`	Longest answer, in bytes.

Used byFormQuestion

ConfirmQuestioninterface

Yes or no.

ExtendsQuestionBaseinherits id label context required under when

Property	Type	Description
`type`	`'confirm'`	—
`yes`	`string \| null`	Label of the yes choice; `null`: the client's own.
`no`	`string \| null`	Label of the no choice; `null`: the client's own.
`default`	`boolean \| null`	—

Used byFormQuestion

FormParamstype

inbox.form.* params: the message holding the form, and answers by question id.

type FormParams = ThreadAddress & { message: string; answers?: Record<string, FormAnswer> };

Used byApiMethods

ThreadNoteinterface

One record of a notification thread.

Property	Type	Description
`id`	`number`	—
`level`	`'info' \| 'warn' \| 'error'`	—
`msg`	`string`	—
`link`	`string \| null`	—
`at`	`number`	Unix seconds.

Used byThreadDetail

ThreadAddresstype

A thread by store id, or an owner thread by owner (instance name or id) and key.

type ThreadAddress = { thread: number } | { owner: string; key: string };

Used byFormParams ApiMethods ApiInbox

NotifyTargettype

One notification thread by store id, or every one.

type NotifyTarget = { thread: number } | { all: true };

Used byApiMethods ApiInbox

ForwardRowinterface

One daemon port forward (forwards.list()).

Property	Type	Description
`id`	`number`	Daemon-wide id: what `forwards.rm()` takes.
`dir`	`string`	The canonical config root; with `machine`, the root on that machine.
`local`	`string`	The bound host address, e.g. `127.0.0.1:3000`.
`target`	`string`	Route label, e.g. `api:3000`; empty until the route first resolves. A remote forward's is `<machine>/<label>`, best effort until the machine first answers.
`process`	`string \| null`	The listening process (`node (pid 412)`).
`state`	`string`	`active`, `connecting`, or `error: <reason>`.
`conns`	`number`	Open connections.
`configured`	`boolean`	From a sandbox's `forwardPorts`, not `forwards.add()`.
`machine`optional	`string`	The machine whose instance or service it reaches (`forwards.add()` with `machine`); absent for this host's.

Used byApiMethods ApiForwards

ForwardAddParamsinterface

forwards.add() params; instance, service, or both.

Property	Type	Description
`dir`	`string`	Config root (the CLI's `-C`); resolved against `process.cwd()`. With `machine`, the absolute root on that machine.
`instance`optional	`string`	Instance name, as the CLI takes it (never prompts).
`service`optional	`string`	Forward one of its services instead.
`address`optional	`string`	Host address to bind. Default `127.0.0.1`.
`spec`	`string`	`port` (that host port or the next free one up) or `host:port` (exactly).
`machine`optional	`string`	A registered machine's instance or service (then `dir` is its config root there and `instance` its name there); the forward still binds on this host.

Used byApiMethods ApiForwards

ForwardAddedinterface

A forward forwards.add() bound.

Property	Type	Description
`id`	`number`	—
`local`	`string`	—
`target`	`string`	Route label, best effort this early.

Used byApiMethods ApiForwards

InstancesResolvedinterface

instances.resolve's answer: every instance the name could mean, sorted (several: the caller picks).

Property	Type	Description
`matches`	`string[]`	With `machines`: a machine's matches qualified, `<machine>/<name>`.
`found`optional	`ResolvedInstance[]`	`matches` in order, with where each lives (absent from older daemons).

Used byApiMethods

ResolvedInstanceinterface

One InstancesResolved match.

Property	Type	Description
`name`	`string`	Its name on its own host (unqualified).
`machine`	`string \| null`	`null`: this host.
`root`	`string \| null`	Its config root on its host; `null` when not recorded.

Used byInstancesResolved

InstanceCancelledinterface

instances.cancel's answer: the in-flight verb's pid was SIGINTed.

Property	Type
`ok`	`true`
`pid`	`number`

Used byApiMethods

InstanceRenamedinterface

instances.rename's answer: the new (trimmed) name.

Property	Type
`instance`	`string`

Used byApiMethods

InstanceDoneinterface

instances.done's answer: the instance's done flag as it now is.

Property	Type
`instance`	`string`
`done`	`boolean`

Used byApiMethods

SandboxEntryinterface

One sandboxes.list entry (not the snapshot's SandboxRow).

Property	Type	Description
`name`	`string`	—
`machine`optional	`string`	With `sandboxes.list`'s `machines`: the machine defining it; absent for this host's.
`root`optional	`string`	The config root defining it: always in `sandboxes.list`, absent in `roots.list`.

Used byRootCandidate ApiMethods

RootCandidateinterface

One roots.list entry: a config root this host knows of.

Property	Type	Description
`root`	`string`	Absolute, canonicalized (a root that's gone: as recorded).
`sandboxes`	`SandboxEntry[]`	Sorted; `[]` when `error` is set or there's no config file.
`error`	`string \| null`	Why the root's sandboxes can't be read (gone, a config that doesn't load).

Used byMachineProbe ApiMethods

MachineProbeinterface

machines.probe's answer: the machine's devsandbox and its candidate roots.

Property	Type
`version`	`string`
`protocol`	`number`
`roots`	`RootCandidate[]`

Used byApiMethods

MachineAddedinterface

machines.add's answer.

Property	Type	Description
`name`	`string`	—
`roots`	`string[]`	As saved: the machine's canonical paths, deduplicated.
`version`	`string`	The machine's devsandbox semver.
`warning`	`string \| null`	Set when that semver differs from this daemon's.

Used byApiMethods

MachineInfointerface

machines.get's answer: what an ssh command to the machine needs.

Property	Type	Description
`name`	`string`	—
`target`	`string`	What ssh takes, or an `ssh://` URL.
`command`	`string \| null`	The remote devsandbox as shell text; `null` is `devsandbox` on its `PATH`.
`roots`	`string[]`	Config roots on the machine.
`agent`	`boolean`	This host's ssh-agent is relayed to it (`machines.set`).

Used byApiMethods

MachineHeldinterface

machines.hold's answer.

Property	Type	Description
`ok`	`true`	—
`agent`	`boolean`	The machine's agent relay is up; always `false` for a machine with `agent` off.

Used byApiMethods

MachineRowinterface

One registered machine (machines.list).

Property	Type	Description
`name`	`string`	—
`target`	`string`	What ssh takes, or an `ssh://` URL.
`roots`	`string[]`	Config roots on the machine.
`command`	`string \| null`	The remote devsandbox as shell text; `null` is `devsandbox` on its `PATH`.
`agent`	`boolean`	This host's ssh-agent is relayed to it (`machines.set`).
`state`	`LinkState`	—
`error`	`string \| null`	Why it's `unreachable` (or a root it refused).
`version`	`string \| null`	The machine's devsandbox semver, once reached.

Used byApiMethods

ProcessRowinterface

One process of an instance, as ps printed it.

Property	Type
`pid`	`string`
`ppid`	`string`
`args`	`string`

Used byProcsListing

RunRowinterface

One tracked run of an instance's helper (devsbd run ls).

Property	Type	Description
`id`	`string`	—
`state`	`string`	`running`, `lost`, or with its code: `exited 4`, `killed 9`.
`started`	`string`	RFC 3339.
`argv`	`string`	The command, space-joined.

Used byProcsListing

ProcsListinginterface

A running instance's processes and runs (instances.procs).

Property	Type	Description
`processes`	`ProcessRow[]`	—
`signalable`	`boolean`	The pids are the container's own, so the process can be signalled; false for the runtime's host-side `top` fallback.
`runs`	`RunRow[]`	Oldest first; `[]` without a helper that tracks runs.

Used byInstanceProcs

ProcsErrorinterface

Why an instance has no listing: no such instance, not running, or the listing failed.

Property	Type
`error`	`string`

Used byInstanceProcs

InstanceProcstype

One instance's instances.procs entry.

type InstanceProcs = ProcsListing | ProcsError;

Used byApiMethods

BuildLogTailinterface

instances.buildLog's answer: the end of the instance's build log.

Property	Type	Description
`text`	`string`	—
`cut`	`boolean`	Earlier lines were left out.

Used byApiMethods

ContainerLogsinterface

containers.logs's answer: the container's last output lines.

Property	Type
`text`	`string`

Used byApiMethods

SandboxConfiginterface

sandboxes.get's answer: the sandbox's config as TOML text.

Property	Type	Description
`original`	`string`	The table as written, `extends` included.
`resolved`	`string`	Merged with what it `extends`, or why it doesn't merge.
`hash`	`string`	The merged table's config hash; empty when it doesn't merge.

Used byApiMethods

ServiceConfiginterface

services.get's answer: the service's table as TOML text (services don't extends).

Property	Type
`original`	`string`

Used byApiMethods

ForwardRemovedinterface

What forwards.rm() stopped.

Property	Type	Description
`ok`	`true`	—
`local`	`string`	—
`configured`	`boolean`	A configured forward stays stopped until its owner runs again.

Used byApiMethods ApiForwards

InboxChangedinterface

inbox.changed params: the store changed, re-fetch.

Property	Type	Description
`generation`	`number`	Grows per change this daemon saw; compare within one connection only.

Used byApiEvents

InboxShowninterface

inbox.shown params: a container message worth a status line.

Property	Type	Description
`instance`	`string`	—
`line`	`string`	The dashboard's status-line text.

Used byApiEvents

ForwardsStatusinterface

forwards.status params: a one-line forward status.

Property	Type
`line`	`string`

Used byApiEvents

VerbParamsinterface

What every verb (run, rebuild, start, stop, rm, services.rebuild) takes: the config root and the env the verb runs with (the caller's whole env, never the daemon's).

Property	Type	Description
`root`	`string`	Absolute config root (the CLI's `-C`); with `machine`, a path on that machine.
`env`	`Record<string, string>`	—
`machine`optional	`string`	Run it on that machine (a fresh ssh); answered as it answers there. A hang-up cancels it there unless `detach`, and so does this daemon exiting.

Used byRunParams RebuildParams StartParams StopParams RmParams ServicesRebuildParams

TtySizeinterface

A terminal's size in cells.

Property	Type
`cols`	`number`
`rows`	`number`

Used byRunParams RebuildParams StartParams