Class Devboxes

constructor

• new Devboxes(client: Runloop): Devboxes

  Parameters

  • client: Runloop

  Returns Devboxes

diskSnapshots

browsers

computers

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?: RequestOptions<unknown> & {
          polling?: Partial<PollingOptions<DevboxView>>;
      },
  ): Promise<DevboxView>

  Wait for a devbox to reach the running state. Polls the devbox status until it reaches running state or fails with an error.

  Parameters

  • id: string

    Devbox ID

  • Optionaloptions: RequestOptions<unknown> & { polling?: Partial<PollingOptions<DevboxView>> }

    request options to specify retries, timeout, polling, etc.

  Returns Promise<DevboxView>

awaitSuspended

• awaitSuspended(
      id: string,
      options?: RequestOptions<unknown> & {
          polling?: Partial<PollingOptions<DevboxView>>;
      },
  ): Promise<DevboxView>

  Wait for a devbox to reach the suspended state. Polls the devbox status until it reaches suspended state or fails with an error.

  Parameters

  • id: string

    Devbox ID

  • Optionaloptions: RequestOptions<unknown> & { polling?: Partial<PollingOptions<DevboxView>> }

    request options to specify retries, timeout, polling, etc.

  Returns Promise<DevboxView>

createAndAwaitRunning

• createAndAwaitRunning(
      body?: DevboxCreateParams,
      options?: RequestOptions<unknown> & {
          polling?: Partial<PollingOptions<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: RequestOptions<unknown> & { polling?: Partial<PollingOptions<DevboxView>> }

    request options to specify retries, timeout, polling, etc.

  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>

createTunnel

• createTunnel(
      id: string,
      body: DevboxCreateTunnelParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<DevboxTunnelView>

  [Deprecated] Use POST /v1/devboxes/{id}/enable_tunnel instead. This endpoint creates a legacy tunnel. The new enable_tunnel endpoint provides improved tunnel functionality with authentication options.

  Parameters

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

  Returns APIPromise<DevboxTunnelView>

  Deprecated

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>

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?: RequestOptions<unknown> & {
          polling?: Partial<PollingOptions<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
  • params: Omit<DevboxExecuteParams, "command_id">
  • Optionaloptions: RequestOptions<unknown> & {
        polling?: Partial<PollingOptions<DevboxAsyncExecutionDetailView>>;
    }

  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,
      body: DevboxRemoveTunnelParams,
      options?: RequestOptions<unknown>,
  ): APIPromise<unknown>

  Remove a previously opened tunnel on the Devbox.

  Parameters

  • id: string
  • body: DevboxRemoveTunnelParams
  • 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>

shutdown

• 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.

  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>