Type Reference

The Runloop Python SDK uses TypeDict objects for configuration parameters to the various API calls. This page documents the TypeDict objects used throughout the SDK.

Blueprint Parameters

These TypeDicts define parameters for blueprint creation and listing.

typeddict runloop_api_client.sdk._types.SDKBlueprintCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str])

• base_blueprint_id (Optional[str])

• base_blueprint_name (Optional[str])

• build_args (Optional[Dict[str, str]])

• build_context (Optional[BuildContext])

• code_mounts (Optional[Iterable[CodeMountParameters]])

• dockerfile (Optional[str])

• file_mounts (Optional[Dict[str, str]])

• launch_parameters (Optional[LaunchParameters])

• metadata (Optional[Dict[str, str]])

• named_build_contexts (Optional[Dict[str, NamedBuildContexts]])

• secrets (Optional[Dict[str, str]])

• services (Optional[Iterable[Service]])

• system_setup_commands (Optional[Sequence[str]])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

typeddict runloop_api_client.sdk._types.SDKBlueprintListParams

typing.TypedDict.

Optional Keys:

• limit (int)

• name (str)

• starting_after (str)

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

Devbox Parameters

These TypeDicts define parameters for devbox creation, listing, and operations.

Creation Parameters

typeddict runloop_api_client.sdk._types.SDKDevboxCreateParams

typing.TypedDict.

Optional Keys:

• code_mounts (Optional[Iterable[CodeMountParameters]])

• entrypoint (Optional[str])

• environment_variables (Optional[Dict[str, str]])

• file_mounts (Optional[Dict[str, str]])

• launch_parameters (Optional[LaunchParameters])

• metadata (Optional[Dict[str, str]])

• mounts (Optional[Iterable[Union[ObjectMountParameters, AgentMountParameters, CodeMountParameters, FileMountParameters]]])

• name (Optional[str])

• repo_connection_id (Optional[str])

• secrets (Optional[Dict[str, str]])

• blueprint_id (Optional[str])

• blueprint_name (Optional[str])

• snapshot_id (Optional[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

typeddict runloop_api_client.sdk._types.SDKDevboxCreateFromImageParams

typing.TypedDict.

Optional Keys:

• code_mounts (Optional[Iterable[CodeMountParameters]])

• entrypoint (Optional[str])

• environment_variables (Optional[Dict[str, str]])

• file_mounts (Optional[Dict[str, str]])

• launch_parameters (Optional[LaunchParameters])

• metadata (Optional[Dict[str, str]])

• mounts (Optional[Iterable[Union[ObjectMountParameters, AgentMountParameters, CodeMountParameters, FileMountParameters]]])

• name (Optional[str])

• repo_connection_id (Optional[str])

• secrets (Optional[Dict[str, str]])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

Listing Parameters

typeddict runloop_api_client.sdk._types.SDKDevboxListParams

typing.TypedDict.

Optional Keys:

• limit (int)

• starting_after (str)

• status (Literal['provisioning', 'initializing', 'running', 'suspending', 'suspended', 'resuming', 'failure', 'shutdown'])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

Command Execution Parameters

typeddict runloop_api_client.sdk._types.SDKDevboxExecuteParams

typing.TypedDict.

Optional Keys:

• command (Required[str])

• attach_stdin (Optional[bool])

• shell_name (Optional[str])

• stdout (Optional[Callable[[str], None]]) – Callback invoked for each stdout log line

• stderr (Optional[Callable[[str], None]]) – Callback invoked for each stderr log line

• output (Optional[Callable[[str], None]]) – Callback invoked for all log lines (both stdout and stderr)

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

typeddict runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams

typing.TypedDict.

Optional Keys:

• command (Required[str])

• attach_stdin (Optional[bool])

• shell_name (Optional[str])

• stdout (Optional[Callable[[str], None]]) – Callback invoked for each stdout log line

• stderr (Optional[Callable[[str], None]]) – Callback invoked for each stderr log line

• output (Optional[Callable[[str], None]]) – Callback invoked for all log lines (both stdout and stderr)

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

File Operation Parameters

typeddict runloop_api_client.sdk._types.SDKDevboxReadFileContentsParams

typing.TypedDict.

Optional Keys:

• file_path (Required[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKDevboxWriteFileContentsParams

typing.TypedDict.

Optional Keys:

• contents (Required[str])

• file_path (Required[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKDevboxDownloadFileParams

typing.TypedDict.

Optional Keys:

• path (Required[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKDevboxUploadFileParams

typing.TypedDict.

Optional Keys:

• path (Required[str])

• file (Union[IO[bytes], bytes, PathLike, Tuple[Optional[str], Union[IO[bytes], bytes, PathLike]], Tuple[Optional[str], Union[IO[bytes], bytes, PathLike], Optional[str]], Tuple[Optional[str], Union[IO[bytes], bytes, PathLike], Optional[str], Mapping[str, str]]])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

Network Tunnel Parameters

typeddict runloop_api_client.sdk._types.SDKDevboxCreateTunnelParams

typing.TypedDict.

Optional Keys:

• port (Required[int])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKDevboxRemoveTunnelParams

typing.TypedDict.

Optional Keys:

• port (Required[int])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

Snapshot Parameters

These TypeDicts define parameters for snapshot creation, listing, and updating.

typeddict runloop_api_client.sdk._types.SDKDevboxSnapshotDiskParams

typing.TypedDict.

Optional Keys:

• commit_message (Optional[str])

• metadata (Optional[Dict[str, str]])

• name (Optional[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

typeddict runloop_api_client.sdk._types.SDKDevboxSnapshotDiskAsyncParams

typing.TypedDict.

Optional Keys:

• commit_message (Optional[str])

• metadata (Optional[Dict[str, str]])

• name (Optional[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKDiskSnapshotListParams

typing.TypedDict.

Optional Keys:

• devbox_id (str)

• limit (int)

• metadata_key (str)

• metadata_key_in (str)

• source_blueprint_id (str)

• starting_after (str)

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

typeddict runloop_api_client.sdk._types.SDKDiskSnapshotUpdateParams

typing.TypedDict.

Optional Keys:

• commit_message (Optional[str])

• metadata (Optional[Dict[str, str]])

• name (Optional[str])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

Storage Object Parameters

These TypeDicts define parameters for storage object creation, listing, and downloading.

typeddict runloop_api_client.sdk._types.SDKObjectCreateParams

typing.TypedDict.

Optional Keys:

• content_type (Required[Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz']])

• name (Required[str])

• metadata (Optional[Dict[str, str]])

• ttl_ms (Optional[int])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

typeddict runloop_api_client.sdk._types.SDKObjectListParams

typing.TypedDict.

Optional Keys:

• content_type (Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz'])

• limit (int)

• name (str)

• search (str)

• starting_after (str)

• state (Literal['UPLOADING', 'READ_ONLY', 'DELETED', 'ERROR'])

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

typeddict runloop_api_client.sdk._types.SDKObjectDownloadParams

typing.TypedDict.

Optional Keys:

• duration_seconds (int)

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

Core Request Options

These TypeDicts define options for timeouts, idempotency, polling, and other low-level request configuration. All other TypeDicts in the SDK extend from one of these core types.

typeddict runloop_api_client.sdk._types.BaseRequestOptions

typing.TypedDict.

Optional Keys:

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

typeddict runloop_api_client.sdk._types.LongRequestOptions

typing.TypedDict.

Optional Keys:

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

class runloop_api_client.sdk._types.PollingConfig(interval_seconds=1.0, max_attempts=120, timeout_seconds=None)

Configuration for polling behavior

interval_seconds: float = 1.0

max_attempts: int = 120

timeout_seconds: Optional[float] = None

typeddict runloop_api_client.sdk._types.PollingRequestOptions

typing.TypedDict.

Optional Keys:

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

typeddict runloop_api_client.sdk._types.LongPollingRequestOptions

typing.TypedDict.

Optional Keys:

• extra_headers (Optional[Mapping[str, Union[str, Omit]]]) – Send extra headers

• extra_query (Optional[Mapping[str, object]]) – Add additional query parameters to the request

• extra_body (Optional[object]) – Add additional JSON properties to the request

• timeout (Union[float, Timeout, NotGiven, None]) – Override the client-level default timeout for this request, in seconds

• idempotency_key (Optional[str]) – Specify a custom idempotency key for this request

• polling_config (Optional[PollingConfig]) – Configuration for polling behavior

Base API Type Reference

typeddict runloop_api_client.types.shared_params.AfterIdle

typing.TypedDict.

Optional Keys:

• idle_time_seconds (Required[int]) – After idle_time_seconds, on_idle action will be taken.

• on_idle (Required[Literal['shutdown', 'suspend']]) – Action to take after Devbox becomes idle.

typeddict runloop_api_client.types.shared_params.AgentMountParameters

typing.TypedDict.

Optional Keys:

• agent_id (Required[Optional[str]]) – The ID of the agent to mount. Either agent_id or name must be set.

• agent_name (Required[Optional[str]]) – 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

• type (Required[Literal['agent_mount']])

• agent_path (Optional[str]) – Path to mount the agent on the Devbox. Required for git and object agents. Use absolute path (e.g., /home/user/agent)

• auth_token (Optional[str]) – Optional auth token for private repositories. Only used for git agents.

typeddict runloop_api_client.types.shared_params.AgentSource

typing.TypedDict.

Optional Keys:

• type (Required[str]) – Source type: npm, pip, object, or git

• git (Optional[Git]) – Git source configuration

• npm (Optional[Npm]) – NPM source configuration

• object (Optional[Object]) – Object store source configuration

• pip (Optional[Pip]) – Pip source configuration

typeddict runloop_api_client.types.shared_params.CodeMountParameters

typing.TypedDict.

Optional Keys:

• repo_name (Required[str]) – The name of the repo to mount. By default, code will be mounted at /home/user/{repo_name}s.

• repo_owner (Required[str]) – The owner of the repo.

• type (Required[Literal['code_mount']])

• token (Optional[str]) – The authentication token necessary to pull repo.

• install_command (Optional[str]) – Installation command to install and setup repository.

typeddict runloop_api_client.types.shared_params.LaunchParameters

typing.TypedDict.

Optional Keys:

• after_idle (Optional[AfterIdle]) – Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds.

• architecture (Optional[Literal['x86_64', 'arm64']]) – The target architecture for the Devbox. If unset, defaults to arm64.

• available_ports (Optional[Iterable[int]]) – A list of ports to make available on the Devbox. Only ports made available will be surfaced to create tunnels via the ‘createTunnel’ API.

• custom_cpu_cores (Optional[int]) – custom resource size, number of cpu cores, must be multiple of 2. Min is 1, max is 16.

• custom_disk_size (Optional[int]) – custom disk size, number in GiB, must be a multiple of 2. Min is 2GiB, max is 64GiB.

• custom_gb_memory (Optional[int]) – custom memory size, number in GiB, must be a multiple of 2. Min is 2GiB, max is 64GiB.

• keep_alive_time_seconds (Optional[int]) – Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds).

• launch_commands (Optional[Sequence[str]]) – Set of commands to be run at launch time, before the entrypoint process is run.

• required_services (Optional[Sequence[str]]) – A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started.

• resource_size_request (Optional[Literal['X_SMALL', 'SMALL', 'MEDIUM', 'LARGE', 'X_LARGE', 'XX_LARGE', 'CUSTOM_SIZE']]) – Manual resource configuration for Devbox. If not set, defaults will be used.

• user_parameters (Optional[UserParameters]) – Specify the user for execution on Devbox. If not set, default user will be used.

typeddict runloop_api_client.types.shared_params.ObjectMountParameters

typing.TypedDict.

Optional Keys:

• object_id (Required[str]) – The ID of the object to write.

• object_path (Required[str]) – 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)

• type (Required[Literal['object_mount']])

typeddict runloop_api_client.types.shared_params.RunProfile

typing.TypedDict.

Optional Keys:

• env_vars (Optional[Dict[str, str]]) – 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’.

• launch_parameters (Optional[LaunchParameters]) – Additional runtime LaunchParameters to apply after the devbox starts.

• purpose (Optional[str]) – Purpose of the run.

• secrets (Optional[Dict[str, str]]) – 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’.

class runloop_api_client.types.AfterIdle(**data)

idle_time_seconds: int

After idle_time_seconds, on_idle action will be taken.

on_idle: Literal['shutdown', 'suspend']

Action to take after Devbox becomes idle.

typeddict runloop_api_client.types.AgentCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The name of the Agent.

• source (Optional[AgentSource]) – The source configuration for the Agent.

typeddict runloop_api_client.types.AgentListParams

typing.TypedDict.

Optional Keys:

• is_public (bool) – Filter agents by public visibility.

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter agents by name (partial match supported).

• search (str) – Search by agent ID or name.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

class runloop_api_client.types.AgentListView(**data)

agents: List[AgentView]

The list of Agents.

has_more: bool

Whether there are more Agents to fetch.

remaining_count: int

The count of remaining Agents.

total_count: int

The total count of Agents.

class runloop_api_client.types.AgentMountParameters(**data)

agent_id: Optional[str]

The ID of the agent to mount. Either agent_id or name must be set.

agent_name: Optional[str]

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_path: Optional[str]

Path to mount the agent on the Devbox.

Required for git and object agents. Use absolute path (e.g., /home/user/agent)

auth_token: Optional[str]

Optional auth token for private repositories. Only used for git agents.

type: Literal['agent_mount']

class runloop_api_client.types.AgentSource(**data)

git: Optional[Git]

Git source configuration

npm: Optional[Npm]

NPM source configuration

object: Optional[Object]

Object store source configuration

pip: Optional[Pip]

Pip source configuration

type: str

npm, pip, object, or git

Type:

Source type

class runloop_api_client.types.AgentView(**data)

create_time_ms: int

The creation time of the Agent (Unix timestamp milliseconds).

id: str

The unique identifier of the Agent.

is_public: bool

Whether the Agent is publicly accessible.

name: str

The name of the Agent.

source: Optional[AgentSource]

The source configuration for the Agent.

typeddict runloop_api_client.types.BenchmarkCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The name of the Benchmark. This must be unique.

• attribution (Optional[str]) – Attribution information for the benchmark.

• description (Optional[str]) – Detailed description of the benchmark.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the benchmark for organization.

• required_environment_variables (Optional[Sequence[str]]) – Environment variables required to run the benchmark. If any required variables are not supplied, the benchmark will fail to start

• required_secret_names (Sequence[str]) – Secrets required to run the benchmark with (environment variable name will be mapped to the your user secret by name). If any of these secrets are not provided or the mapping is incorrect, the benchmark will fail to start.

• scenario_ids (Optional[Sequence[str]]) – The Scenario IDs that make up the Benchmark.

typeddict runloop_api_client.types.BenchmarkDefinitionsParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

typeddict runloop_api_client.types.BenchmarkListParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

typeddict runloop_api_client.types.BenchmarkListPublicParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

class runloop_api_client.types.BenchmarkRunListView(**data)

has_more: bool

remaining_count: int

runs: List[BenchmarkRunView]

List of BenchmarkRuns matching filter.

total_count: int

class runloop_api_client.types.BenchmarkRunView(**data)

benchmark_id: str

The ID of the Benchmark.

duration_ms: Optional[int]

The duration for the BenchmarkRun to complete.

environment_variables: Optional[Dict[str, str]]

Environment variables used to run the benchmark.

id: str

The ID of the BenchmarkRun.

metadata: Dict[str, str]

User defined metadata to attach to the benchmark run for organization.

name: Optional[str]

The name of the BenchmarkRun.

purpose: Optional[str]

Purpose of the run.

score: Optional[float]

The final score across the BenchmarkRun, present once completed.

Calculated as sum of scenario scores / number of scenario runs.

secrets_provided: Optional[Dict[str, str]]

User secrets used to run the benchmark.

Example: {“DB_PASS”: “DATABASE_PASSWORD”} would set the environment variable ‘DB_PASS’ on all scenario devboxes to the value of the secret ‘DATABASE_PASSWORD’.

start_time_ms: int

The time the benchmark run execution started (Unix timestamp milliseconds).

state: Literal['running', 'canceled', 'completed']

The state of the BenchmarkRun.

typeddict runloop_api_client.types.BenchmarkStartRunParams

typing.TypedDict.

Optional Keys:

• benchmark_id (Required[str]) – ID of the Benchmark to run.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the benchmark run for organization.

• run_name (Optional[str]) – Display name of the run.

• run_profile (Optional[RunProfile]) – Runtime configuration to use for this benchmark run

typeddict runloop_api_client.types.BenchmarkUpdateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The name of the Benchmark. This must be unique.

• attribution (Optional[str]) – Attribution information for the benchmark.

• description (Optional[str]) – Detailed description of the benchmark.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the benchmark for organization.

• required_environment_variables (Optional[Sequence[str]]) – Environment variables required to run the benchmark. If any required variables are not supplied, the benchmark will fail to start

• required_secret_names (Sequence[str]) – Secrets required to run the benchmark with (environment variable name will be mapped to the your user secret by name). If any of these secrets are not provided or the mapping is incorrect, the benchmark will fail to start.

• scenario_ids (Optional[Sequence[str]]) – The Scenario IDs that make up the Benchmark.

class runloop_api_client.types.BenchmarkView(**data)

attribution: Optional[str]

Attribution information for the benchmark.

description: Optional[str]

Detailed description of the benchmark.

id: str

The ID of the Benchmark.

is_public: Optional[bool]

Whether this benchmark is public.

metadata: Dict[str, str]

User defined metadata to attach to the benchmark for organization.

name: str

The name of the Benchmark.

required_environment_variables: Optional[List[str]]

Required environment variables used to run the benchmark.

If any required environment variables are missing, the benchmark will fail to start.

required_secret_names: Optional[List[str]]

Required secrets used to run the benchmark.

If any required secrets are missing, the benchmark will fail to start.

scenario_ids: List[str]

List of Scenario IDs that make up the benchmark.

class runloop_api_client.types.BlueprintBuildLog(**data)

level: str

Log line severity level.

message: str

Log line message.

timestamp_ms: int

Time of log (Unix timestamp milliseconds).

class runloop_api_client.types.BlueprintBuildLogsListView(**data)

blueprint_id: str

ID of the Blueprint.

logs: List[BlueprintBuildLog]

List of logs generated during Blueprint build.

class runloop_api_client.types.BlueprintBuildParameters(**data)

base_blueprint_id: Optional[str]

(Optional) ID of previously built blueprint to use as a base blueprint for this build.

base_blueprint_name: Optional[str]

(Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.

build_args: Optional[Dict[str, str]]

(Optional) Arbitrary Docker build args to pass during build.

build_context: Optional[BuildContext]

A build context backed by an Object.

code_mounts: Optional[List[CodeMountParameters]]

A list of code mounts to be included in the Blueprint.

dockerfile: Optional[str]

Dockerfile contents to be used to build the Blueprint.

file_mounts: Optional[Dict[str, str]]

(Optional) Map of paths and file contents to write before setup.

launch_parameters: Optional[LaunchParameters]

Parameters to configure your Devbox at launch time.

metadata: Optional[Dict[str, str]]

(Optional) User defined metadata for the Blueprint.

name: str

Name of the Blueprint.

named_build_contexts: Optional[Dict[str, NamedBuildContexts]]

(Optional) Map of named build contexts to attach to the Blueprint build, where the keys are the name used when referencing the contexts in a Dockerfile. See Docker buildx additional contexts for details: https://docs.docker.com/reference/cli/docker/buildx/build/#build-context

secrets: Optional[Dict[str, str]]

(Optional) Map of mount IDs/environment variable names to secret names.

Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {“DB_PASS”: “DATABASE_PASSWORD”} makes the secret ‘DATABASE_PASSWORD’ available as environment variable ‘DB_PASS’.

services: Optional[List[Service]]

(Optional) List of containerized services to include in the Blueprint.

These services will be pre-pulled during the build phase for optimized startup performance.

system_setup_commands: Optional[List[str]]

A list of commands to run to set up your system.

typeddict runloop_api_client.types.BlueprintCreateFromInspectionParams

typing.TypedDict.

Optional Keys:

• inspection_source (Required[InspectionSourceParam]) – (Optional) Use a RepositoryInspection a source of a Blueprint build. The Dockerfile will be automatically created based on the RepositoryInspection contents.

• name (Required[str]) – Name of the Blueprint.

• file_mounts (Optional[Dict[str, str]]) – (Optional) Map of paths and file contents to write before setup.

• launch_parameters (Optional[LaunchParameters]) – Parameters to configure your Devbox at launch time.

• metadata (Optional[Dict[str, str]]) – (Optional) User defined metadata for the Blueprint.

• secrets (Optional[Dict[str, str]]) – (Optional) Map of mount IDs/environment variable names to secret names. Secrets can be used as environment variables in system_setup_commands. Example: {“GITHUB_TOKEN”: “gh_secret”} makes ‘gh_secret’ available as GITHUB_TOKEN.

• system_setup_commands (Optional[Sequence[str]]) – A list of commands to run to set up your system.

typeddict runloop_api_client.types.BlueprintCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The name of the container service.

• base_blueprint_id (Optional[str]) – (Optional) ID of previously built blueprint to use as a base blueprint for this build.

• base_blueprint_name (Optional[str]) – (Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.

• build_args (Optional[Dict[str, str]]) – (Optional) Arbitrary Docker build args to pass during build.

• build_context (Optional[BuildContext]) – A build context backed by an Object.

• code_mounts (Optional[Iterable[CodeMountParameters]]) – A list of code mounts to be included in the Blueprint.

• dockerfile (Optional[str]) – Dockerfile contents to be used to build the Blueprint.

• file_mounts (Optional[Dict[str, str]]) – (Optional) Map of paths and file contents to write before setup.

• launch_parameters (Optional[LaunchParameters]) – Parameters to configure your Devbox at launch time.

• metadata (Optional[Dict[str, str]]) – (Optional) User defined metadata for the Blueprint.

• named_build_contexts (Optional[Dict[str, NamedBuildContexts]]) – (Optional) Map of named build contexts to attach to the Blueprint build, where the keys are the name used when referencing the contexts in a Dockerfile. See Docker buildx additional contexts for details: https://docs.docker.com/reference/cli/docker/buildx/build/#build-context

• secrets (Optional[Dict[str, str]]) – (Optional) Map of mount IDs/environment variable names to secret names. Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {“DB_PASS”: “DATABASE_PASSWORD”} makes the secret ‘DATABASE_PASSWORD’ available as environment variable ‘DB_PASS’.

• services (Optional[Iterable[Service]]) – (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance.

• system_setup_commands (Optional[Sequence[str]]) – A list of commands to run to set up your system.

typeddict runloop_api_client.types.BlueprintListParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter by name

• starting_after (str) – Load the next page of data starting after the item with the given ID.

typeddict runloop_api_client.types.BlueprintListPublicParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter by name

• starting_after (str) – Load the next page of data starting after the item with the given ID.

class runloop_api_client.types.BlueprintListView(**data)

blueprints: List[BlueprintView]

List of blueprints matching filter.

has_more: bool

remaining_count: int

total_count: int

typeddict runloop_api_client.types.BlueprintPreviewParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The name of the container service.

• base_blueprint_id (Optional[str]) – (Optional) ID of previously built blueprint to use as a base blueprint for this build.

• base_blueprint_name (Optional[str]) – (Optional) Name of previously built blueprint to use as a base blueprint for this build. When set, this will load the latest successfully built Blueprint with the given name. Only one of (base_blueprint_id, base_blueprint_name) should be specified.

• build_args (Optional[Dict[str, str]]) – (Optional) Arbitrary Docker build args to pass during build.

• build_context (Optional[BuildContext]) – A build context backed by an Object.

• code_mounts (Optional[Iterable[CodeMountParameters]]) – A list of code mounts to be included in the Blueprint.

• dockerfile (Optional[str]) – Dockerfile contents to be used to build the Blueprint.

• file_mounts (Optional[Dict[str, str]]) – (Optional) Map of paths and file contents to write before setup.

• launch_parameters (Optional[LaunchParameters]) – Parameters to configure your Devbox at launch time.

• metadata (Optional[Dict[str, str]]) – (Optional) User defined metadata for the Blueprint.

• named_build_contexts (Optional[Dict[str, NamedBuildContexts]]) – (Optional) Map of named build contexts to attach to the Blueprint build, where the keys are the name used when referencing the contexts in a Dockerfile. See Docker buildx additional contexts for details: https://docs.docker.com/reference/cli/docker/buildx/build/#build-context

• secrets (Optional[Dict[str, str]]) – (Optional) Map of mount IDs/environment variable names to secret names. Secrets will be available to commands during the build. Secrets are NOT stored in the blueprint image. Example: {“DB_PASS”: “DATABASE_PASSWORD”} makes the secret ‘DATABASE_PASSWORD’ available as environment variable ‘DB_PASS’.

• services (Optional[Iterable[Service]]) – (Optional) List of containerized services to include in the Blueprint. These services will be pre-pulled during the build phase for optimized startup performance.

• system_setup_commands (Optional[Sequence[str]]) – A list of commands to run to set up your system.

class runloop_api_client.types.BlueprintPreviewView(**data)

dockerfile: str

The Dockerfile contents that will built.

class runloop_api_client.types.BlueprintView(**data)

base_blueprint_id: Optional[str]

The ID of the base Blueprint.

build_finish_time_ms: Optional[int]

Build completion time of the Blueprint (Unix timestamp milliseconds).

containerized_services: Optional[List[ContainerizedService]]

List of ContainerizedServices available in the Blueprint.

Services can be explicitly started when creating a Devbox.

create_time_ms: int

Creation time of the Blueprint (Unix timestamp milliseconds).

devbox_capabilities: Optional[List[Literal['unknown', 'computer_usage', 'browser_usage', 'docker_in_docker']]]

Capabilities that will be available on Devbox.

failure_reason: Optional[Literal['out_of_memory', 'out_of_disk', 'build_failed']]

The failure reason if the Blueprint build failed, if any.

id: str

The id of the Blueprint.

is_public: Optional[bool]

Whether this Blueprint is publicly accessible to all users.

metadata: Optional[Dict[str, str]]

User defined metadata associated with the blueprint.

name: str

The name of the Blueprint.

parameters: BlueprintBuildParameters

The parameters used to create Blueprint.

state: Literal['created', 'deleted']

The state of the Blueprint.

status: Literal['queued', 'provisioning', 'building', 'failed', 'build_complete']

The status of the Blueprint build.

class runloop_api_client.types.CodeMountParameters(**data)

install_command: Optional[str]

Installation command to install and setup repository.

repo_name: str

The name of the repo to mount.

By default, code will be mounted at /home/user/{repo_name}s.

repo_owner: str

The owner of the repo.

token: Optional[str]

The authentication token necessary to pull repo.

type: Literal['code_mount']

class runloop_api_client.types.DevboxAsyncExecutionDetailView(**data)

devbox_id: str

Devbox id where command was executed.

execution_id: str

Ephemeral id of the execution in progress.

exit_status: Optional[int]

Exit code of command execution.

This field will remain unset until the execution has completed.

shell_name: Optional[str]

Shell name.

status: Literal['queued', 'running', 'completed']

Current status of the execution.

stderr: Optional[str]

Standard error generated by command.

This field will remain unset until the execution has completed.

stderr_truncated: Optional[bool]

Indicates whether the stderr was truncated due to size limits.

stdout: Optional[str]

Standard out generated by command.

This field will remain unset until the execution has completed.

stdout_truncated: Optional[bool]

Indicates whether the stdout was truncated due to size limits.

typeddict runloop_api_client.types.DevboxCreateParams

typing.TypedDict.

Optional Keys:

• code_mounts (Optional[Iterable[CodeMountParameters]]) – A list of code mounts to be included in the Devbox.

• entrypoint (Optional[str]) – (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.

• environment_variables (Optional[Dict[str, str]]) – (Optional) Environment variables used to configure your Devbox.

• file_mounts (Optional[Dict[str, str]]) – (Optional) Map of paths and file contents to write before setup..

• launch_parameters (Optional[LaunchParameters]) – Parameters to configure the resources and launch time behavior of the Devbox.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the devbox for organization.

• mounts (Optional[Iterable[Union[ObjectMountParameters, AgentMountParameters, CodeMountParameters, FileMountParameters]]]) – A list of mounts to be included in the Devbox.

• name (Optional[str]) – (Optional) A user specified name to give the Devbox.

• repo_connection_id (Optional[str]) – Repository connection id the devbox should source its base image from.

• secrets (Optional[Dict[str, str]]) – (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’.

• blueprint_id (Optional[str]) – 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_name (Optional[str]) – 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.

• snapshot_id (Optional[str]) – Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.

class runloop_api_client.types.DevboxCreateSSHKeyResponse(**data)

id: str

The ID of the Devbox.

ssh_private_key: str

The ssh private key, in PEM format.

url: str

The host url of the Devbox that can be used for SSH.

typeddict runloop_api_client.types.DevboxCreateTunnelParams

typing.TypedDict.

Optional Keys:

• port (Required[int]) – Devbox port that tunnel will expose.

typeddict runloop_api_client.types.DevboxDownloadFileParams

typing.TypedDict.

Optional Keys:

• path (Required[str]) – The path on the Devbox filesystem to read the file from. Path is relative to user home directory.

typeddict runloop_api_client.types.DevboxExecuteAsyncParams

typing.TypedDict.

Optional Keys:

• command (Required[str]) – The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell.

• attach_stdin (Optional[bool]) – Whether to attach stdin streaming for async commands. Not valid for execute_sync endpoint. Defaults to false if not specified.

• shell_name (Optional[str]) – The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.

typeddict runloop_api_client.types.DevboxExecuteParams

typing.TypedDict.

Optional Keys:

• command (Required[str]) – The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell.

• command_id (Required[str]) – The command ID in UUIDv7 string format for idempotency and tracking

• last_n (str) – Last n lines of standard error / standard out to return (default: 100)

• optimistic_timeout (Optional[int]) – Timeout in seconds to wait for command completion. Operation is not killed. Max is 600 seconds.

• shell_name (Optional[str]) – The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.

typeddict runloop_api_client.types.DevboxExecuteSyncParams

typing.TypedDict.

Optional Keys:

• command (Required[str]) – The command to execute via the Devbox shell. By default, commands are run from the user home directory unless shell_name is specified. If shell_name is specified the command is run from the directory based on the recent state of the persistent shell.

• attach_stdin (Optional[bool]) – Whether to attach stdin streaming for async commands. Not valid for execute_sync endpoint. Defaults to false if not specified.

• shell_name (Optional[str]) – The name of the persistent shell to create or use if already created. When using a persistent shell, the command will run from the directory at the end of the previous command and environment variables will be preserved.

class runloop_api_client.types.DevboxExecutionDetailView(**data)

devbox_id: str

Devbox id where command was executed.

exit_status: int

Exit status of command execution.

shell_name: Optional[str]

Shell name.

stderr: str

Standard error generated by command.

stdout: str

Standard out generated by command.

typeddict runloop_api_client.types.DevboxListDiskSnapshotsParams

typing.TypedDict.

Optional Keys:

• devbox_id (str) – Devbox ID to filter by.

• limit (int) – The limit of items to return. Default is 20.

• metadata_key (str) – Filter snapshots by metadata key-value pair. Can be used multiple times for different keys.

• metadata_key_in (str) – Filter snapshots by metadata key with multiple possible values (OR condition).

• source_blueprint_id (str) – Source Blueprint ID to filter snapshots by.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

typeddict runloop_api_client.types.DevboxListParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

• status (Literal['provisioning', 'initializing', 'running', 'suspending', 'suspended', 'resuming', 'failure', 'shutdown']) – Filter by status

class runloop_api_client.types.DevboxListView(**data)

devboxes: List[DevboxView]

List of devboxes matching filter.

has_more: bool

remaining_count: int

total_count: int

typeddict runloop_api_client.types.DevboxReadFileContentsParams

typing.TypedDict.

Optional Keys:

• file_path (Required[str]) – The path on the Devbox filesystem to read the file from. Path is relative to user home directory.

runloop_api_client.types.DevboxReadFileContentsResponse

alias of str

typeddict runloop_api_client.types.DevboxRemoveTunnelParams

typing.TypedDict.

Optional Keys:

• port (Required[int]) – Devbox port that tunnel will expose.

class runloop_api_client.types.DevboxSendStdInResult(**data)

devbox_id: str

Devbox id where command is executing.

execution_id: str

Execution id that received the stdin.

success: bool

Whether the stdin was successfully sent.

typeddict runloop_api_client.types.DevboxSnapshotDiskAsyncParams

typing.TypedDict.

Optional Keys:

• commit_message (Optional[str]) – (Optional) Commit message associated with the snapshot (max 1000 characters)

• metadata (Optional[Dict[str, str]]) – (Optional) Metadata used to describe the snapshot

• name (Optional[str]) – (Optional) A user specified name to give the snapshot

typeddict runloop_api_client.types.DevboxSnapshotDiskParams

typing.TypedDict.

Optional Keys:

• commit_message (Optional[str]) – (Optional) Commit message associated with the snapshot (max 1000 characters)

• metadata (Optional[Dict[str, str]]) – (Optional) Metadata used to describe the snapshot

• name (Optional[str]) – (Optional) A user specified name to give the snapshot

class runloop_api_client.types.DevboxSnapshotListView(**data)

has_more: bool

remaining_count: int

snapshots: List[DevboxSnapshotView]

List of snapshots matching filter.

total_count: int

class runloop_api_client.types.DevboxSnapshotView(**data)

commit_message: Optional[str]

(Optional) The commit message of the snapshot (max 1000 characters).

create_time_ms: int

Creation time of the Snapshot (Unix timestamp milliseconds).

id: str

The unique identifier of the snapshot.

metadata: Dict[str, str]

User defined metadata associated with the snapshot.

name: Optional[str]

(Optional) The custom name of the snapshot.

source_blueprint_id: Optional[str]

(Optional) The source Blueprint ID this snapshot was created from.

source_devbox_id: str

The source Devbox ID this snapshot was created from.

class runloop_api_client.types.DevboxTunnelView(**data)

devbox_id: str

ID of the Devbox the tunnel routes to.

port: int

Port of the Devbox the tunnel routes to.

url: str

Public url used to access Devbox.

typeddict runloop_api_client.types.DevboxUpdateParams

typing.TypedDict.

Optional Keys:

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the devbox for organization.

• name (Optional[str]) – (Optional) A user specified name to give the Devbox.

typeddict runloop_api_client.types.DevboxUploadFileParams

typing.TypedDict.

Optional Keys:

• path (Required[str]) – The path to write the file to on the Devbox. Path is relative to user home directory.

• file (Union[IO[bytes], bytes, PathLike, Tuple[Optional[str], Union[IO[bytes], bytes, PathLike]], Tuple[Optional[str], Union[IO[bytes], bytes, PathLike], Optional[str]], Tuple[Optional[str], Union[IO[bytes], bytes, PathLike], Optional[str], Mapping[str, str]]])

class runloop_api_client.types.DevboxView(**data)

blueprint_id: Optional[str]

The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.

capabilities: List[Literal['unknown', 'computer_usage', 'browser_usage', 'docker_in_docker']]

A list of capability groups this devbox has access to.

This allows devboxes to be compatible with certain tools sets like computer usage APIs.

create_time_ms: int

Creation time of the Devbox (Unix timestamp milliseconds).

end_time_ms: Optional[int]

The time the Devbox finished execution (Unix timestamp milliseconds).

Present if the Devbox is in a terminal state.

failure_reason: Optional[Literal['out_of_memory', 'out_of_disk', 'execution_failed']]

The failure reason if the Devbox failed, if the Devbox has a ‘failure’ status.

id: str

The ID of the Devbox.

initiator_id: Optional[str]

The ID of the initiator that created the Devbox.

initiator_type: Optional[Literal['unknown', 'api', 'scenario']]

The type of initiator that created the Devbox.

launch_parameters: LaunchParameters

The launch parameters used to create the Devbox.

metadata: Dict[str, str]

The user defined Devbox metadata.

name: Optional[str]

The name of the Devbox.

shutdown_reason: Optional[Literal['api_shutdown', 'keep_alive_timeout', 'entrypoint_exit', 'idle']]

The shutdown reason if the Devbox shutdown, if the Devbox has a ‘shutdown’ status.

snapshot_id: Optional[str]

The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.

state_transitions: List[StateTransition]

A list of state transitions in order with durations

status: Literal['provisioning', 'initializing', 'running', 'suspending', 'suspended', 'resuming', 'failure', 'shutdown']

The current status of the Devbox.

typeddict runloop_api_client.types.DevboxWaitForCommandParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

• statuses (Required[List[Literal['queued', 'running', 'completed']]]) – 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.

• last_n (str) – Last n lines of standard error / standard out to return (default: 100)

• timeout_seconds (Optional[int]) – (Optional) Timeout in seconds to wait for the status, up to 60 seconds. Defaults to 60 seconds.

typeddict runloop_api_client.types.DevboxWriteFileContentsParams

typing.TypedDict.

Optional Keys:

• contents (Required[str]) – The UTF-8 string contents to write to the file.

• file_path (Required[str]) – The path to write the file to on the Devbox. Path is relative to user home directory.

class runloop_api_client.types.InputContext(**data)

additional_context: Optional[object]

Additional JSON structured input context.

problem_statement: str

The problem statement for the Scenario.

typeddict runloop_api_client.types.InputContextParam

typing.TypedDict.

Optional Keys:

• problem_statement (Required[str]) – The problem statement for the Scenario.

• additional_context (Optional[object]) – Additional JSON structured input context.

typeddict runloop_api_client.types.InputContextUpdateParam

typing.TypedDict.

Optional Keys:

• additional_context (Optional[object]) – Additional JSON structured input context.

• problem_statement (Optional[str]) – The problem statement for the Scenario.

typeddict runloop_api_client.types.InspectionSourceParam

typing.TypedDict.

Optional Keys:

• inspection_id (Required[str]) – The ID of a repository inspection.

• github_auth_token (Optional[str]) – GitHub authentication token for accessing private repositories.

class runloop_api_client.types.LaunchParameters(**data)

after_idle: Optional[AfterIdle]

Configure Devbox lifecycle based on idle activity.

If after_idle is set, Devbox will ignore keep_alive_time_seconds.

architecture: Optional[Literal['x86_64', 'arm64']]

The target architecture for the Devbox. If unset, defaults to arm64.

available_ports: Optional[List[int]]

A list of ports to make available on the Devbox.

Only ports made available will be surfaced to create tunnels via the ‘createTunnel’ API.

custom_cpu_cores: Optional[int]

custom resource size, number of cpu cores, must be multiple of 2.

Min is 1, max is 16.

custom_disk_size: Optional[int]

custom disk size, number in GiB, must be a multiple of 2.

Min is 2GiB, max is 64GiB.

custom_gb_memory: Optional[int]

custom memory size, number in GiB, must be a multiple of 2.

Min is 2GiB, max is 64GiB.

keep_alive_time_seconds: Optional[int]

Time in seconds after which Devbox will automatically shutdown.

Default is 1 hour. Maximum is 48 hours (172800 seconds).

launch_commands: Optional[List[str]]

Set of commands to be run at launch time, before the entrypoint process is run.

required_services: Optional[List[str]]

A list of ContainerizedService names to be started when a Devbox is created.

A valid ContainerizedService must be specified in Blueprint to be started.

resource_size_request: Optional[Literal['X_SMALL', 'SMALL', 'MEDIUM', 'LARGE', 'X_LARGE', 'XX_LARGE', 'CUSTOM_SIZE']]

Manual resource configuration for Devbox. If not set, defaults will be used.

user_parameters: Optional[UserParameters]

Specify the user for execution on Devbox.

If not set, default user will be used.

typeddict runloop_api_client.types.ObjectCreateParams

typing.TypedDict.

Optional Keys:

• content_type (Required[Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz']]) – The content type of the Object.

• name (Required[str]) – The name of the Object.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the object for organization.

• ttl_ms (Optional[int]) – Optional lifetime of the object in milliseconds, after which the object is automatically deleted. Time starts ticking after the object is created.

typeddict runloop_api_client.types.ObjectDownloadParams

typing.TypedDict.

Optional Keys:

• duration_seconds (int) – Duration in seconds for the presigned URL validity (default: 3600).

class runloop_api_client.types.ObjectDownloadURLView(**data)

download_url: str

The presigned download URL for the Object.

typeddict runloop_api_client.types.ObjectListParams

typing.TypedDict.

Optional Keys:

• content_type (Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz']) – Filter storage objects by content type.

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter storage objects by name (partial match supported).

• search (str) – Search by object ID or name.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

• state (Literal['UPLOADING', 'READ_ONLY', 'DELETED', 'ERROR']) – Filter storage objects by state.

typeddict runloop_api_client.types.ObjectListPublicParams

typing.TypedDict.

Optional Keys:

• content_type (Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz']) – Filter storage objects by content type.

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter storage objects by name (partial match supported).

• search (str) – Search by object ID or name.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

• state (Literal['UPLOADING', 'READ_ONLY', 'DELETED', 'ERROR']) – Filter storage objects by state.

class runloop_api_client.types.ObjectListView(**data)

has_more: bool

True if there are more results available beyond this page.

objects: List[ObjectView]

List of Object entities.

remaining_count: int

Number of Objects remaining after this page.

total_count: int

Total number of Objects across all pages.

class runloop_api_client.types.ObjectMountParameters(**data)

object_id: str

The ID of the object to write.

object_path: str

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)

type: Literal['object_mount']

class runloop_api_client.types.ObjectView(**data)

content_type: Literal['unspecified', 'text', 'binary', 'gzip', 'tar', 'tgz']

The content type of the Object.

create_time_ms: int

The creation time of the Object in milliseconds since epoch.

delete_after_time_ms: Optional[int]

The time after which the Object will be deleted in milliseconds since epoch.

id: str

The unique identifier of the Object.

name: str

The name of the Object.

size_bytes: Optional[int]

The size of the Object content in bytes (null until uploaded).

state: Literal['UPLOADING', 'READ_ONLY', 'DELETED', 'ERROR']

The current state of the Object.

upload_url: Optional[str]

Presigned URL for uploading content to S3 (only present on create).

class runloop_api_client.types.RepositoryConnectionListView(**data)

has_more: bool

remaining_count: int

repositories: List[RepositoryConnectionView]

List of repositories matching filter.

total_count: int

class runloop_api_client.types.RepositoryConnectionView(**data)

id: str

The ID of the Repository.

name: str

The name of the Repository.

owner: str

The account owner of the Repository.

typeddict runloop_api_client.types.RepositoryCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – Name of the repository.

• owner (Required[str]) – Account owner of the repository.

• blueprint_id (Optional[str]) – ID of blueprint to use as base for resulting RepositoryVersion blueprint.

• github_auth_token (Optional[str]) – GitHub authentication token for accessing private repositories.

typeddict runloop_api_client.types.RepositoryInspectParams

typing.TypedDict.

Optional Keys:

• github_auth_token (Optional[str]) – GitHub authentication token for accessing private repositories.

class runloop_api_client.types.RepositoryInspectionDetails(**data)

blueprint_id: Optional[str]

The blueprint ID associated with this inspection if successful.

blueprint_name: Optional[str]

The blueprint name associated with this inspection if successful.

build_status: Optional[Literal['image_building', 'image_build_success', 'image_build_failure']]

The status of the linked Blueprint build.

commit_sha: str

The sha of the inspected version of the Repository.

id: str

The ID of the inspection.

inspected_at: int

Inspection time of the Repository Version (Unix timestamp milliseconds).

repository_manifest: RepositoryManifestView

Repository manifest containing container config and workspace details.

status: Literal['invalid', 'repo_auth_pending', 'repo_authentication_failure', 'repo_access_failure', 'inspection_pending', 'inspection_failed', 'inspection_success', 'inspection_user_manifest_added']

The status of the repository inspection.

user_manifest: Optional[RepositoryManifestView]

User uploaded repository manifest containing container config and workspace details.

workflow_contexts: Optional[Dict[str, WorkflowContexts]]

Workflow contexts mapping workflow names to their processing details.

class runloop_api_client.types.RepositoryInspectionListView(**data)

inspections: List[RepositoryInspectionDetails]

List of inspections for this repository.

typeddict runloop_api_client.types.RepositoryListParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Filter by repository name

• owner (str) – Filter by repository owner

• starting_after (str) – Load the next page of data starting after the item with the given ID.

class runloop_api_client.types.RepositoryManifestView(**data)

container_config: ContainerConfig

Container configuration specifying the base image and setup commands.

containerized_services: Optional[List[ContainerizedService]]

List of discovered ContainerizedServices.

Services can be explicitly started when creating a Devbox.

env_vars: Optional[Dict[str, str]]

Qualified environment variables and values that should be set for this repository to run correctly.

languages: List[Language]

List of required languages found in Repository.

required_env_vars: Optional[List[str]]

Missing environment variables that (may) be required for this repository to run correctly.

workspaces: List[Workspace]

List of workspaces within the repository.

Each workspace represents a buildable unit of code.

typeddict runloop_api_client.types.RepositoryRefreshParams

typing.TypedDict.

Optional Keys:

• blueprint_id (Optional[str]) – ID of blueprint to use as base for resulting RepositoryVersion blueprint.

• github_auth_token (Optional[str]) – GitHub authentication token for accessing private repositories.

class runloop_api_client.types.RunProfile(**data)

env_vars: Optional[Dict[str, str]]

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

launch_parameters: Optional[LaunchParameters]

Additional runtime LaunchParameters to apply after the devbox starts.

purpose: Optional[str]

Purpose of the run.

secrets: Optional[Dict[str, str]]

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

typeddict runloop_api_client.types.ScenarioCreateParams

typing.TypedDict.

Optional Keys:

• input_context (Required[InputContextParam]) – The input context for the Scenario.

• name (Required[str]) – Name of the scenario.

• scoring_contract (Required[ScoringContractParam]) – The scoring contract for the Scenario.

• environment_parameters (Optional[ScenarioEnvironmentParam]) – The Environment in which the Scenario will run.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the scenario for organization.

• reference_output (Optional[str]) – A string representation of the reference output to solve the scenario. Commonly can be the result of a git diff or a sequence of command actions to apply to the environment.

• required_environment_variables (Optional[Sequence[str]]) – Environment variables required to run the scenario. If these variables are not provided, the scenario will fail to start.

• required_secret_names (Optional[Sequence[str]]) – Secrets required to run the scenario (user secret name to scenario required secret name). If these secrets are not provided or the mapping is incorrect, the scenario will fail to start.

• validation_type (Optional[Literal['UNSPECIFIED', 'FORWARD', 'REVERSE', 'EVALUATION']]) – Validation strategy.

class runloop_api_client.types.ScenarioDefinitionListView(**data)

has_more: bool

remaining_count: int

scenarios: List[ScenarioView]

List of Scenarios matching filter.

total_count: int

class runloop_api_client.types.ScenarioEnvironment(**data)

blueprint_id: Optional[str]

Use the blueprint with matching ID.

launch_parameters: Optional[LaunchParameters]

Optional launch parameters to apply to the devbox environment at launch.

snapshot_id: Optional[str]

Use the snapshot with matching ID.

working_directory: Optional[str]

The working directory where the agent is expected to fulfill the scenario.

Scoring functions also run from the working directory.

typeddict runloop_api_client.types.ScenarioEnvironmentParam

typing.TypedDict.

Optional Keys:

• blueprint_id (Optional[str]) – Use the blueprint with matching ID.

• launch_parameters (Optional[LaunchParameters]) – Optional launch parameters to apply to the devbox environment at launch.

• snapshot_id (Optional[str]) – Use the snapshot with matching ID.

• working_directory (Optional[str]) – The working directory where the agent is expected to fulfill the scenario. Scoring functions also run from the working directory.

typeddict runloop_api_client.types.ScenarioListParams

typing.TypedDict.

Optional Keys:

• benchmark_id (str) – Filter scenarios by benchmark ID.

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Query for Scenarios with a given name.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

typeddict runloop_api_client.types.ScenarioListPublicParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

• name (str) – Query for Scenarios with a given name.

• starting_after (str) – Load the next page of data starting after the item with the given ID.

class runloop_api_client.types.ScenarioRunListView(**data)

has_more: bool

remaining_count: int

runs: List[ScenarioRunView]

List of ScenarioRuns matching filter.

total_count: int

class runloop_api_client.types.ScenarioRunView(**data)

benchmark_run_id: Optional[str]

ID of the BenchmarkRun that this Scenario is associated with, if any.

devbox_id: str

ID of the Devbox on which the Scenario is running.

duration_ms: Optional[int]

Duration scenario took to run.

environment_variables: Optional[Dict[str, str]]

Environment variables used to run the scenario.

id: str

ID of the ScenarioRun.

metadata: Dict[str, str]

User defined metadata to attach to the scenario run for organization.

name: Optional[str]

Optional name of ScenarioRun.

purpose: Optional[str]

Purpose of the ScenarioRun.

scenario_id: str

ID of the Scenario that has been run.

scoring_contract_result: Optional[ScoringContractResultView]

The scoring result of the ScenarioRun.

secrets_provided: Optional[Dict[str, str]]

User secrets used to run the scenario.

start_time_ms: Optional[int]

The time that the scenario started

state: Literal['running', 'scoring', 'scored', 'completed', 'canceled', 'timeout', 'failed']

The state of the ScenarioRun.

typeddict runloop_api_client.types.ScenarioStartRunParams

typing.TypedDict.

Optional Keys:

• scenario_id (Required[str]) – ID of the Scenario to run.

• benchmark_run_id (Optional[str]) – Benchmark to associate the run.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the run for organization.

• run_name (Optional[str]) – Display name of the run.

• run_profile (Optional[RunProfile]) – Runtime configuration to use for this benchmark run

typeddict runloop_api_client.types.ScenarioUpdateParams

typing.TypedDict.

Optional Keys:

• environment_parameters (Optional[ScenarioEnvironmentParam]) – The Environment in which the Scenario will run.

• input_context (Optional[InputContextUpdateParam]) – The input context for the Scenario.

• metadata (Optional[Dict[str, str]]) – User defined metadata to attach to the scenario for organization.

• name (Optional[str]) – Name of the scenario.

• reference_output (Optional[str]) – A string representation of the reference output to solve the scenario. Commonly can be the result of a git diff or a sequence of command actions to apply to the environment.

• required_environment_variables (Optional[Sequence[str]]) – Environment variables required to run the scenario.

• required_secret_names (Optional[Sequence[str]]) – Secrets required to run the scenario.

• scoring_contract (Optional[ScoringContractUpdateParam]) – The scoring contract for the Scenario.

• validation_type (Optional[Literal['UNSPECIFIED', 'FORWARD', 'REVERSE', 'EVALUATION']]) – Validation strategy.

class runloop_api_client.types.ScenarioView(**data)

environment: Optional[ScenarioEnvironment]

The Environment in which the Scenario is run.

id: str

The ID of the Scenario.

input_context: InputContext

The input context for the Scenario.

is_public: Optional[bool]

Whether this scenario is public.

metadata: Dict[str, str]

User defined metadata to attach to the scenario for organization.

name: str

The name of the Scenario.

reference_output: Optional[str]

A string representation of the reference output to solve the scenario.

Commonly can be the result of a git diff or a sequence of command actions to apply to the environment.

required_environment_variables: Optional[List[str]]

Environment variables required to run the scenario.

If any required environment variables are missing, the scenario will fail to start.

required_secret_names: Optional[List[str]]

Environment variables required to run the scenario.

If any required secrets are missing, the scenario will fail to start.

scoring_contract: ScoringContract

The scoring contract for the Scenario.

validation_type: Optional[Literal['UNSPECIFIED', 'FORWARD', 'REVERSE', 'EVALUATION']]

Validation strategy.

class runloop_api_client.types.ScoringContract(**data)

scoring_function_parameters: List[ScoringFunction]

A list of scoring functions used to evaluate the Scenario.

typeddict runloop_api_client.types.ScoringContractParam

typing.TypedDict.

Optional Keys:

• scoring_function_parameters (Required[Iterable[ScoringFunctionParam]]) – A list of scoring functions used to evaluate the Scenario.

class runloop_api_client.types.ScoringContractResultView(**data)

score: float

Total score for all scoring contracts. This will be a value between 0 and 1.

scoring_function_results: List[ScoringFunctionResultView]

List of all individual scoring function results.

typeddict runloop_api_client.types.ScoringContractUpdateParam

typing.TypedDict.

Optional Keys:

• scoring_function_parameters (Optional[Iterable[ScoringFunctionParam]]) – A list of scoring functions used to evaluate the Scenario.

class runloop_api_client.types.ScoringFunction(**data)

name: str

Name of scoring function. Names must only contain [a-zA-Z0-9_-].

scorer: AnnotatedAlias[Union[ScorerAstGrepScoringFunction, ScorerBashScriptScoringFunction, ScorerCommandScoringFunction, ScorerCustomScoringFunction, ScorerPythonScriptScoringFunction, ScorerTestBasedScoringFunction]]

The scoring function to use for evaluating this scenario.

The type field determines which built-in function to use.

weight: float

Weight to apply to scoring function score.

Weights of all scoring functions should sum to 1.0.

typeddict runloop_api_client.types.ScoringFunctionParam

typing.TypedDict.

Optional Keys:

• name (Required[str]) – Name of scoring function. Names must only contain [a-zA-Z0-9_-].

• scorer (Required[Union[ScorerAstGrepScoringFunction, ScorerBashScriptScoringFunction, ScorerCommandScoringFunction, ScorerCustomScoringFunction, ScorerPythonScriptScoringFunction, ScorerTestBasedScoringFunction]]) – The scoring function to use for evaluating this scenario. The type field determines which built-in function to use.

• weight (Required[float]) – Weight to apply to scoring function score. Weights of all scoring functions should sum to 1.0.

class runloop_api_client.types.ScoringFunctionResultView(**data)

output: str

Log output of the scoring function.

score: float

Final score for the given scoring function.

scoring_function_name: str

Scoring function name that ran.

state: Literal['unknown', 'complete', 'error']

The state of the scoring function application.

typeddict runloop_api_client.types.SecretCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The globally unique name for the Secret. Must be a valid environment variable name (alphanumeric and underscores only). Example: ‘DATABASE_PASSWORD’

• value (Required[str]) – The value to store for this Secret. This will be encrypted at rest and made available as an environment variable in Devboxes. Example: ‘my-secure-password’

typeddict runloop_api_client.types.SecretListParams

typing.TypedDict.

Optional Keys:

• limit (int) – The limit of items to return. Default is 20.

class runloop_api_client.types.SecretListView(**data)

has_more: bool

True if there are more results available beyond this page.

remaining_count: int

Number of Secrets remaining after this page.

secrets: List[SecretView]

List of Secret objects. Values are omitted for security.

total_count: int

Total number of Secrets across all pages.

typeddict runloop_api_client.types.SecretUpdateParams

typing.TypedDict.

Optional Keys:

• value (Required[str]) – The new value for the Secret. This will replace the existing value and be encrypted at rest. Example: ‘my-updated-secure-password’

class runloop_api_client.types.SecretView(**data)

create_time_ms: int

Creation time of the Secret (Unix timestamp in milliseconds).

id: str

The unique identifier of the Secret.

name: str

The globally unique name of the Secret.

Used as the environment variable name in Devboxes.

update_time_ms: int

Last update time of the Secret (Unix timestamp in milliseconds).