shared.ts

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

import * as Shared from './shared';

/**
 * Configuration for automatic Devbox behavior after idle time.
 *
 * @category Shared Types
 */
export interface AfterIdle {
  /**
   * After idle_time_seconds, on_idle action will be taken.
   */
  idle_time_seconds: number;

  /**
   * Action to take after Devbox becomes idle.
   */
  on_idle: 'shutdown' | 'suspend';
}

export interface AgentMount {
  /**
   * The ID of the agent to mount. Either agent_id or name must be set.
   */
  agent_id: string | null;

  /**
   * The name of the agent to mount. Returns the most recent agent with a matching
   * name if no agent id string provided. Either agent id or name must be set
   */
  agent_name: string | null;

  type: 'agent_mount';

  /**
   * Path to mount the agent on the Devbox. Required for git and object agents. Use
   * absolute path (e.g., /home/user/agent)
   */
  agent_path?: string | null;

  /**
   * Optional auth token for private repositories. Only used for git agents.
   */
  auth_token?: string | null;
}

/**
 * Agent source configuration.
 *
 * @category Shared Types
 */
export interface AgentSource {
  /**
   * Source type: npm, pip, object, or git
   */
  type: string;

  /**
   * Git source configuration
   */
  git?: AgentSource.Git | null;

  /**
   * NPM source configuration
   */
  npm?: AgentSource.Npm | null;

  /**
   * Object store source configuration
   */
  object?: AgentSource.Object | null;

  /**
   * Pip source configuration
   */
  pip?: AgentSource.Pip | null;
}

export namespace AgentSource {
  /**
   * Git source configuration
   */
  export interface Git {
    /**
     * Git repository URL
     */
    repository: string;

    /**
     * Setup commands to run after cloning
     */
    agent_setup?: Array<string> | null;

    /**
     * Optional Git ref (branch/tag/commit), defaults to main/HEAD
     */
    ref?: string | null;
  }

  /**
   * NPM source configuration
   */
  export interface Npm {
    /**
     * NPM package name
     */
    package_name: string;

    /**
     * Setup commands to run after installation
     */
    agent_setup?: Array<string> | null;

    /**
     * NPM registry URL
     */
    registry_url?: string | null;
  }

  /**
   * Object store source configuration
   */
  export interface Object {
    /**
     * Object ID
     */
    object_id: string;

    /**
     * Setup commands to run after unpacking
     */
    agent_setup?: Array<string> | null;
  }

  /**
   * Pip source configuration
   */
  export interface Pip {
    /**
     * Pip package name
     */
    package_name: string;

    /**
     * Setup commands to run after installation
     */
    agent_setup?: Array<string> | null;

    /**
     * Pip registry URL
     */
    registry_url?: string | null;
  }
}

export interface BrokerMount {
  /**
   * The ID of the axon event stream to mount onto the Devbox.
   */
  axon_id: string;

  type: 'broker_mount';

  /**
   * Binary to launch the agent (e.g., 'opencode'). Used by protocols that launch a
   * subprocess (acp, claude_json).
   */
  agent_binary?: string | null;

  /**
   * Arguments to pass to the agent command (e.g., ['acp']). Used by protocols that
   * launch a subprocess (acp, claude_json).
   */
  launch_args?: Array<string> | null;

  /**
   * The protocol used by the broker to deliver events to the agent.
   */
  protocol?: 'acp' | 'claude_json' | null;

  /**
   * Working directory in which to launch the agent binary. Defaults to the home
   * directory if not specified.
   */
  working_directory?: string | null;
}

/**
 * Parameters for mounting code from a Git repository.
 *
 * @category Shared Types
 */
export interface CodeMountParameters {
  /**
   * The name of the repo to mount. By default, code will be mounted at
   * /home/user/{repo_name}.
   */
  repo_name: string;

  /**
   * The owner of the repo.
   */
  repo_owner: string;

  /**
   * The authentication token necessary to pull repo.
   */
  token?: string | null;

  /**
   * Optional git ref (branch or tag) to checkout. Defaults to the repository default
   * branch.
   */
  git_ref?: string | null;

  /**
   * Installation command to install and setup repository.
   */
  install_command?: string | 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'.
 *
 * @category Shared Types
 */
export interface LaunchParameters {
  /**
   * Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox
   * will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle
   * are set, they must have the same value. Use lifecycle.after_idle instead.
   */
  after_idle?: AfterIdle | null;

  /**
   * The target architecture for the Devbox. If unset, defaults to x86_64.
   */
  architecture?: 'x86_64' | 'arm64' | null;

  /**
   * [Deprecated] A list of ports to make available on the Devbox. This field is
   * ignored.
   */
  available_ports?: Array<number> | null;

  /**
   * Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.
   */
  custom_cpu_cores?: number | null;

  /**
   * Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.
   */
  custom_disk_size?: number | null;

  /**
   * Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.
   */
  custom_gb_memory?: number | null;

  /**
   * Time in seconds after which Devbox will automatically shutdown. Default is 1
   * hour. Maximum is 48 hours (172800 seconds).
   */
  keep_alive_time_seconds?: number | null;

  /**
   * Set of commands to be run at launch time, before the entrypoint process is run.
   */
  launch_commands?: Array<string> | null;

  /**
   * Lifecycle configuration for idle and resume behavior. Configure idle policy via
   * lifecycle.after_idle (if both this and the top-level after_idle are set, they
   * must match) and resume triggers via lifecycle.resume_triggers.
   */
  lifecycle?: LaunchParameters.Lifecycle | null;

  /**
   * (Optional) ID of the network policy to apply to Devboxes launched with these
   * parameters. When set on a Blueprint launch parameters, Devboxes created from it
   * will inherit this policy unless explicitly overridden.
   */
  network_policy_id?: string | null;

  /**
   * A list of ContainerizedService names to be started when a Devbox is created. A
   * valid ContainerizedService must be specified in Blueprint to be started.
   */
  required_services?: Array<string> | null;

  /**
   * Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set,
   * SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB
   * RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB
   * RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32
   * GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and
   * optionally custom_disk_size.
   */
  resource_size_request?:
    | 'X_SMALL'
    | 'SMALL'
    | 'MEDIUM'
    | 'LARGE'
    | 'X_LARGE'
    | 'XX_LARGE'
    | 'CUSTOM_SIZE'
    | null;

  /**
   * Specify the user for execution on Devbox. If not set, default `user` will be
   * used.
   */
  user_parameters?: LaunchParameters.UserParameters | null;
}

export namespace LaunchParameters {
  /**
   * Lifecycle configuration for idle and resume behavior. Configure idle policy via
   * lifecycle.after_idle (if both this and the top-level after_idle are set, they
   * must match) and resume triggers via lifecycle.resume_triggers.
   */
  export interface Lifecycle {
    /**
     * Configure Devbox lifecycle based on idle activity. If both this and the
     * top-level after_idle are set, they must have the same value. Prefer this field
     * for new integrations.
     */
    after_idle?: Shared.AfterIdle | null;

    /**
     * Triggers that can resume a suspended Devbox.
     */
    resume_triggers?: Lifecycle.ResumeTriggers | null;
  }

  export namespace Lifecycle {
    /**
     * Triggers that can resume a suspended Devbox.
     */
    export interface ResumeTriggers {
      /**
       * When true, axon events targeting a suspended Devbox will trigger a resume.
       */
      axon_event?: boolean | null;

      /**
       * When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.
       */
      http?: boolean | null;
    }
  }

  /**
   * Specify the user for execution on Devbox. If not set, default `user` will be
   * used.
   */
  export interface UserParameters {
    /**
     * User ID (UID) for the Linux user. Must be a non-negative integer.
     */
    uid: number;

    /**
     * Username for the Linux user.
     */
    username: string;
  }
}

/**
 * Mount configuration for attaching files, agents, or code to a Devbox.
 *
 * @category Shared Types
 */
export type Mount = ObjectMount | AgentMount | Mount.CodeMount | Mount.FileMount | BrokerMount;

export namespace Mount {
  export interface CodeMount {
    /**
     * The name of the repo to mount. By default, code will be mounted at
     * /home/user/{repo_name}.
     */
    repo_name: string;

    /**
     * The owner of the repo.
     */
    repo_owner: string;

    type: 'code_mount';

    /**
     * The authentication token necessary to pull repo.
     */
    token?: string | null;

    /**
     * Optional git ref (branch or tag) to checkout. Defaults to the repository default
     * branch.
     */
    git_ref?: string | null;

    /**
     * Installation command to install and setup repository.
     */
    install_command?: string | null;
  }

  export interface FileMount {
    /**
     * Content of the file to mount.
     */
    content: string;

    /**
     * Target path where the file should be mounted.
     */
    target: string;

    type: 'file_mount';
  }
}

export interface ObjectMount {
  /**
   * The ID of the object to write.
   */
  object_id: string;

  /**
   * The path to write the object on the Devbox. Use absolute path of object (ie
   * /home/user/object.txt, or directory if archive /home/user/archive_dir)
   */
  object_path: string;

  type: 'object_mount';
}

/**
 * Configuration profile for scenario/benchmark runs.
 *
 * @category Shared Types
 */
export interface RunProfile {
  /**
   * Mapping of Environment Variable to Value. May be shown in devbox logging.
   * Example: {"DB_PASS": "DATABASE_PASSWORD"} would set the environment variable
   * 'DB_PASS' to the value 'DATABASE_PASSWORD_VALUE'.
   */
  envVars?: { [key: string]: string } | null;

  /**
   * Additional runtime LaunchParameters to apply after the devbox starts.
   */
  launchParameters?: LaunchParameters | null;

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

  /**
   * Purpose of the run.
   */
  purpose?: string | null;

  /**
   * Mapping of Environment Variable to User Secret Name. Never shown in devbox
   * logging. Example: {"DB_PASS": "DATABASE_PASSWORD"} would set the environment
   * variable 'DB_PASS' to the value of the secret 'DATABASE_PASSWORD'.
   */
  secrets?: { [key: string]: string } | null;
}