devboxes.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../resource';
import { isRequestOptions } from '../../core';
import { APIPromise } from '../../core';
import * as Core from '../../core';
import * as Shared from '../shared';
import * as DiskSnapshotsAPI from './disk-snapshots';
import {
  DevboxSnapshotAsyncStatusView,
  DiskSnapshotDeleteResponse,
  DiskSnapshotListParams,
  DiskSnapshotUpdateParams,
  DiskSnapshots,
} from './disk-snapshots';
import * as ExecutionsAPI from './executions';
import {
  ExecutionExecuteAsyncParams,
  ExecutionExecuteSyncParams,
  ExecutionKillParams,
  ExecutionRetrieveParams,
  ExecutionSendStdInParams,
  ExecutionStreamStderrUpdatesParams,
  ExecutionStreamStdoutUpdatesParams,
  ExecutionUpdateChunk,
  Executions,
} from './executions';
import * as LogsAPI from './logs';
import { DevboxLogsListView, LogListParams, Logs } from './logs';
import {
  DevboxesCursorIDPage,
  type DevboxesCursorIDPageParams,
  DiskSnapshotsCursorIDPage,
  type DiskSnapshotsCursorIDPageParams,
} from '../../pagination';
import { Stream } from '../../streaming';
import { type Response } from '../../_shims/index';
import {
  longPollUntil,
  LongPollRequestOptions,
  resolveLongPollTimeoutMs,
} from '@runloop/api-client/lib/polling';
import { awaitDevboxState } from '@runloop/api-client/lib/devbox-state';
import { DevboxTools } from './tools';
import { uuidv7 } from 'uuidv7';

type DevboxStatus = DevboxView['status'];
const DEVBOX_BOOTING_STATES: DevboxStatus[] = ['provisioning', 'initializing'];

export class Devboxes extends APIResource {
  diskSnapshots: DiskSnapshotsAPI.DiskSnapshots = new DiskSnapshotsAPI.DiskSnapshots(this._client);
  logs: LogsAPI.Logs = new LogsAPI.Logs(this._client);
  executions: ExecutionsAPI.Executions = new ExecutionsAPI.Executions(this._client);

  /**
   * 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.
   */
  create(body?: DevboxCreateParams, options?: Core.RequestOptions): Core.APIPromise<DevboxView>;
  create(options?: Core.RequestOptions): Core.APIPromise<DevboxView>;
  create(
    body: DevboxCreateParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxView> {
    if (isRequestOptions(body)) {
      return this.create({}, body);
    }
    return this._client.post('/v1/devboxes', { body, ...options });
  }

  /**
   * Get the latest details and status of a Devbox.
   */
  retrieve(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxView> {
    return this._client.get(`/v1/devboxes/${id}`, options);
  }

  /**
   * Wait for a devbox to reach the running state.
   * Long Polls the devbox status until it reaches running state.
   *
   * @param id - Devbox ID
   * @param options - request options with optional long-poll configuration.
   */
  async awaitRunning(id: string, options?: LongPollRequestOptions<DevboxView>): Promise<DevboxView> {
    return awaitDevboxState<DevboxView>({
      client: this._client,
      devboxId: id,
      targetState: 'running',
      statesToCheck: ['running', 'failure', 'shutdown'],
      transitionStates: DEVBOX_BOOTING_STATES,
      timeoutMs: resolveLongPollTimeoutMs(options),
      signal: options?.signal,
      errorMessage: (devboxId, actualState) => `Devbox ${devboxId} is in non-running state ${actualState}`,
    });
  }

  /**
   * Wait for a devbox to reach the suspended state.
   * Long Polls the devbox status until it reaches suspended state.
   *
   * @param id - Devbox ID
   * @param options - request options with optional long-poll configuration.
   */
  async awaitSuspended(id: string, options?: LongPollRequestOptions<DevboxView>): Promise<DevboxView> {
    return awaitDevboxState<DevboxView>({
      client: this._client,
      devboxId: id,
      targetState: 'suspended',
      statesToCheck: ['suspended', 'failure', 'shutdown'],
      transitionStates: ['suspending'],
      timeoutMs: resolveLongPollTimeoutMs(options),
      signal: options?.signal,
      errorMessage: (devboxId, actualState) => `Devbox ${devboxId} is in non-suspended state ${actualState}`,
    });
  }

  /**
   * Create a devbox and wait for it to reach the running state.
   * This is a convenience method that combines create() and awaitDevboxRunning().
   *
   * @param body - DevboxCreateParams
   * @param options - request options with optional long-poll configuration.
   */
  async createAndAwaitRunning(
    body?: DevboxCreateParams,
    options?: LongPollRequestOptions<DevboxView>,
  ): Promise<DevboxView> {
    const { longPoll, polling, ...requestOptions } = options ?? {};
    const devbox = (await this._client.post('/v1/devboxes/create_and_await_running', {
      body: body ?? {},
      ...requestOptions,
    })) as DevboxView;
    if (devbox.status === 'running') {
      return devbox;
    }
    return this.awaitRunning(devbox.id, { ...requestOptions, longPoll, polling });
  }
  /**
   * Updates the specified Devbox fields. Omitted fields are left unchanged. An empty
   * name clears the name, and an empty metadata map clears the metadata.
   */
  update(id: string, body?: DevboxUpdateParams, options?: Core.RequestOptions): Core.APIPromise<DevboxView>;
  update(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxView>;
  update(
    id: string,
    body: DevboxUpdateParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxView> {
    if (isRequestOptions(body)) {
      return this.update(id, {}, body);
    }
    return this._client.post(`/v1/devboxes/${id}`, { body, ...options });
  }

  /**
   * List all Devboxes while optionally filtering by status.
   */
  list(
    query?: DevboxListParams,
    options?: Core.RequestOptions,
  ): Core.PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>;
  list(options?: Core.RequestOptions): Core.PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView>;
  list(
    query: DevboxListParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.PagePromise<DevboxViewsDevboxesCursorIDPage, DevboxView> {
    if (isRequestOptions(query)) {
      return this.list({}, query);
    }
    return this._client.getAPIList('/v1/devboxes', DevboxViewsDevboxesCursorIDPage, { query, ...options });
  }

  /**
   * 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.
   */
  createGatewayToken(
    id: string,
    body: DevboxCreateGatewayTokenParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<GatewayTokenView> {
    return this._client.post(`/v1/devboxes/${id}/create_gateway_token`, { body, ...options });
  }

  /**
   * [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.
   */
  createMcpToken(
    id: string,
    body: DevboxCreateMcpTokenParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<McpTokenView> {
    return this._client.post(`/v1/devboxes/${id}/create_mcp_token`, { body, ...options });
  }

  /**
   * 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.
   */
  createPtyTunnel(id: string, options?: Core.RequestOptions): Core.APIPromise<PtyTunnelView> {
    return this._client.post(`/v1/devboxes/${id}/create_pty_tunnel`, options);
  }

  /**
   * Create an SSH key for a Devbox to enable remote access.
   */
  createSSHKey(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxCreateSSHKeyResponse> {
    return this._client.post(`/v1/devboxes/${id}/create_ssh_key`, options);
  }

  /**
   * Delete a previously taken disk snapshot of a Devbox.
   */
  deleteDiskSnapshot(id: string, options?: Core.RequestOptions): Core.APIPromise<unknown> {
    return this._client.post(`/v1/devboxes/disk_snapshots/${id}/delete`, options);
  }

  /**
   * Download file contents of any type (binary, text, etc) from a specified path on
   * the Devbox.
   */
  downloadFile(
    id: string,
    body: DevboxDownloadFileParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<Response> {
    return this._client.post(`/v1/devboxes/${id}/download_file`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
      headers: { Accept: 'application/octet-stream', ...options?.headers },
      __binaryResponse: true,
    });
  }

  /**
   * 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://&#123;port&#125;-&#123;tunnel_key&#125;.tunnel.runloop.ai
   *
   * Each Devbox can have one tunnel. If tunnel config is omitted, or auth_mode is
   * omitted, the tunnel defaults to open (public hostname, no bearer token).
   */
  enableTunnel(
    id: string,
    body?: DevboxEnableTunnelParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<TunnelView>;
  enableTunnel(id: string, options?: Core.RequestOptions): Core.APIPromise<TunnelView>;
  enableTunnel(
    id: string,
    body: DevboxEnableTunnelParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<TunnelView> {
    if (isRequestOptions(body)) {
      return this.enableTunnel(id, {}, body);
    }
    return this._client.post(`/v1/devboxes/${id}/enable_tunnel`, { body, ...options });
  }

  /**
   * 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.
   */
  execute(
    id: string,
    params: DevboxExecuteParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxAsyncExecutionDetailView> {
    const { last_n, ...body } = params;
    return this._client.post(`/v1/devboxes/${id}/execute`, {
      body: {
        ...body,
        command_id: body.command_id || uuidv7(),
      },
      query: { last_n },
      timeout: this._client.timeout ?? 600000,
      ...options,
    });
  }

  /**
   * Execute a command and wait for it to complete with optimal latency for long running commands that can't rely on just polling.
   *
   * @param devboxId - Devbox ID
   * @param params - Execution parameters.
   * @param options - request options with optional long-poll configuration.
   */
  async executeAndAwaitCompletion(
    devboxId: string,
    params: Omit<DevboxExecuteParams, 'command_id'>,
    options?: LongPollRequestOptions<DevboxAsyncExecutionDetailView>,
  ): Promise<DevboxAsyncExecutionDetailView> {
    const { longPoll, polling, ...requestOptions } = options ?? {};
    const effectiveTimeoutMs = resolveLongPollTimeoutMs(options);
    const commandId = uuidv7();
    const execution = await this.execute(
      devboxId,
      { ...params, command_id: commandId },
      { ...{ timeout: requestOptions?.timeout ?? effectiveTimeoutMs ?? 600000 }, ...requestOptions },
    );

    if (execution.status === 'completed') {
      return execution;
    }

    const waitForCommandBody: DevboxWaitForCommandParams = {
      statuses: ['completed'],
    };

    if (params.last_n) {
      waitForCommandBody.last_n = params.last_n;
    }

    const finalResult = await longPollUntil(
      (signal) =>
        this.waitForCommand(devboxId, execution.execution_id, waitForCommandBody, {
          signal,
          // Per-request HTTP timeout must exceed the server's max long-poll hold (25s)
          // so the server's 408 always arrives before the client aborts the connection.
          // The longPollUntil AbortSignal enforces the caller's actual deadline.
          timeout: 600000,
          // Disable base-client retries so 408s surface immediately to longPollUntil
          // (the server's wait_for_status endpoint sets x-should-retry: true for executions).
          maxRetries: 0,
        }),
      {
        timeoutMs: effectiveTimeoutMs,
        shouldStop: (result) => result.status === 'completed',
        signal: requestOptions.signal,
      },
    );

    return finalResult;
  }

  /**
   * Execute the given command in the Devbox shell asynchronously and returns the
   * execution that can be used to track the command's progress.
   */
  executeAsync(
    id: string,
    body: DevboxExecuteAsyncParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxAsyncExecutionDetailView> {
    return this._client.post(`/v1/devboxes/${id}/execute_async`, { body, ...options });
  }

  /**
   * 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.
   *
   * @deprecated Use execute, executeAsync, or executeAndAwaitCompletion instead.
   */
  executeSync(
    id: string,
    body: DevboxExecuteSyncParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxExecutionDetailView> {
    return this._client.post(`/v1/devboxes/${id}/execute_sync`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
    });
  }

  /**
   * Send a 'Keep Alive' signal to a running Devbox that is configured to shutdown on
   * idle so the idle time resets.
   */
  keepAlive(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxKeepAliveResponse> {
    return this._client.post(`/v1/devboxes/${id}/keep_alive`, options);
  }

  /**
   * List all snapshots of a Devbox while optionally filtering by Devbox ID, source
   * Blueprint ID, and metadata.
   */
  listDiskSnapshots(
    query?: DevboxListDiskSnapshotsParams,
    options?: Core.RequestOptions,
  ): Core.PagePromise<DevboxSnapshotViewsDiskSnapshotsCursorIDPage, DevboxSnapshotView>;
  listDiskSnapshots(
    options?: Core.RequestOptions,
  ): Core.PagePromise<DevboxSnapshotViewsDiskSnapshotsCursorIDPage, DevboxSnapshotView>;
  listDiskSnapshots(
    query: DevboxListDiskSnapshotsParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.PagePromise<DevboxSnapshotViewsDiskSnapshotsCursorIDPage, DevboxSnapshotView> {
    if (isRequestOptions(query)) {
      return this.listDiskSnapshots({}, query);
    }
    return this._client.getAPIList(
      '/v1/devboxes/disk_snapshots',
      DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
      { query, ...options },
    );
  }

  /**
   * 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.
   */
  readFileContents(
    id: string,
    body: DevboxReadFileContentsParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<string> {
    return this._client.post(`/v1/devboxes/${id}/read_file_contents`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
      headers: { Accept: 'text/plain', ...options?.headers },
    });
  }

  /**
   * Remove an existing V2 tunnel from the Devbox.
   */
  removeTunnel(id: string, options?: Core.RequestOptions): Core.APIPromise<unknown> {
    return this._client.post(`/v1/devboxes/${id}/remove_tunnel`, options);
  }

  /**
   * 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.
   */
  resume(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxView> {
    return this._client.post(`/v1/devboxes/${id}/resume`, options);
  }

  /**
   * 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.
   */
  retrieveResourceUsage(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxResourceUsageView> {
    return this._client.get(`/v1/devboxes/${id}/usage`, options);
  }

  /**
   * 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.
   */
  shutdown(
    id: string,
    params?: DevboxShutdownParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxView>;
  shutdown(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxView>;
  shutdown(
    id: string,
    params: DevboxShutdownParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxView> {
    if (isRequestOptions(params)) {
      return this.shutdown(id, {}, params);
    }
    const { force } = params;
    return this._client.post(`/v1/devboxes/${id}/shutdown`, { query: { force }, ...options });
  }

  /**
   * Create a disk snapshot of a devbox with the specified name and metadata to
   * enable launching future Devboxes with the same disk state.
   */
  snapshotDisk(
    id: string,
    body?: DevboxSnapshotDiskParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxSnapshotView>;
  snapshotDisk(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxSnapshotView>;
  snapshotDisk(
    id: string,
    body: DevboxSnapshotDiskParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxSnapshotView> {
    if (isRequestOptions(body)) {
      return this.snapshotDisk(id, {}, body);
    }
    return this._client.post(`/v1/devboxes/${id}/snapshot_disk`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
    });
  }

  /**
   * 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.
   */
  snapshotDiskAsync(
    id: string,
    body?: DevboxSnapshotDiskAsyncParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxSnapshotView>;
  snapshotDiskAsync(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxSnapshotView>;
  snapshotDiskAsync(
    id: string,
    body: DevboxSnapshotDiskAsyncParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxSnapshotView> {
    if (isRequestOptions(body)) {
      return this.snapshotDiskAsync(id, {}, body);
    }
    return this._client.post(`/v1/devboxes/${id}/snapshot_disk_async`, { body, ...options });
  }

  /**
   * 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.
   */
  suspend(id: string, options?: Core.RequestOptions): Core.APIPromise<DevboxView> {
    return this._client.post(`/v1/devboxes/${id}/suspend`, options);
  }

  /**
   * 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.
   */
  uploadFile(
    id: string,
    body: DevboxUploadFileParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<unknown> {
    return this._client.post(
      `/v1/devboxes/${id}/upload_file`,
      Core.multipartFormRequestOptions({
        body,
        timeout: this._client.timeout ?? 600000,
        ...options,
      }),
    );
  }

  /**
   * Polls the asynchronous execution's status until it reaches one of the desired
   * statuses or times out. Max is 25 seconds.
   */
  waitForCommand(
    devboxId: string,
    executionId: string,
    params: DevboxWaitForCommandParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxAsyncExecutionDetailView> {
    const { last_n, ...body } = params;
    return this._client.post(`/v1/devboxes/${devboxId}/executions/${executionId}/wait_for_status`, {
      query: { last_n },
      body,
      ...options,
    });
  }

  /**
   * 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.
   */
  watchEvictions(options?: Core.RequestOptions): APIPromise<Stream<DevboxEvictionEventView>> {
    return this._client.get('/v1/devboxes/evictions/watch', { ...options, stream: true }) as APIPromise<
      Stream<DevboxEvictionEventView>
    >;
  }

  /**
   * 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.
   */
  writeFileContents(
    id: string,
    body: DevboxWriteFileContentsParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DevboxExecutionDetailView> {
    return this._client.post(`/v1/devboxes/${id}/write_file_contents`, {
      body,
      timeout: this._client.timeout ?? 600000,
      ...options,
    });
  }

  // Make an accessor for tools
  get tools(): DevboxTools {
    return new DevboxTools(this);
  }
}

export class DevboxViewsDevboxesCursorIDPage extends DevboxesCursorIDPage<DevboxView> {}

export class DevboxSnapshotViewsDiskSnapshotsCursorIDPage extends DiskSnapshotsCursorIDPage<DevboxSnapshotView> {}

/**
 * Details of an asynchronous command execution on a Devbox.
 *
 * @category Devbox Types
 */
export interface DevboxAsyncExecutionDetailView {
  /**
   * Devbox id where command was executed.
   */
  devbox_id: string;

  /**
   * Ephemeral id of the execution in progress.
   */
  execution_id: string;

  /**
   * Current status of the execution.
   */
  status: 'queued' | 'running' | 'completed';

  /**
   * Exit code of command execution. This field will remain unset until the execution
   * has completed.
   */
  exit_status?: number | null;

  /**
   * Standard error generated by command. This field will remain unset until the
   * execution has completed.
   */
  stderr?: string | null;

  /**
   * Indicates whether the stderr was truncated due to size limits.
   */
  stderr_truncated?: boolean | null;

  /**
   * Standard out generated by command. This field will remain unset until the
   * execution has completed.
   */
  stdout?: string | null;

  /**
   * Indicates whether the stdout was truncated due to size limits.
   */
  stdout_truncated?: boolean | null;
}

export interface DevboxEvictionEventView {
  /**
   * The ID of the Devbox with a pending eviction.
   */
  devbox_id: string;

  /**
   * Unix timestamp (milliseconds) after which the Devbox will be suspended. Advisory
   * and best-effort.
   */
  eviction_deadline_ms: number;
}

export interface DevboxExecutionDetailView {
  /**
   * Devbox id where command was executed.
   */
  devbox_id: string;

  /**
   * Exit status of command execution.
   */
  exit_status: number;

  /**
   * Standard error generated by command.
   */
  stderr: string;

  /**
   * Standard out generated by command.
   */
  stdout: string;
}

export interface DevboxKillExecutionRequest {
  /**
   * Whether to kill the entire process group (default: false). If true, kills all
   * processes in the same process group as the target process.
   */
  kill_process_group?: boolean | null;
}

export interface DevboxListView {
  /**
   * List of devboxes matching filter.
   */
  devboxes: Array<DevboxView>;

  has_more: boolean;

  total_count?: number | null;
}

export interface DevboxResourceUsageView {
  /**
   * The devbox ID.
   */
  id: string;

  /**
   * Disk usage in GB-seconds (total_elapsed_seconds multiplied by disk size in GB).
   * Disk is billed for elapsed time since storage is consumed even when suspended.
   */
  disk_gb_seconds: number;

  /**
   * Memory usage in GB-seconds (total_active_seconds multiplied by memory in GB).
   */
  memory_gb_seconds: number;

  /**
   * The devbox creation time in milliseconds since epoch.
   */
  start_time_ms: number;

  /**
   * The current status of the devbox.
   */
  status: string;

  /**
   * Total time in seconds the devbox was actively running (excludes time spent
   * suspended).
   */
  total_active_seconds: number;

  /**
   * Total elapsed time in seconds from devbox creation to now (or end time if
   * terminated). Includes all time regardless of devbox state.
   */
  total_elapsed_seconds: number;

  /**
   * vCPU usage in vCPU-seconds (total_active_seconds multiplied by the number of
   * vCPUs).
   */
  vcpu_seconds: number;

  /**
   * The devbox end time in milliseconds since epoch, or null if still running.
   */
  end_time_ms?: number | null;
}

export interface DevboxSendStdInRequest {
  /**
   * Signal to send to std in of the running execution.
   */
  signal?: 'EOF' | 'INTERRUPT' | null;

  /**
   * Text to send to std in of the running execution.
   */
  text?: string | null;
}

export interface DevboxSendStdInResult {
  /**
   * Devbox id where command is executing.
   */
  devbox_id: string;

  /**
   * Execution id that received the stdin.
   */
  execution_id: string;

  /**
   * Whether the stdin was successfully sent.
   */
  success: boolean;
}

export interface DevboxSnapshotListView {
  has_more: boolean;

  /**
   * List of snapshots matching filter.
   */
  snapshots: Array<DevboxSnapshotView>;

  total_count?: number | null;
}

/**
 * View of a Devbox disk snapshot.
 *
 * @category Snapshot Types
 */
export interface DevboxSnapshotView {
  /**
   * The unique identifier of the snapshot.
   */
  id: string;

  /**
   * Creation time of the Snapshot (Unix timestamp milliseconds).
   */
  create_time_ms: number;

  /**
   * User defined metadata associated with the snapshot.
   */
  metadata: { [key: string]: string };

  /**
   * The source Devbox ID this snapshot was created from.
   */
  source_devbox_id: string;

  /**
   * (Optional) The commit message of the snapshot (max 1000 characters).
   */
  commit_message?: string | null;

  /**
   * (Optional) The custom name of the snapshot.
   */
  name?: string | null;

  /**
   * (Optional) The size of the snapshot in bytes, relative to the base blueprint.
   */
  size_bytes?: number | null;

  /**
   * (Optional) The source Blueprint ID this snapshot was created from.
   */
  source_blueprint_id?: string | null;
}

/**
 * A Devbox represents a virtual development environment. It is an isolated sandbox
 * that can be given to agents and used to run arbitrary code such as AI generated
 * code.
 *
 * @category Devbox Types
 */
export interface DevboxView {
  /**
   * The ID of the Devbox.
   */
  id: string;

  /**
   * A list of capability groups this devbox has access to.
   */
  capabilities: Array<'unknown' | 'docker_in_docker'>;

  /**
   * Creation time of the Devbox (Unix timestamp milliseconds).
   */
  create_time_ms: number;

  /**
   * The time the Devbox finished execution (Unix timestamp milliseconds). Present if
   * the Devbox is in a terminal state.
   */
  end_time_ms: number | null;

  /**
   * The launch parameters used to create the Devbox.
   */
  launch_parameters: Shared.LaunchParameters;

  /**
   * The user defined Devbox metadata.
   */
  metadata: { [key: string]: string };

  /**
   * A list of state transitions in order with durations
   */
  state_transitions: Array<DevboxView.StateTransition>;

  /**
   * The current status of the Devbox.
   */
  status:
    | 'scheduled'
    | 'queued'
    | 'provisioning'
    | 'initializing'
    | 'running'
    | 'suspending'
    | 'suspended'
    | 'resuming'
    | 'failure'
    | 'shutdown';

  /**
   * The Blueprint ID used in creation of the Devbox, if the devbox was created from
   * a Blueprint.
   */
  blueprint_id?: string | null;

  /**
   * The category of failure experienced by the Devbox.
   *
   * out_of_memory: The Devbox ran out of memory at runtime. Use launch parameters to
   * request a larger resource size. out_of_disk: The Devbox ran out of disk at
   * runtime. Please reach out to support for us to better support your use case.
   * execution_failed: The Devbox failed at runtime. Please use the dashboard to look
   * at the logs of the failure. health_check_failed: The Devbox failed its health
   * checks. This may indicate resource utilization is close to the maximum. Consider
   * requesting a larger resource size.
   */
  failure_reason?: 'out_of_memory' | 'out_of_disk' | 'execution_failed' | 'health_check_failed' | null;

  /**
   * Gateway specifications configured for this devbox. Map key is the environment
   * variable prefix (e.g., 'GWS_ANTHROPIC').
   */
  gateway_specs?: { [key: string]: DevboxView.GatewaySpecs } | null;

  /**
   * The ID of the initiator that created the Devbox.
   */
  initiator_id?: string | null;

  /**
   * The type of initiator that created the Devbox.
   */
  initiator_type?: 'unknown' | 'api' | 'reflex';

  /**
   * [Beta] MCP specifications configured for this devbox. Map key is the environment
   * variable name for the MCP token envelope. Each spec links an MCP config to a
   * secret for MCP server access through the MCP hub.
   */
  mcp_specs?: { [key: string]: DevboxView.McpSpecs } | null;

  /**
   * The name of the Devbox.
   */
  name?: string | null;

  /**
   * The reason that caused the transition of the Devbox to the shutown state.
   *
   * api_shutdown: The Devbox shutdown due to API request. entrypoint_exit: The
   * Devbox entrypoint program completed. idle: The Devbox shutdown due to configured
   * action on idle configuration. ttl_expired: The Devbox shutdown due to TTL
   * expiration.
   */
  shutdown_reason?: 'api_shutdown' | 'keep_alive_timeout' | 'entrypoint_exit' | 'idle' | 'ttl_expired' | null;

  /**
   * The Snapshot ID used in creation of the Devbox, if the devbox was created from a
   * Snapshot.
   */
  snapshot_id?: string | null;

  /**
   * A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels
   * allow external clients to reach web servers, APIs, or other HTTP services
   * running inside a Devbox without requiring direct network access. Each tunnel is
   * uniquely identified by an encrypted tunnel_key and can be configured for either
   * open (public) or authenticated access. Usage:
   * https://{port}-{tunnel_key}.tunnel.runloop.ai. Authenticated tunnels should pass
   * auth_token as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
   */
  tunnel?: TunnelView | null;
}

export namespace DevboxView {
  export interface StateTransition {
    /**
     * The failure that caused this state transition, if applicable.
     */
    failure_reason?: string | null;

    /**
     * The status of the Devbox.
     *
     * scheduled: Deprecated. The Devbox is waiting for infrastructure allocation to
     * start. Use queued. queued: The Devbox is waiting for infrastructure allocation
     * to start. provisioning: Runloop is allocating and booting the necessary
     * infrastructure resources. initializing: Runloop defined boot scripts are running
     * to enable the environment for interaction. running: The Devbox is ready for
     * interaction. suspending: The Devbox disk is being snapshotted as part of
     * suspension. suspended: The Devbox disk is saved and no more active compute is
     * being used for the Devbox. resuming: The Devbox disk is being loaded as part of
     * booting a suspended Devbox. failure: The Devbox failed as part of booting or
     * running user requested actions. shutdown: The Devbox was successfully shutdown
     * and no more active compute is being used.
     */
    status?:
      | 'scheduled'
      | 'queued'
      | 'provisioning'
      | 'initializing'
      | 'running'
      | 'suspending'
      | 'suspended'
      | 'resuming'
      | 'failure'
      | 'shutdown';

    /**
     * The time the status change occurred
     */
    transition_time_ms?: unknown;
  }

  export interface GatewaySpecs {
    /**
     * The ID of the gateway config (e.g., gwc_123abc).
     */
    gateway_config_id: string;

    /**
     * The ID of the secret containing the credential.
     */
    secret_id: string;
  }

  export interface McpSpecs {
    /**
     * The ID of the MCP config (e.g., mcp_123abc).
     */
    mcp_config_id: string;

    /**
     * The ID of the secret containing the credential.
     */
    secret_id: string;
  }
}

export interface GatewayTokenView {
  /**
   * The token to send to the gateway as a Bearer token in the Authorization header.
   * Only accepted for requests originating from the bound Devbox.
   */
  token: string;

  /**
   * How the gateway applies the credential to proxied requests.
   */
  auth_mechanism: Shared.AuthMechanism;

  /**
   * The Devbox the token is bound to.
   */
  devbox_id: string;

  /**
   * The target API endpoint the gateway proxies to.
   */
  endpoint: string;

  /**
   * The ID of the gateway config the token proxies through.
   */
  gateway_config_id: string;

  /**
   * The gateway URL to send requests to. Matches the value of the
   * &#123;prefix&#125;\_URL environment variable inside the Devbox.
   */
  url: string;
}

export interface McpTokenView {
  /**
   * The token to send to the MCP hub as a Bearer token in the Authorization header.
   * Only accepted for requests originating from the bound Devbox.
   */
  token: string;

  /**
   * Glob patterns for the tools the token permits.
   */
  allowed_tools: Array<string>;

  /**
   * The Devbox the token is bound to.
   */
  devbox_id: string;

  /**
   * The upstream MCP server endpoint the hub proxies to.
   */
  endpoint: string;

  /**
   * The ID of the MCP config the token grants access to.
   */
  mcp_config_id: string;

  /**
   * The MCP hub URL the token authenticates against. Matches the RL_MCP_URL
   * environment variable inside the Devbox.
   */
  url: string;
}

/**
 * An ephemeral PTY tunnel providing authenticated terminal access to a Devbox.
 * These tunnels are not stored on the Devbox and are generated fresh on each
 * request. Usage: https://{port}-{tunnel_key}.tunnel.runloop.ai with
 * X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
 */
export interface PtyTunnelView {
  /**
   * Bearer token for tunnel authentication. Always required for PTY tunnels. Pass as
   * X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
   */
  auth_token: string;

  /**
   * The encrypted tunnel key used to construct the tunnel URL. URL format:
   * https://{port}-{tunnel_key}.tunnel.runloop.{domain}
   */
  tunnel_key: string;
}

/**
 * A V2 tunnel provides secure HTTP access to services running on a Devbox. Tunnels
 * allow external clients to reach web servers, APIs, or other HTTP services
 * running inside a Devbox without requiring direct network access. Each tunnel is
 * uniquely identified by an encrypted tunnel_key and can be configured for either
 * open (public) or authenticated access. Usage:
 * https://{port}-{tunnel_key}.tunnel.runloop.ai. Authenticated tunnels should pass
 * auth_token as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
 */
export interface TunnelView {
  /**
   * The authentication mode for the tunnel.
   */
  auth_mode: 'open' | 'authenticated';

  /**
   * Creation time of the tunnel (Unix timestamp milliseconds).
   */
  create_time_ms: number;

  /**
   * When true, HTTP traffic through the tunnel counts as activity for idle lifecycle
   * policies, resetting the idle timer.
   */
  http_keep_alive: boolean;

  /**
   * The encrypted tunnel key used to construct the tunnel URL. URL format:
   * https://{port}-{tunnel_key}.tunnel.runloop.{domain}
   */
  tunnel_key: string;

  /**
   * When true, HTTP traffic to a suspended devbox will automatically trigger a
   * resume.
   */
  wake_on_http: boolean;

  /**
   * Bearer token for tunnel authentication. Only present when auth_mode is
   * 'authenticated'. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.
   */
  auth_token?: string | null;
}

export interface DevboxCreateSSHKeyResponse {
  /**
   * The ID of the Devbox.
   */
  id: string;

  /**
   * The ssh private key, in PEM format.
   */
  ssh_private_key: string;

  /**
   * The Linux user to use for SSH connections to this Devbox.
   */
  ssh_user: string;

  /**
   * The host url of the Devbox that can be used for SSH.
   */
  url: string;
}

export type DevboxDeleteDiskSnapshotResponse = unknown;

export type DevboxKeepAliveResponse = unknown;

export type DevboxReadFileContentsResponse = string;

export type DevboxRemoveTunnelResponse = unknown;

export type DevboxUploadFileResponse = unknown;

/**
 * Parameters for creating a new Devbox.
 *
 * @category Devbox Types
 */
export interface DevboxCreateParams {
  /**
   * Blueprint ID to use for the Devbox. If none set, the Devbox will be created with
   * the default Runloop Devbox image. Only one of (Snapshot ID, Blueprint ID,
   * Blueprint name) should be specified.
   */
  blueprint_id?: string | null;

  /**
   * Name of Blueprint to use for the Devbox. When set, this will load the latest
   * successfully built Blueprint with the given name. Only one of (Snapshot ID,
   * Blueprint ID, Blueprint name) should be specified.
   */
  blueprint_name?: string | null;

  /**
   * A list of code mounts to be included in the Devbox. Use mounts instead.
   */
  code_mounts?: Array<Shared.CodeMountParameters> | null;

  /**
   * (Optional) When specified, the Devbox will run this script as its main
   * executable. The devbox lifecycle will be bound to entrypoint, shutting down when
   * the process is complete.
   */
  entrypoint?: string | null;

  /**
   * (Optional) Environment variables used to configure your Devbox.
   */
  environment_variables?: { [key: string]: string } | null;

  /**
   * Map of paths and file contents to write before setup. Use mounts instead.
   */
  file_mounts?: { [key: string]: string } | null;

  /**
   * (Optional) Agent gateway specifications for credential proxying. Map key is the
   * environment variable prefix (e.g., 'GWS_ANTHROPIC'). The agent gateway will
   * proxy requests to external APIs using the specified credential without exposing
   * the real API key. Example: {'GWS_ANTHROPIC': {'gateway': 'anthropic', 'secret':
   * 'my_claude_key'}}
   */
  gateways?: { [key: string]: DevboxCreateParams.Gateways } | null;

  /**
   * LaunchParameters enable you to customize the resources available to your Devbox
   * as well as the environment set up that should be completed before the Devbox is
   * marked as 'running'.
   */
  launch_parameters?: Shared.LaunchParameters | null;

  /**
   * [Beta] (Optional) MCP specifications for MCP server access. Map key is the
   * environment variable name for the MCP token envelope. Each spec links an MCP
   * config to a secret. The devbox will also receive RL_MCP_URL for the MCP hub
   * endpoint. Example: {'MCP_SECRET': {'mcp_config': 'github-readonly', 'secret':
   * 'MY_GITHUB_TOKEN'}}
   */
  mcp?: { [key: string]: DevboxCreateParams.Mcp } | null;

  /**
   * User defined metadata to attach to the devbox for organization.
   */
  metadata?: { [key: string]: string } | null;

  /**
   * A list of mounts to be included in the Devbox.
   */
  mounts?: Array<Shared.Mount> | null;

  /**
   * (Optional) A user specified name to give the Devbox.
   */
  name?: string | null;

  /**
   * (Optional) Map of environment variable names to secret names. The secret values
   * will be securely injected as environment variables in the Devbox. Example:
   * {"DB_PASS": "DATABASE_PASSWORD"} sets environment variable 'DB_PASS' to the
   * value of secret 'DATABASE_PASSWORD'.
   */
  secrets?: { [key: string]: string } | null;

  /**
   * Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID,
   * Blueprint name) should be specified.
   */
  snapshot_id?: string | null;

  /**
   * Configuration for creating a V2 tunnel. When specified at Devbox creation, a
   * tunnel will be automatically provisioned.
   */
  tunnel?: DevboxCreateParams.Tunnel | null;
}

export namespace DevboxCreateParams {
  /**
   * GatewaySpec links an agent gateway configuration to a secret for credential
   * proxying in a devbox. The agent gateway will proxy requests to external APIs
   * using the specified credential without exposing the real API key.
   */
  export interface Gateways {
    /**
     * The gateway config to use. Can be a gateway config ID (gwc_xxx) or name. A name
     * binds the most recently created config with that name.
     */
    gateway: string;

    /**
     * The secret containing the credential. Can be a secret ID or name.
     */
    secret: string;
  }

  /**
   * [Beta] McpSpec links an MCP configuration to a secret for MCP server access in a
   * devbox. The MCP hub will proxy requests to upstream MCP servers using the
   * specified credential, with tool-level access control based on the MCP config's
   * allowed_tools.
   */
  export interface Mcp {
    /**
     * The MCP config to use. Can be an MCP config ID (mcp_xxx) or name. A name binds
     * the most recently created config with that name.
     */
    mcp_config: string;

    /**
     * The secret containing the MCP server credential. Can be a secret ID or name.
     */
    secret: string;
  }

  /**
   * Configuration for creating a V2 tunnel. When specified at Devbox creation, a
   * tunnel will be automatically provisioned.
   */
  export interface Tunnel {
    /**
     * Authentication mode for the tunnel. Defaults to open if omitted: the hostname is
     * a public capability and does not require a tunnel bearer token.
     */
    auth_mode?: 'open' | 'authenticated' | null;

    /**
     * When true, HTTP traffic through the tunnel counts as activity for idle lifecycle
     * policies, resetting the idle timer. Defaults to true if not specified.
     */
    http_keep_alive?: boolean | null;

    /**
     * When true, HTTP traffic to a suspended devbox will automatically trigger a
     * resume. Defaults to false if not specified. Prefer
     * lifecycle.resume_triggers.http on launch_parameters for new integrations. If
     * both are set, lifecycle.resume_triggers.http takes precedence.
     */
    wake_on_http?: boolean | null;
  }
}

export interface DevboxUpdateParams {
  /**
   * User defined metadata to replace the Devbox metadata. Omit to leave unchanged or
   * set to an empty map to clear it.
   */
  metadata?: { [key: string]: string } | null;

  /**
   * A user specified name to give the Devbox. Omit to leave unchanged or set to an
   * empty string to clear it.
   */
  name?: string | null;
}

export interface DevboxListParams extends DevboxesCursorIDPageParams {
  /**
   * If true (default), includes total_count in the response. Set to false to skip
   * the count query for better performance on large datasets.
   */
  include_total_count?: boolean;

  /**
   * Filter by status
   */
  status?:
    | 'scheduled'
    | 'queued'
    | 'provisioning'
    | 'initializing'
    | 'running'
    | 'suspending'
    | 'suspended'
    | 'resuming'
    | 'failure'
    | 'shutdown';
}

export interface DevboxCreateGatewayTokenParams {
  /**
   * The gateway config to use. Can be a gateway config ID (gwc_xxx) or name.
   */
  gateway: string;

  /**
   * The secret containing the credential. Can be a secret ID or name.
   */
  secret: string;
}

export interface DevboxCreateMcpTokenParams {
  /**
   * The MCP config to use. Can be an MCP config ID (mcp_xxx) or name.
   */
  mcp_config: string;

  /**
   * The secret containing the MCP server credential. Can be a secret ID or name.
   */
  secret: string;
}

export interface DevboxDownloadFileParams {
  /**
   * The path on the Devbox filesystem to read the file from. Path is relative to
   * user home directory.
   */
  path: string;
}

export interface DevboxEnableTunnelParams {
  /**
   * Authentication mode for the tunnel. Defaults to open if omitted: the hostname is
   * a public capability and does not require a tunnel bearer token.
   */
  auth_mode?: 'open' | 'authenticated' | null;

  /**
   * When true, HTTP traffic through the tunnel counts as activity for idle lifecycle
   * policies, resetting the idle timer. Defaults to true if not specified.
   */
  http_keep_alive?: boolean | null;

  /**
   * When true, HTTP traffic to a suspended devbox will automatically trigger a
   * resume. Defaults to false if not specified. Prefer
   * lifecycle.resume_triggers.http on launch_parameters for new integrations. If
   * both are set, lifecycle.resume_triggers.http takes precedence.
   */
  wake_on_http?: boolean | null;
}

/**
 * Parameters for executing a command on a Devbox.
 *
 * @category Devbox Types
 */
export interface DevboxExecuteParams {
  /**
   * Body param: The command to execute via the Devbox shell. Commands are run from
   * the user home directory in a fresh login shell.
   */
  command: string;

  /**
   * Body param: The command ID in UUIDv7 string format for idempotency and tracking
   */
  command_id?: string; // This is optional as the client will generate a command_id if not provided

  /**
   * Query param: Last n lines of standard error / standard out to return
   * (default: 100)
   */
  last_n?: string;

  /**
   * Body param: Timeout in seconds to wait for command completion, up to 25 seconds.
   * Defaults to 25 seconds. Operation is not killed.
   */
  optimistic_timeout?: number | null;
}

export interface DevboxExecuteAsyncParams {
  /**
   * The command to execute via the Devbox shell. Commands are run from the user home
   * directory in a fresh login shell.
   */
  command: string;

  /**
   * Whether to attach stdin streaming for async commands. Not valid for execute_sync
   * endpoint. Defaults to false if not specified.
   */
  attach_stdin?: boolean | null;
}

export interface DevboxExecuteSyncParams {
  /**
   * The command to execute via the Devbox shell. Commands are run from the user home
   * directory in a fresh login shell.
   */
  command: string;

  /**
   * Whether to attach stdin streaming for async commands. Not valid for execute_sync
   * endpoint. Defaults to false if not specified.
   */
  attach_stdin?: boolean | null;
}

export interface DevboxListDiskSnapshotsParams extends DiskSnapshotsCursorIDPageParams {
  /**
   * Devbox ID to filter by.
   */
  devbox_id?: string;

  /**
   * If true (default), includes total_count in the response. Set to false to skip
   * the count query for better performance on large datasets.
   */
  include_total_count?: boolean;

  /**
   * Filter snapshots by metadata key-value pair. Can be used multiple times for
   * different keys.
   */
  'metadata[key]'?: string;

  /**
   * Filter snapshots by metadata key with multiple possible values (OR condition).
   */
  'metadata[key][in]'?: string;

  /**
   * Source Blueprint ID to filter snapshots by.
   */
  source_blueprint_id?: string;
}

export interface DevboxReadFileContentsParams {
  /**
   * The path on the Devbox filesystem to read the file from. Path is relative to
   * user home directory.
   */
  file_path: string;
}

export interface DevboxShutdownParams {
  /**
   * If true, force shutdown even if snapshots are in progress. Defaults to false.
   */
  force?: string;
}

export interface DevboxSnapshotDiskParams {
  /**
   * (Optional) Commit message associated with the snapshot (max 1000 characters)
   */
  commit_message?: string | null;

  /**
   * (Optional) Metadata used to describe the snapshot
   */
  metadata?: { [key: string]: string } | null;

  /**
   * (Optional) A user specified name to give the snapshot
   */
  name?: string | null;
}

export interface DevboxSnapshotDiskAsyncParams {
  /**
   * (Optional) Commit message associated with the snapshot (max 1000 characters)
   */
  commit_message?: string | null;

  /**
   * (Optional) Metadata used to describe the snapshot
   */
  metadata?: { [key: string]: string } | null;

  /**
   * (Optional) A user specified name to give the snapshot
   */
  name?: string | null;
}

export interface DevboxUploadFileParams {
  /**
   * The path to write the file to on the Devbox. Path is relative to user home
   * directory.
   */
  path: string;

  file?: Core.Uploadable;
}

export interface DevboxWaitForCommandParams {
  /**
   * Body param: The command execution statuses to wait for. At least one status must
   * be provided. The command will be returned as soon as it reaches any of the
   * provided statuses.
   */
  statuses: Array<'queued' | 'running' | 'completed'>;

  /**
   * Query param: Last n lines of standard error / standard out to return
   * (default: 100)
   */
  last_n?: string;

  /**
   * Body param: (Optional) Timeout in seconds to wait for the status, up to 25
   * seconds. Defaults to 25 seconds.
   */
  timeout_seconds?: number | null;
}

export interface DevboxWriteFileContentsParams {
  /**
   * The UTF-8 string contents to write to the file.
   */
  contents: string;

  /**
   * The path to write the file to on the Devbox. Path is relative to user home
   * directory.
   */
  file_path: string;
}

Devboxes.DevboxViewsDevboxesCursorIDPage = DevboxViewsDevboxesCursorIDPage;
Devboxes.DevboxSnapshotViewsDiskSnapshotsCursorIDPage = DevboxSnapshotViewsDiskSnapshotsCursorIDPage;
Devboxes.DiskSnapshots = DiskSnapshots;
Devboxes.Logs = Logs;
Devboxes.Executions = Executions;

export declare namespace Devboxes {
  export {
    type DevboxAsyncExecutionDetailView as DevboxAsyncExecutionDetailView,
    type DevboxEvictionEventView as DevboxEvictionEventView,
    type DevboxExecutionDetailView as DevboxExecutionDetailView,
    type DevboxKillExecutionRequest as DevboxKillExecutionRequest,
    type DevboxListView as DevboxListView,
    type DevboxResourceUsageView as DevboxResourceUsageView,
    type DevboxSendStdInRequest as DevboxSendStdInRequest,
    type DevboxSendStdInResult as DevboxSendStdInResult,
    type DevboxSnapshotListView as DevboxSnapshotListView,
    type DevboxSnapshotView as DevboxSnapshotView,
    type DevboxView as DevboxView,
    type GatewayTokenView as GatewayTokenView,
    type McpTokenView as McpTokenView,
    type PtyTunnelView as PtyTunnelView,
    type TunnelView as TunnelView,
    type DevboxCreateSSHKeyResponse as DevboxCreateSSHKeyResponse,
    type DevboxDeleteDiskSnapshotResponse as DevboxDeleteDiskSnapshotResponse,
    type DevboxKeepAliveResponse as DevboxKeepAliveResponse,
    type DevboxReadFileContentsResponse as DevboxReadFileContentsResponse,
    type DevboxRemoveTunnelResponse as DevboxRemoveTunnelResponse,
    type DevboxUploadFileResponse as DevboxUploadFileResponse,
    DevboxViewsDevboxesCursorIDPage as DevboxViewsDevboxesCursorIDPage,
    DevboxSnapshotViewsDiskSnapshotsCursorIDPage as DevboxSnapshotViewsDiskSnapshotsCursorIDPage,
    type DevboxCreateParams as DevboxCreateParams,
    type DevboxUpdateParams as DevboxUpdateParams,
    type DevboxListParams as DevboxListParams,
    type DevboxCreateGatewayTokenParams as DevboxCreateGatewayTokenParams,
    type DevboxCreateMcpTokenParams as DevboxCreateMcpTokenParams,
    type DevboxDownloadFileParams as DevboxDownloadFileParams,
    type DevboxEnableTunnelParams as DevboxEnableTunnelParams,
    type DevboxExecuteParams as DevboxExecuteParams,
    type DevboxExecuteAsyncParams as DevboxExecuteAsyncParams,
    type DevboxExecuteSyncParams as DevboxExecuteSyncParams,
    type DevboxListDiskSnapshotsParams as DevboxListDiskSnapshotsParams,
    type DevboxReadFileContentsParams as DevboxReadFileContentsParams,
    type DevboxShutdownParams as DevboxShutdownParams,
    type DevboxSnapshotDiskParams as DevboxSnapshotDiskParams,
    type DevboxSnapshotDiskAsyncParams as DevboxSnapshotDiskAsyncParams,
    type DevboxUploadFileParams as DevboxUploadFileParams,
    type DevboxWaitForCommandParams as DevboxWaitForCommandParams,
    type DevboxWriteFileContentsParams as DevboxWriteFileContentsParams,
  };

  export {
    DiskSnapshots as DiskSnapshots,
    type DevboxSnapshotAsyncStatusView as DevboxSnapshotAsyncStatusView,
    type DiskSnapshotDeleteResponse as DiskSnapshotDeleteResponse,
    type DiskSnapshotUpdateParams as DiskSnapshotUpdateParams,
    type DiskSnapshotListParams as DiskSnapshotListParams,
  };

  export { Logs as Logs, type DevboxLogsListView as DevboxLogsListView, type LogListParams as LogListParams };

  export {
    Executions as Executions,
    type ExecutionUpdateChunk as ExecutionUpdateChunk,
    type ExecutionRetrieveParams as ExecutionRetrieveParams,
    type ExecutionExecuteAsyncParams as ExecutionExecuteAsyncParams,
    type ExecutionExecuteSyncParams as ExecutionExecuteSyncParams,
    type ExecutionKillParams as ExecutionKillParams,
    type ExecutionSendStdInParams as ExecutionSendStdInParams,
    type ExecutionStreamStderrUpdatesParams as ExecutionStreamStderrUpdatesParams,
    type ExecutionStreamStdoutUpdatesParams as ExecutionStreamStdoutUpdatesParams,
  };
}