Class Devbox

Object-oriented interface for working with Devboxes.

Remarks

Overview

The Devbox class provides a high-level, object-oriented API for managing devboxes. Devboxes are containers that run your code in a consistent environment. They have the the following categories of operations:

net - Network operations
cmd - Command execution operations
file - File operations

Quickstart

import { RunloopSDK } from '@runloop/api-client-ts';

const runloop = new RunloopSDK();
const devbox = await runloop.devbox.create({ name: 'my-devbox' });
devbox.cmd.exec('echo "Hello, World!"');
...

Index

Properties

net cmd file

Accessors

Methods

shell getInfo getTunnel getTunnelUrl logs awaitRunning awaitSuspended snapshotDisk snapshotDiskAsync shutdown suspend resume resumeAsync keepAlive onEvict cancelOnEvict

Properties

`Readonly`net

net: DevboxNetOps

Network operations on the devbox.

`Readonly`cmd

cmd: DevboxCmdOps

Command execution operations on the devbox.

`Readonly`file

file: DevboxFileOps

File operations on the devbox.

Accessors

id

get id(): string
Get the devbox ID.

Returns string
The devbox ID
- Defined in src/sdk/devbox.ts:692

Methods

shell

shell(shellName?: string): DevboxNamedShell
Create a named shell instance for stateful command execution.

Named shells are stateful and maintain environment variables and the current working directory (CWD) across commands, just like a real shell on your local computer. Commands executed through the same named shell instance will execute sequentially - the shell can only run one command at a time with automatic queuing. This ensures that environment changes and directory changes from one command are preserved for the next command.
Parameters
- OptionalshellName: string = ...
  The name of the persistent shell session. If not provided, a UUID will be generated automatically.
Returns DevboxNamedShell
A DevboxNamedShell instance for executing commands in the named shell
Example
```
// Create a named shell with a custom name
const shell = devbox.shell('my-session');

// Create a named shell with an auto-generated UUID name
const shell2 = devbox.shell();

// Commands execute sequentially and share state
await shell.exec('cd /app');
await shell.exec('export MY_VAR=value');
await shell.exec('echo $MY_VAR'); // Will output 'value' because env is preserved
await shell.exec('pwd'); // Will output '/app' because CWD is preserved
```
- Defined in src/sdk/devbox.ts:723

getInfo

getInfo(options?: RequestOptions<unknown>): Promise<DevboxView>
Get the complete devbox data from the API.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<DevboxView>
The devbox data
Example
```
const info = await devbox.getInfo();
console.log(`Devbox name: ${info.name}, status: ${info.status}`);
```
- Defined in src/sdk/devbox.ts:797

getTunnel

getTunnel(options?: RequestOptions<unknown>): Promise<TunnelView | null>
Get the tunnel information for this devbox. Returns null if no tunnel has been enabled.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<TunnelView | null>
The tunnel information, or null if no tunnel exists
Example
```
const tunnel = await devbox.getTunnel();
if (tunnel) {
  console.log(`Tunnel key: ${tunnel.tunnel_key}`);
}
```
- Defined in src/sdk/devbox.ts:816

getTunnelUrl

getTunnelUrl(port: number, options?: RequestOptions<unknown>): Promise<string>
Get the tunnel URL for a specific port. Throws an error if no tunnel has been enabled.
Parameters
- port: number
  The port number to construct the URL for
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<string>
The tunnel URL for the specified port
Example
```
const url = await devbox.getTunnelUrl(8080);
console.log(`Access your app at: ${url}`);
// Output: https://8080-abc123xyz.tunnel.runloop.ai
```
Throws
If no tunnel has been enabled for this devbox
- Defined in src/sdk/devbox.ts:837

logs

logs(
params?: LogListParams,
options?: RequestOptions<unknown>,
): Promise<DevboxLogsListView>
Get all logs from a running or completed devbox. Optionally filter by execution ID or shell name.
Parameters
- Optionalparams: LogListParams
  Optional filter parameters (execution_id, shell_name)
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<DevboxLogsListView>
The devbox logs
Example
```
const logs = await devbox.logs();
for (const log of logs.logs) {
  console.log(`[${log.level}] ${log.message}`);
}

// Filter by execution ID
const execLogs = await devbox.logs({ execution_id: 'exec-123' });

// Filter by shell name
const shellLogs = await devbox.logs({ shell_name: 'my-shell' });
```
- Defined in src/sdk/devbox.ts:869

awaitRunning

awaitRunning(options?: LongPollRequestOptions<DevboxView>): Promise<DevboxView>
Wait for the devbox to reach the running state. Uses optimized server-side polling for better performance.
Parameters
- Optionaloptions: LongPollRequestOptions<DevboxView>
  Request options with optional long-poll configuration
Returns Promise<DevboxView>
The devbox data when running state is reached
Example
```
const devbox = Devbox.fromId(runloop, 'devbox-123');
await devbox.awaitRunning();
console.log('Devbox is now running');
```
- Defined in src/sdk/devbox.ts:887

awaitSuspended

awaitSuspended(
options?: LongPollRequestOptions<DevboxView>,
): Promise<DevboxView>
Wait for the devbox to reach the suspended state. Uses optimized server-side polling for better performance.
Parameters
- Optionaloptions: LongPollRequestOptions<DevboxView>
  Request options with optional long-poll configuration
Returns Promise<DevboxView>
The devbox data when suspended state is reached
Example
```
await devbox.suspend();
await devbox.awaitSuspended();
console.log('Devbox is now suspended');
```
- Defined in src/sdk/devbox.ts:905

snapshotDisk

snapshotDisk(
    params?: DevboxSnapshotDiskParams,
    options?: RequestOptions<unknown> & {
        polling?: Partial<PollingOptions<DevboxSnapshotView>>;
    },
): Promise<RunloopSDK.Snapshot>
Create a disk snapshot of the devbox. Returns a snapshot that is completed. If you don't want to block on completion, use snapshotDiskAsync().
Parameters
- Optionalparams: DevboxSnapshotDiskParams
  Snapshot creation parameters
- Optionaloptions: RequestOptions<unknown> & {
  polling?: Partial<PollingOptions<DevboxSnapshotView>>;
  }
  Request options with optional polling configuration
Returns Promise<RunloopSDK.Snapshot>
A completed Snapshot instance
Example
```
const snapshot = await devbox.snapshotDisk({ name: 'pre-deployment' });
console.log(`Snapshot ${snapshot.id} created successfully`);
```
- Defined in src/sdk/devbox.ts:921

snapshotDiskAsync

snapshotDiskAsync(
params?: DevboxSnapshotDiskParams,
options?: RequestOptions<unknown>,
): Promise<RunloopSDK.Snapshot>
Create a disk snapshot of the devbox asynchronously. Returns a snapshot that is not yet completed but has started. You can await completion using snapshot.awaitCompleted().
Parameters
- Optionalparams: DevboxSnapshotDiskParams
  Snapshot creation parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<RunloopSDK.Snapshot>
A Snapshot instance that has started but may not be completed
Example
```
const snapshot = await devbox.snapshotDiskAsync({ name: 'backup' });
// Do other work...
await snapshot.awaitCompleted();
```
- Defined in src/sdk/devbox.ts:944

shutdown

shutdown(options?: RequestOptions<unknown>): Promise<DevboxView>
Shutdown the devbox.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<DevboxView>
Shutdown result
Example
```
await devbox.shutdown();
```
- Defined in src/sdk/devbox.ts:963

suspend

suspend(options?: RequestOptions<unknown>): Promise<DevboxView>
Suspend the devbox and create a disk snapshot.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<DevboxView>
Suspend result
Example
```
await devbox.suspend();
// Optionally, wait for the devbox to reach the suspended state
await devbox.awaitSuspended();
```
- Defined in src/sdk/devbox.ts:980

resume

resume(options?: LongPollRequestOptions<DevboxView>): Promise<DevboxView>
Resume a suspended devbox and wait for it to reach the running state.
Parameters
- Optionaloptions: LongPollRequestOptions<DevboxView>
  Request options with optional long-poll configuration
Returns Promise<DevboxView>
The devbox data when running state is reached
Example
```
await devbox.resume();
// Devbox is now running
```
- Defined in src/sdk/devbox.ts:996

resumeAsync

resumeAsync(options?: RequestOptions<unknown>): Promise<DevboxView>
Resume a suspended devbox without waiting for it to reach the running state.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<DevboxView>
Resume result
Example
```
await devbox.resumeAsync();
// Optionally wait for running state
await devbox.awaitRunning();
```
- Defined in src/sdk/devbox.ts:1014

keepAlive

keepAlive(options?: RequestOptions<unknown>): Promise<unknown>
Send a keep-alive signal to prevent idle shutdown.
Parameters
- Optionaloptions: RequestOptions<unknown>
  Request options
Returns Promise<unknown>
Keep-alive result
Example
```
// Send keep-alive periodically
setInterval(() => devbox.keepAlive(), 60000);
```
- Defined in src/sdk/devbox.ts:1030

onEvict

onEvict(callback: EvictionCallback): void
Register a callback fired once if this devbox gets a pending infrastructure eviction.

The first onEvict across any devbox on this client opens a single account-wide notification stream; it closes automatically once every registered devbox has been notified. The callback runs at most once and is invoked as callback(devbox, evictionDeadlineMs) — this devbox and the Unix millisecond deadline by which it will be suspended. Use it to run cleanup before suspend.
Parameters
- callback: EvictionCallback
  Invoked with this devbox and its eviction deadline (ms).
Returns void
Example
```
devbox.onEvict((devbox, evictionDeadlineMs) => {
  console.log(`${devbox.id} will be suspended at ${evictionDeadlineMs}`);
});
```
- Defined in src/sdk/devbox.ts:1052

cancelOnEvict

cancelOnEvict(): void
Withdraw this devbox's eviction interest registered via onEvict.

Returns void
- Defined in src/sdk/devbox.ts:1059

Class Devbox

Remarks

Overview

Quickstart

Index

Properties

Accessors

Methods

Properties

Readonlynet

Readonlycmd

Readonlyfile

Accessors

id

Returns string

Methods

shell

Parameters

Returns DevboxNamedShell

Example

getInfo

Parameters

Returns Promise<DevboxView>

Example

getTunnel

Parameters

Returns Promise<TunnelView | null>

Example

getTunnelUrl

Parameters

Returns Promise<string>

Example

Throws

logs

Parameters

Returns Promise<DevboxLogsListView>

Example

awaitRunning

Parameters

Returns Promise<DevboxView>

Example

awaitSuspended

Parameters

Returns Promise<DevboxView>

Example

snapshotDisk

Parameters

Returns Promise<RunloopSDK.Snapshot>

Example

snapshotDiskAsync

Parameters

Returns Promise<RunloopSDK.Snapshot>

Example

shutdown

Parameters

Returns Promise<DevboxView>

Example

suspend

Parameters

Returns Promise<DevboxView>

Example

resume

Parameters

Returns Promise<DevboxView>

Example

resumeAsync

Parameters

Returns Promise<DevboxView>

Example

keepAlive

Parameters

Returns Promise<unknown>

Example

onEvict

Parameters

Returns void

Example

cancelOnEvict

Returns void

Settings

`Readonly`net

`Readonly`cmd

`Readonly`file