Class Devboxes

constructor

• new Devboxes(client: Runloop): Devboxes

  Parameters

  • client: Runloop

  Returns Devboxes

diskSnapshots

logs

executions

tools

• get tools(): DevboxTools

  Returns DevboxTools

create

• create(
      body?: DevboxCreateParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxView>

  Create a Devbox and begin the boot process. Standard Devboxes initially report the 'provisioning' state. FLEX Devboxes initially report the 'queued' state while waiting for infrastructure allocation, then transition to 'provisioning' once assigned to a node. The Devbox transitions to 'initializing' while the booted Devbox runs Runloop or user-defined setup scripts, then to 'running' when it is ready for use.

  Parameters

  • Optionalbody: DevboxCreateParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

• create(options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Create a Devbox and begin the boot process. Standard Devboxes initially report the 'provisioning' state. FLEX Devboxes initially report the 'queued' state while waiting for infrastructure allocation, then transition to 'provisioning' once assigned to a node. The Devbox transitions to 'initializing' while the booted Devbox runs Runloop or user-defined setup scripts, then to 'running' when it is ready for use.

  Parameters

  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

retrieve

• retrieve(id: string, options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Get the latest details and status of a Devbox.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

awaitRunning

• awaitRunning(
      id: string,
      options?: LongPollRequestOptions<DevboxView>,
  ): Promise<DevboxView>

  Wait for a devbox to reach the running state. Long Polls the devbox status until it reaches running state.

  Parameters

  • id: string

    Devbox ID

  • Optionaloptions: LongPollRequestOptions<DevboxView>

    request options with optional long-poll configuration.

  Returns Promise<DevboxView>

awaitSuspended

• awaitSuspended(
      id: string,
      options?: LongPollRequestOptions<DevboxView>,
  ): Promise<DevboxView>

  Wait for a devbox to reach the suspended state. Long Polls the devbox status until it reaches suspended state.

  Parameters

  • id: string

    Devbox ID

  • Optionaloptions: LongPollRequestOptions<DevboxView>

    request options with optional long-poll configuration.

  Returns Promise<DevboxView>

createAndAwaitRunning

• createAndAwaitRunning(
      body?: DevboxCreateParams,
      options?: LongPollRequestOptions<DevboxView>,
  ): Promise<DevboxView>

  Create a devbox and wait for it to reach the running state. This is a convenience method that combines create() and awaitDevboxRunning().

  Parameters

  • Optionalbody: DevboxCreateParams

    DevboxCreateParams

  • Optionaloptions: LongPollRequestOptions<DevboxView>

    request options with optional long-poll configuration.

  Returns Promise<DevboxView>

update

• update(
      id: string,
      body?: DevboxUpdateParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxView>

  Updates the specified Devbox fields. Omitted fields are left unchanged. An empty name clears the name, and an empty metadata map clears the metadata.

  Parameters

  • id: string
  • Optionalbody: DevboxUpdateParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

• update(id: string, options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Updates the specified Devbox fields. Omitted fields are left unchanged. An empty name clears the name, and an empty metadata map clears the metadata.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

list

• list(
      query?: DevboxListParams,
      options?: RequestOptions<unknown>,
  ): PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>

  List all Devboxes while optionally filtering by status.

  Parameters

  • Optionalquery: DevboxListParams
  • Optionaloptions: RequestOptions<unknown>

  Returns PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>

• list(
      options?: RequestOptions<unknown>,
  ): PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>

  List all Devboxes while optionally filtering by status.

  Parameters

  • Optionaloptions: RequestOptions<unknown>

  Returns PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>

createGatewayToken

• createGatewayToken(
      id: string,
      body: DevboxCreateGatewayTokenParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<GatewayTokenView>

  Mint a token that lets a running Devbox call an external API through the Runloop agent gateway, using the credential in the supplied secret. The gateway applies the credential to proxied requests, so the real API key is never exposed to the Devbox.

  The token is bound to this Devbox and is only accepted for requests that originate from it. Nothing is stored on the Devbox: the token is returned to the caller and is not re-issued when the Devbox is resumed.

  Parameters

  • id: string
  • body: DevboxCreateGatewayTokenParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<GatewayTokenView>

createMcpToken

• createMcpToken(
      id: string,
      body: DevboxCreateMcpTokenParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<McpTokenView>

  [Beta] Mint a token that lets a running Devbox reach an upstream MCP (Model Context Protocol) server through the Runloop MCP hub, using the credential in the supplied secret. Tool access is limited to the MCP config's allowed_tools, and the credential itself is never exposed to the Devbox.

  The token is bound to this Devbox and is only accepted for requests that originate from it. Nothing is stored on the Devbox: the token is returned to the caller and is not re-issued when the Devbox is resumed.

  Parameters

  • id: string
  • body: DevboxCreateMcpTokenParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<McpTokenView>

createPtyTunnel

• createPtyTunnel(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<PtyTunnelView>

  Create an ephemeral authenticated tunnel for terminal access to a running Devbox. This tunnel is not persisted on the Devbox and is generated fresh on each request. The returned auth_token should be passed as a Bearer token in the X-Runloop-Tunnel-Authorization header.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<PtyTunnelView>

createSSHKey

• createSSHKey(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxCreateSSHKeyResponse>

  Create an SSH key for a Devbox to enable remote access.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxCreateSSHKeyResponse>

deleteDiskSnapshot

• deleteDiskSnapshot(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<unknown>

  Delete a previously taken disk snapshot of a Devbox.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<unknown>

downloadFile

• downloadFile(
      id: string,
      body: DevboxDownloadFileParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<Response>

  Download file contents of any type (binary, text, etc) from a specified path on the Devbox.

  Parameters

  • id: string
  • body: DevboxDownloadFileParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<Response>

enableTunnel

• enableTunnel(
      id: string,
      body?: DevboxEnableTunnelParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<TunnelView>

  Enable a V2 tunnel for an existing running Devbox. Tunnels provide encrypted URL-based access to the Devbox without exposing internal IDs. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai

  Each Devbox can have one tunnel.

  Parameters

  • id: string
  • Optionalbody: DevboxEnableTunnelParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<TunnelView>

• enableTunnel(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<TunnelView>

  Enable a V2 tunnel for an existing running Devbox. Tunnels provide encrypted URL-based access to the Devbox without exposing internal IDs. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai

  Each Devbox can have one tunnel.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<TunnelView>

execute

• execute(
      id: string,
      params: DevboxExecuteParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxAsyncExecutionDetailView>

  Execute a command with a known command ID on a devbox, optimistically waiting for it to complete within the specified timeout. If it completes in time, return the result. If not, return a status indicating the command is still running. Note: attach_stdin parameter is not supported; use execute_async for stdin support.

  Parameters

  • id: string
  • params: DevboxExecuteParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxAsyncExecutionDetailView>

executeAndAwaitCompletion

• executeAndAwaitCompletion(
      devboxId: string,
      params: Omit<DevboxExecuteParams, "command_id">,
      options?: LongPollRequestOptions<DevboxAsyncExecutionDetailView>,
  ): Promise<DevboxAsyncExecutionDetailView>

  Execute a command and wait for it to complete with optimal latency for long running commands that can't rely on just polling.

  Parameters

  • devboxId: string

    Devbox ID

  • params: Omit<DevboxExecuteParams, "command_id">

    Execution parameters.

  • Optionaloptions: LongPollRequestOptions<DevboxAsyncExecutionDetailView>

    request options with optional long-poll configuration.

  Returns Promise<DevboxAsyncExecutionDetailView>

executeAsync

• executeAsync(
      id: string,
      body: DevboxExecuteAsyncParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxAsyncExecutionDetailView>

  Execute the given command in the Devbox shell asynchronously and returns the execution that can be used to track the command's progress.

  Parameters

  • id: string
  • body: DevboxExecuteAsyncParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxAsyncExecutionDetailView>

executeSync

• executeSync(
      id: string,
      body: DevboxExecuteSyncParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxExecutionDetailView>

  Execute a bash command in the Devbox shell, await the command completion and return the output. Note: attach_stdin parameter is not supported for synchronous execution.

  Parameters

  • id: string
  • body: DevboxExecuteSyncParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxExecutionDetailView>

  Deprecated

  Use execute, executeAsync, or executeAndAwaitCompletion instead.

keepAlive

• keepAlive(id: string, options?: RequestOptions<unknown>): APIPromise<unknown>

  Send a 'Keep Alive' signal to a running Devbox that is configured to shutdown on idle so the idle time resets.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<unknown>

listDiskSnapshots

• listDiskSnapshots(
      query?: DevboxListDiskSnapshotsParams,
      options?: RequestOptions<unknown>,
  ): PagePromise<
      DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
      DevboxSnapshotView,
  >

  List all snapshots of a Devbox while optionally filtering by Devbox ID, source Blueprint ID, and metadata.

  Parameters

  • Optionalquery: DevboxListDiskSnapshotsParams
  • Optionaloptions: RequestOptions<unknown>

  Returns PagePromise<DevboxSnapshotViewsDiskSnapshotsCursorIDPage, DevboxSnapshotView>

• listDiskSnapshots(
      options?: RequestOptions<unknown>,
  ): PagePromise<
      DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
      DevboxSnapshotView,
  >

  List all snapshots of a Devbox while optionally filtering by Devbox ID, source Blueprint ID, and metadata.

  Parameters

  • Optionaloptions: RequestOptions<unknown>

  Returns PagePromise<DevboxSnapshotViewsDiskSnapshotsCursorIDPage, DevboxSnapshotView>

readFileContents

• readFileContents(
      id: string,
      body: DevboxReadFileContentsParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<string>

  Read file contents from a file on a Devbox as a UTF-8. Note 'downloadFile' should be used for large files (greater than 100MB). Returns the file contents as a UTF-8 string.

  Parameters

  • id: string
  • body: DevboxReadFileContentsParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<string>

removeTunnel

• removeTunnel(id: string, options?: RequestOptions<unknown>): APIPromise<unknown>

  Remove an existing V2 tunnel from the Devbox.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<unknown>

resume

• resume(id: string, options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Resume a suspended Devbox with the disk state captured as suspend time. Note that any previously running processes or daemons will need to be restarted using the Devbox shell tools.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

retrieveResourceUsage

• retrieveResourceUsage(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxResourceUsageView>

  Get resource usage metrics for a specific Devbox. Returns CPU, memory, and disk consumption calculated from the Devbox's lifecycle, excluding any suspended periods for CPU and memory. Disk usage includes the full elapsed time since storage is consumed even when suspended.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxResourceUsageView>

shutdown

• shutdown(
      id: string,
      params?: DevboxShutdownParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxView>

  Shutdown a running Devbox. This will permanently stop the Devbox. If you want to save the state of the Devbox, you should take a snapshot before shutting down or should suspend the Devbox instead of shutting down. If the Devbox has any in-progress snapshots, the shutdown will be rejected with a 409 Conflict unless force=true is specified.

  Parameters

  • id: string
  • Optionalparams: DevboxShutdownParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

• shutdown(id: string, options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Shutdown a running Devbox. This will permanently stop the Devbox. If you want to save the state of the Devbox, you should take a snapshot before shutting down or should suspend the Devbox instead of shutting down. If the Devbox has any in-progress snapshots, the shutdown will be rejected with a 409 Conflict unless force=true is specified.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

snapshotDisk

• snapshotDisk(
      id: string,
      body?: DevboxSnapshotDiskParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxSnapshotView>

  Create a disk snapshot of a devbox with the specified name and metadata to enable launching future Devboxes with the same disk state.

  Parameters

  • id: string
  • Optionalbody: DevboxSnapshotDiskParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxSnapshotView>

• snapshotDisk(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxSnapshotView>

  Create a disk snapshot of a devbox with the specified name and metadata to enable launching future Devboxes with the same disk state.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxSnapshotView>

snapshotDiskAsync

• snapshotDiskAsync(
      id: string,
      body?: DevboxSnapshotDiskAsyncParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxSnapshotView>

  Start an asynchronous disk snapshot of a devbox with the specified name and metadata. The snapshot operation will continue in the background and can be monitored using the query endpoint.

  Parameters

  • id: string
  • Optionalbody: DevboxSnapshotDiskAsyncParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxSnapshotView>

• snapshotDiskAsync(
      id: string,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxSnapshotView>

  Start an asynchronous disk snapshot of a devbox with the specified name and metadata. The snapshot operation will continue in the background and can be monitored using the query endpoint.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxSnapshotView>

suspend

• suspend(id: string, options?: RequestOptions<unknown>): APIPromise<DevboxView>

  Suspend a running Devbox and create a disk snapshot to enable resuming the Devbox later with the same disk. Note this will not snapshot memory state such as running processes.

  Parameters

  • id: string
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxView>

uploadFile

• uploadFile(
      id: string,
      body: DevboxUploadFileParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<unknown>

  Upload file contents of any type (binary, text, etc) to a Devbox. Note this API is suitable for large files (larger than 100MB) and efficiently uploads files via multipart form data.

  Parameters

  • id: string
  • body: DevboxUploadFileParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<unknown>

waitForCommand

• waitForCommand(
      devboxId: string,
      executionId: string,
      params: DevboxWaitForCommandParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxAsyncExecutionDetailView>

  Polls the asynchronous execution's status until it reaches one of the desired statuses or times out. Max is 25 seconds.

  Parameters

  • devboxId: string
  • executionId: string
  • params: DevboxWaitForCommandParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxAsyncExecutionDetailView>

watchEvictions

• watchEvictions(
      options?: RequestOptions<unknown>,
  ): APIPromise<Stream<DevboxEvictionEventView>>

  Subscribe, via server-sent events, to pending infrastructure evictions for every Devbox in the account. On connect the stream emits one event per Devbox that currently has a pending eviction, then one event as each further eviction is scheduled. Best-effort and advisory: a Devbox stays running until its deadline, and delivery is not guaranteed.

  Parameters

  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<Stream<DevboxEvictionEventView>>

writeFileContents

• writeFileContents(
      id: string,
      body: DevboxWriteFileContentsParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxExecutionDetailView>

  Write UTF-8 string contents to a file at path on the Devbox. Note for large files (larger than 100MB), the upload_file endpoint must be used.

  Parameters

  • id: string
  • body: DevboxWriteFileContentsParams
  • Optionaloptions: RequestOptions<unknown>

  Returns APIPromise<DevboxExecutionDetailView>