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. The Devbox will initially launch in the 'provisioning' state while Runloop allocates the necessary infrastructure. It will transition to the 'initializing' state while the booted Devbox runs any Runloop or user defined set up scripts. Finally, the Devbox will transition to the 'running' state 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. The Devbox will initially launch in the 'provisioning' state while Runloop allocates the necessary infrastructure. It will transition to the 'initializing' state while the booted Devbox runs any Runloop or user defined set up scripts. Finally, the Devbox will transition to the 'running' state 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 a devbox by doing a complete update the existing name,metadata fields. It does not patch partial values.

  Parameters

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

  Returns APIPromise<DevboxView>

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

  Updates a devbox by doing a complete update the existing name,metadata fields. It does not patch partial values.

  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>

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>

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>