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]) – 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]) – 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’.

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

• network_policy_id (Optional[str]) – (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.

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

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• name (str) – Filter by name

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

• status (str) – Filter by build status (queued, provisioning, building, failed, build_complete)

• 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]]) – A list of code mounts to be included in the Devbox. Use mounts instead.

• 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]]) – Map of paths and file contents to write before setup. Use mounts instead.

• gateways (Optional[Dict[str, Gateways]]) – (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’}}

• launch_parameters (Optional[LaunchParameters]) – 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’.

• mcp (Optional[Dict[str, Mcp]]) – [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’}}

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

• mounts (Optional[Iterable[Union[ObjectMount, AgentMount, CodeMount, FileMount, BrokerMount]]]) – A list of mounts to be included in the Devbox.

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

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

• tunnel (Optional[Tunnel]) – Configuration for creating a V2 tunnel. When specified at Devbox creation, a tunnel will be automatically provisioned.

• 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]]) – A list of code mounts to be included in the Devbox. Use mounts instead.

• 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]]) – Map of paths and file contents to write before setup. Use mounts instead.

• gateways (Optional[Dict[str, Gateways]]) – (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’}}

• launch_parameters (Optional[LaunchParameters]) – 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’.

• mcp (Optional[Dict[str, Mcp]]) – [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’}}

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

• mounts (Optional[Iterable[Union[ObjectMount, AgentMount, CodeMount, FileMount, BrokerMount]]]) – A list of mounts to be included in the Devbox.

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

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

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

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

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

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

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

• 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]) – The path on the Devbox filesystem to read the file from. Path is relative to user home directory.

• 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]) – 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.

• 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]) – The path on the Devbox filesystem to read the file from. Path is relative to user home directory.

• 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]) – 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]]])

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

typing.TypedDict.

Optional Keys:

• auth_mode (Optional[Literal['open', 'authenticated']]) – Authentication mode for the tunnel. Defaults to open if omitted: the hostname is a public capability and does not require a tunnel bearer token.

• http_keep_alive (Optional[bool]) – When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. Defaults to true if not specified.

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

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

• 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]) – (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

• 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]) – (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

• 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) – Devbox ID to filter by.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

• 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]) – (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

• 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']]) – 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.

• 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']) – Filter storage objects by content type.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

• 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) – Duration in seconds for the presigned URL validity (default: 3600).

• 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

Agent Parameters

These TypeDicts define parameters for agent creation and listing.

typeddict runloop_api_client.sdk._types.SDKAgentCreateParams

typing.TypedDict.

Optional Keys:

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

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

• version (Optional[str]) – Optional version identifier for the Agent. For npm/pip sources this is typically a semver string (e.g. ‘2.0.65’). For git sources it can be a branch or tag. Semantics are user-defined for object sources.

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

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

• version (str) – Filter by version. Use ‘latest’ to get the most recently created agent.

• 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

Axon Parameters

These TypeDicts define parameters for axon creation, listing, publishing, and SQL operations.

typeddict runloop_api_client.sdk._types.SDKAxonCreateParams

typing.TypedDict.

Optional Keys:

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

• name (Optional[str]) – (Optional) Name for the axon.

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

typing.TypedDict.

Optional Keys:

• id (str) – Filter by axon ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

• name (str) – Filter by axon name (prefix match supported).

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

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

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

typing.TypedDict.

Optional Keys:

• event_type (Required[str]) – The event type (e.g. push, pull_request).

• origin (Required[Literal['EXTERNAL_EVENT', 'AGENT_EVENT', 'USER_EVENT']]) – Event origin.

• payload (Required[str]) – Event payload.

• source (Required[str]) – The source of the event (e.g. github, slack).

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

typing.TypedDict.

Optional Keys:

• sql (Required[str]) – SQL query with ?-style positional placeholders.

• params (Iterable[object]) – Positional parameter bindings for ? placeholders.

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

typing.TypedDict.

Optional Keys:

• statements (Required[Iterable[SqlStatementParams]]) – The SQL statements to execute atomically within a transaction.

• 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 Policy Parameters

These TypeDicts define parameters for network policy creation, listing, and updating.

typeddict runloop_api_client.sdk._types.SDKNetworkPolicyCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The human-readable name for the NetworkPolicy. Names are labels and may be reused.

• allow_agent_gateway (Optional[bool]) – (Optional) If true, allows devbox egress to the agent gateway for credential proxying. Defaults to false.

• allow_all (Optional[bool]) – (Optional) If true, all egress traffic is allowed (ALLOW_ALL policy). Defaults to false.

• allow_devbox_to_devbox (Optional[bool]) – (Optional) If true, allows traffic between the account’s own devboxes via tunnels. Defaults to false. If allow_all is true, this is automatically set to true.

• allow_mcp_gateway (Optional[bool]) – (Optional) If true, allows devbox egress to the MCP hub for MCP server access. Defaults to false.

• allow_runloop_mirrors (Optional[bool]) – (Optional) If true, allows devbox egress to Runloop’s package/image registry mirrors. Defaults to false. Implicitly allowed when allow_all is true.

• allowed_cidrs (Optional[Iterable[AllowedCidrParam]]) – (Optional) IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames. Example: [{‘cidr’: ‘10.12.0.0/16’, ‘ports’: [{‘port’: 443}]}].

• allowed_hostnames (Optional[Sequence[str]]) – (Optional) DNS-based allow list with wildcard support. Examples: [‘github.com’, ‘*.npmjs.org’].

• description (Optional[str]) – Optional description for the NetworkPolicy.

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

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

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

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

typing.TypedDict.

Optional Keys:

• allow_agent_gateway (Optional[bool]) – If true, allows devbox egress to the agent gateway.

• allow_all (Optional[bool]) – If true, all egress traffic is allowed (ALLOW_ALL policy).

• allow_devbox_to_devbox (Optional[bool]) – If true, allows traffic between the account’s own devboxes via tunnels.

• allow_mcp_gateway (Optional[bool]) – If true, allows devbox egress to the MCP hub.

• allow_runloop_mirrors (Optional[bool]) – If true, allows devbox egress to Runloop’s package/image registry mirrors. Implicitly allowed when allow_all is true.

• allowed_cidrs (Optional[Iterable[AllowedCidrParam]]) – Updated IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames.

• allowed_hostnames (Optional[Sequence[str]]) – Updated DNS-based allow list with wildcard support. Examples: [‘github.com’, ‘*.npmjs.org’].

• description (Optional[str]) – Updated description for the NetworkPolicy.

• name (Optional[str]) – Updated human-readable name for the NetworkPolicy.

• 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

MCP Config Parameters

These TypeDicts define parameters for MCP (Model Context Protocol) configuration creation, listing, and updating.

typeddict runloop_api_client.sdk._types.SDKMcpConfigCreateParams

typing.TypedDict.

Optional Keys:

• allowed_tools (Required[Sequence[str]]) – Glob patterns specifying which tools are allowed from this MCP server. Examples: [‘*’] for all tools, [‘github.search_*’, ‘github.get_*’] for specific patterns.

• endpoint (Required[str]) – The target MCP server endpoint URL (e.g., ‘https://mcp.example.com’).

• name (Required[str]) – The human-readable name for the McpConfig. Names are labels and may be reused. The first segment before ‘-’ is used as the service name for tool routing (e.g., ‘github-readonly’ uses ‘github’ as the service name).

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – Additional headers applied to upstream requests after the credential. At most 8 entries.

• description (Optional[str]) – Optional description for this MCP configuration.

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

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• name (str) – Filter by name (prefix match supported).

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

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

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

typing.TypedDict.

Optional Keys:

• allowed_tools (Optional[Sequence[str]]) – New glob patterns specifying which tools are allowed. Examples: [‘*’] for all tools, [‘github.search_*’] for specific patterns.

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.

• description (Optional[str]) – New description for this MCP configuration.

• endpoint (Optional[str]) – New target MCP server endpoint URL.

• name (Optional[str]) – New name for the McpConfig. Names are labels and may be reused.

• 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

Gateway Config Parameters

These TypeDicts define parameters for gateway configuration creation, listing, and updating.

typeddict runloop_api_client.sdk._types.SDKGatewayConfigCreateParams

typing.TypedDict.

Optional Keys:

• auth_mechanism (Required[AuthMechanism]) – How credentials should be applied to proxied requests. Specify the type (‘header’, ‘bearer’) and optional key field.

• endpoint (Required[str]) – The target endpoint URL (e.g., ‘https://api.anthropic.com’).

• name (Required[str]) – The human-readable name for the GatewayConfig. Names are labels and may be reused.

• custom_headers (Optional[Iterable[CustomHeader]]) – Additional headers applied to proxied requests after the auth mechanism. At most 8 entries.

• description (Optional[str]) – Optional description for this gateway configuration.

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

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

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

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

typing.TypedDict.

Optional Keys:

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.

• description (Optional[str]) – New description for this gateway configuration.

• endpoint (Optional[str]) – New target endpoint URL (e.g., ‘https://api.anthropic.com’).

• name (Optional[str]) – New name for the GatewayConfig. Names are labels and may be reused.

• 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

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

class runloop_api_client.types.account_view.AccountView(**data)

Account information.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

The account ID.

account_status: Literal['ACCOUNT_STATUS_INVALID', 'ACCOUNT_STATUS_ONBOARDING', 'ACCOUNT_STATUS_ENABLED', 'ACCOUNT_STATUS_DISABLED_BY_ADMIN', 'ACCOUNT_STATUS_DISABLED_QUOTA_REACHED', 'ACCOUNT_STATUS_TRIAL_CANCELLED', 'ACCOUNT_STATUS_STRIPE_PENDING_RESOURCES', 'UNRECOGNIZED']

The account status.

billing: Billing

The account billing information.

created_at: str

The account creation timestamp.

name: str

The account name.

tier: Literal['ACCOUNT_TIER_INVALID', 'ACCOUNT_TIER_BASIC', 'ACCOUNT_TIER_PRO', 'ACCOUNT_TIER_ENTERPRISE', 'ACCOUNT_TIER_TRIAL', 'UNRECOGNIZED']

The account tier.

account_billing_type: Optional[Literal['STRIPE', 'AWS_MARKETPLACE', 'STRIPE_PROJECTS', 'UNRECOGNIZED']]

use billing.account_billing_type.

Type:

Deprecated

active_subscription: Optional[str]

use billing.stripe.active_subscription.

Type:

Deprecated

external_billing_account_id: Optional[str]

use billing.aws.customer_identifier.

Type:

Deprecated

stripe_customer_id: Optional[str]

use billing.stripe.customer_id.

Type:

Deprecated

class runloop_api_client.types.account_view.Billing(**data)

The account billing information.

account_billing_type: Literal['STRIPE', 'AWS_MARKETPLACE', 'STRIPE_PROJECTS', 'UNRECOGNIZED']

The account billing type.

aws: Optional[BillingAws]

AWS Marketplace billing information.

stripe: Optional[BillingStripe]

Stripe billing information.

stripe_customer_id: Optional[str]

use stripe.customer_id.

Type:

Deprecated

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.account_view.BillingAws(**data)

AWS Marketplace billing information.

customer_identifier: Optional[str]

The AWS account ID used for Marketplace billing (12-digit).

license_arn: Optional[str]

The AWS Marketplace license ARN.

subscription_status: Optional[str]

The AWS Marketplace subscription status.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.account_view.BillingStripe(**data)

Stripe billing information.

active_subscription: Optional[str]

The active Stripe subscription ID.

customer_id: Optional[str]

The Stripe customer ID.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.agent_create_params.AgentCreateParams

typing.TypedDict.

Optional Keys:

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

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

• version (Optional[str]) – Optional version identifier for the Agent. For npm/pip sources this is typically a semver string (e.g. ‘2.0.65’). For git sources it can be a branch or tag. Semantics are user-defined for object sources.

class runloop_api_client.types.agent_devbox_counts_view.AgentDevboxCountsView(**data)

Devbox counts grouped by agent name.

Used to efficiently fetch devbox counts for multiple agents in a single request.

counts: Dict[str, int]

Map of agent name to devbox count.

Each key is an agent name, and the value is the count of devboxes associated with that agent.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: int

Total count of devboxes across all agents in the result.

typeddict runloop_api_client.types.agent_list_params.AgentListParams

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

• version (str) – Filter by version. Use ‘latest’ to get the most recently created agent.

typeddict runloop_api_client.types.agent_list_public_params.AgentListPublicParams

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

• version (str) – Filter by version. Use ‘latest’ to get the most recently created agent.

class runloop_api_client.types.agent_list_view.AgentListView(**data)

A paginated list of Agents.

agents: List[AgentView]

The list of Agents.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

has_more: bool

Whether there are more Agents to fetch.

total_count: Optional[int]

The total count of Agents.

class runloop_api_client.types.agent_view.AgentView(**data)

An Agent represents a registered AI agent entity.

id: str

The unique identifier of the Agent.

create_time_ms: int

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

is_public: bool

Whether the Agent is publicly accessible.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

The name of the Agent.

source: Optional[AgentSource]

Agent source configuration.

version: Optional[str]

Optional version identifier for the Agent.

For npm/pip sources this is typically a semver string (e.g. ‘2.0.65’). For git sources it can be a branch or tag. Omitted for object sources or when not provided.

class runloop_api_client.types.allowed_cidr.AllowedCidr(**data)

A CIDR-based egress allow rule with optional port restrictions.

cidr: str

IPv4 CIDR block in canonical form (host bits zero), e.g. ‘10.12.0.0/16’.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ports: Optional[List[PortRule]]

(Optional) Ports allowed for this CIDR.

Empty or omitted means all ports and protocols.

typeddict runloop_api_client.types.allowed_cidr_param.AllowedCidrParam

A CIDR-based egress allow rule with optional port restrictions.

Optional Keys:

• cidr (Required[str]) – IPv4 CIDR block in canonical form (host bits zero), e.g. ‘10.12.0.0/16’.

• ports (Optional[Iterable[PortRuleParam]]) – (Optional) Ports allowed for this CIDR. Empty or omitted means all ports and protocols.

class runloop_api_client.types.api_key_created_view.APIKeyCreatedView(**data)

id: Optional[str]

expires_at_ms: Optional[int]

key_secret: Optional[str]

name: Optional[str]

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.apikey_create_params.ApikeyCreateParams

typing.TypedDict.

Optional Keys:

• expires_at_ms (Optional[int])

• name (str)

typeddict runloop_api_client.types.axon_create_params.AxonCreateParams

typing.TypedDict.

Optional Keys:

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

• name (Optional[str]) – (Optional) Name for the axon.

class runloop_api_client.types.axon_event_view.AxonEventView(**data)

axon_id: str

The axon identifier.

event_type: str

Event type (e.g. push, pull_request).

origin: Literal['EXTERNAL_EVENT', 'AGENT_EVENT', 'USER_EVENT', 'SYSTEM_EVENT']

Event origin.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

payload: str

JSON-encoded event payload.

sequence: int

Monotonic sequence number.

source: str

Event source (e.g. github, slack).

timestamp_ms: int

Timestamp in milliseconds since epoch.

typeddict runloop_api_client.types.axon_list_params.AxonListParams

typing.TypedDict.

Optional Keys:

• id (str) – Filter by axon ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

• name (str) – Filter by axon name (prefix match supported).

• search (str) – Search by axon 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.axon_list_view.AxonListView(**data)

axons: List[AxonView]

List of active axons.

has_more: bool

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: Optional[int]

typeddict runloop_api_client.types.axon_publish_params.AxonPublishParams

typing.TypedDict.

Optional Keys:

• event_type (Required[str]) – The event type (e.g. push, pull_request).

• origin (Required[Literal['EXTERNAL_EVENT', 'AGENT_EVENT', 'USER_EVENT']]) – Event origin.

• payload (Required[str]) – Event payload.

• source (Required[str]) – The source of the event (e.g. github, slack).

typeddict runloop_api_client.types.axon_subscribe_sse_params.AxonSubscribeSseParams

typing.TypedDict.

Optional Keys:

• after_sequence (int) – Sequence number after which to start streaming. Events with sequence > this value are returned. If unset, replay from the beginning.

typeddict runloop_api_client.types.axon_update_params.AxonUpdateParams

typing.TypedDict.

Optional Keys:

• metadata (Optional[Dict[str, str]]) – User defined metadata to replace the axon metadata. Omit or set to null to leave unchanged, or set to an empty map to clear it.

class runloop_api_client.types.axon_view.AxonView(**data)

id: str

The axon identifier.

created_at_ms: int

Creation time in milliseconds since epoch.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

metadata: Dict[str, str]

The user defined axon metadata.

deleted_at_ms: Optional[int]

Deletion time in milliseconds since epoch; null while the axon is active.

name: Optional[str]

The name of the axon.

class runloop_api_client.types.axons.axon_event_list_view.AxonEventListView(**data)

events: List[AxonEventView]

List of axon events.

has_more: bool

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: Optional[int]

typeddict runloop_api_client.types.axons.event_list_params.EventListParams

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

typeddict runloop_api_client.types.axons.sql_batch_params.SqlBatchParams

typing.TypedDict.

Optional Keys:

• statements (Required[Iterable[SqlStatementParams]]) – The SQL statements to execute atomically within a transaction.

class runloop_api_client.types.axons.sql_batch_result_view.SqlBatchResultView(**data)

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

results: List[SqlStepResultView]

One result per statement, in order.

class runloop_api_client.types.axons.sql_column_meta_view.SqlColumnMetaView(**data)

name: str

Column name or alias.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str

Declared type (TEXT, INTEGER, REAL, BLOB, or empty).

typeddict runloop_api_client.types.axons.sql_query_params.SqlQueryParams

typing.TypedDict.

Optional Keys:

• sql (Required[str]) – SQL query with ?-style positional placeholders.

• params (Iterable[object]) – Positional parameter bindings for ? placeholders.

class runloop_api_client.types.axons.sql_query_result_view.SqlQueryResultView(**data)

columns: List[SqlColumnMetaView]

Column metadata.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

meta: SqlResultMetaView

Execution metadata.

rows: List[object]

Result rows (empty for non-SELECT statements).

class runloop_api_client.types.axons.sql_result_meta_view.SqlResultMetaView(**data)

changes: int

Rows modified by INSERT/UPDATE/DELETE.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

duration_ms: float

Execution time in milliseconds.

rows_read_limit_reached: bool

True when result was truncated at the row limit.

typeddict runloop_api_client.types.axons.sql_statement_params.SqlStatementParams

typing.TypedDict.

Optional Keys:

• sql (Required[str]) – SQL query with ?-style positional placeholders.

• params (Iterable[object]) – Positional parameter bindings for ? placeholders.

class runloop_api_client.types.axons.sql_step_error_view.SqlStepErrorView(**data)

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

message: str

Error message.

class runloop_api_client.types.axons.sql_step_result_view.SqlStepResultView(**data)

error: Optional[SqlStepErrorView]

Error on failure.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: Optional[SqlQueryResultView]

Result on success.

class runloop_api_client.types.blueprint_build_log.BlueprintBuildLog(**data)

level: str

Log line severity level.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

message: str

Log line message.

timestamp_ms: int

Time of log (Unix timestamp milliseconds).

class runloop_api_client.types.blueprint_build_logs_list_view.BlueprintBuildLogsListView(**data)

blueprint_id: str

ID of the Blueprint.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

logs: List[BlueprintBuildLog]

List of logs generated during Blueprint build.

class runloop_api_client.types.blueprint_build_parameters.BlueprintBuildParameters(**data)

name: str

Name of the Blueprint.

base_blueprint_id: Optional[str]

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

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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]

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

metadata: Optional[Dict[str, str]]

(Optional) User defined metadata for the Blueprint.

network_policy_id: Optional[str]

(Optional) ID of the network policy to apply during blueprint build.

This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.

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.

class runloop_api_client.types.blueprint_build_parameters.BuildContext(**data)

A build context backed by an Object.

object_id: str

The ID of an object, whose contents are to be used as a build context.

type: Literal['object']

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.blueprint_build_parameters.Service(**data)

image: str

The image of the container service.

name: str

The name of the container service.

credentials: Optional[ServiceCredentials]

The credentials of the container service.

env: Optional[Dict[str, str]]

The environment variables of the container service.

options: Optional[str]

Additional Docker container create options.

port_mappings: Optional[List[str]]

The port mappings of the container service.

Port mappings are in the format of <host_port>:<container_port>.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.blueprint_build_parameters.ServiceCredentials(**data)

The credentials of the container service.

password: str

The password of the container service.

username: str

The username of the container service.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.blueprint_create_params.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]) – 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’.

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

• network_policy_id (Optional[str]) – (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.

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

A build context backed by an Object.

Optional Keys:

• object_id (Required[str]) – The ID of an object, whose contents are to be used as a build context.

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

typeddict runloop_api_client.types.blueprint_create_params.Service

typing.TypedDict.

Optional Keys:

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

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

• credentials (Optional[ServiceCredentials]) – The credentials of the container service.

• env (Optional[Dict[str, str]]) – The environment variables of the container service.

• options (Optional[str]) – Additional Docker container create options.

• port_mappings (Optional[Sequence[str]]) – The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.

typeddict runloop_api_client.types.blueprint_create_params.ServiceCredentials

The credentials of the container service.

Optional Keys:

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

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

typeddict runloop_api_client.types.blueprint_list_params.BlueprintListParams

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• name (str) – Filter by name

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

• status (str) – Filter by build status (queued, provisioning, building, failed, build_complete)

typeddict runloop_api_client.types.blueprint_list_public_params.BlueprintListPublicParams

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• name (str) – Filter by name

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

• status (str) – Filter by build status (queued, provisioning, building, failed, build_complete)

class runloop_api_client.types.blueprint_list_view.BlueprintListView(**data)

blueprints: List[BlueprintView]

List of blueprints matching filter.

has_more: bool

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: Optional[int]

typeddict runloop_api_client.types.blueprint_preview_params.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]) – 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’.

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

• network_policy_id (Optional[str]) – (Optional) ID of the network policy to apply during blueprint build. This restricts network access during the build process. This does not affect devboxes created from this blueprint; if you want devboxes created from this blueprint to inherit the network policy, set the network_policy_id on the blueprint launch parameters.

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

A build context backed by an Object.

Optional Keys:

• object_id (Required[str]) – The ID of an object, whose contents are to be used as a build context.

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

typeddict runloop_api_client.types.blueprint_preview_params.Service

typing.TypedDict.

Optional Keys:

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

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

• credentials (Optional[ServiceCredentials]) – The credentials of the container service.

• env (Optional[Dict[str, str]]) – The environment variables of the container service.

• options (Optional[str]) – Additional Docker container create options.

• port_mappings (Optional[Sequence[str]]) – The port mappings of the container service. Port mappings are in the format of <host_port>:<container_port>.

typeddict runloop_api_client.types.blueprint_preview_params.ServiceCredentials

The credentials of the container service.

Optional Keys:

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

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

class runloop_api_client.types.blueprint_preview_view.BlueprintPreviewView(**data)

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

dockerfile: str

The Dockerfile contents that will built.

class runloop_api_client.types.blueprint_view.BlueprintView(**data)

Blueprints are ways to create customized starting points for Devboxes.

They allow you to define custom starting points for Devboxes such that environment set up can be cached to improve Devbox boot times.

id: str

The id of the Blueprint.

create_time_ms: int

Creation time of the Blueprint (Unix timestamp milliseconds).

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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', 'awaiting_upload', 'failed', 'build_complete']

The status of the Blueprint build.

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.

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

Capabilities that will be available on Devbox.

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

The cause of the failure of the Blueprint build.

out_of_memory: The build has run out of memory. Contact support if this is unexpected. out_of_disk: The build has run out of disk. Contact support if this is unexpected. build_failed: The build has failed. Use the dashboard to look at Blueprint build logs for more info.

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.

class runloop_api_client.types.blueprint_view.ContainerizedService(**data)

image: str

The image of the container service.

name: str

The name of the container service.

credentials: Optional[ContainerizedServiceCredentials]

The credentials of the container service.

env: Optional[Dict[str, str]]

The environment variables of the container service.

options: Optional[str]

Additional Docker container create options.

port_mappings: Optional[List[str]]

The port mappings of the container service.

Port mappings are in the format of <host_port>:<container_port>.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.blueprint_view.ContainerizedServiceCredentials(**data)

The credentials of the container service.

password: str

The password of the container service.

username: str

The username of the container service.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.devbox_async_execution_detail_view.DevboxAsyncExecutionDetailView(**data)

devbox_id: str

Devbox id where command was executed.

execution_id: str

Ephemeral id of the execution in progress.

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

Current status of the execution.

exit_status: Optional[int]

Exit code of command execution.

This field will remain unset until the execution has completed.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shell_name: Optional[str]

Shell name.

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.devbox_create_gateway_token_params.DevboxCreateGatewayTokenParams

typing.TypedDict.

Optional Keys:

• gateway (Required[str]) – The gateway config to use. Can be a gateway config ID (gwc_xxx) or name.

• secret (Required[str]) – The secret containing the credential. Can be a secret ID or name.

typeddict runloop_api_client.types.devbox_create_mcp_token_params.DevboxCreateMcpTokenParams

typing.TypedDict.

Optional Keys:

• mcp_config (Required[str]) – The MCP config to use. Can be an MCP config ID (mcp_xxx) or name.

• secret (Required[str]) – The secret containing the MCP server credential. Can be a secret ID or name.

typeddict runloop_api_client.types.devbox_create_params.DevboxCreateParams

typing.TypedDict.

Optional Keys:

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

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

• 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]]) – Map of paths and file contents to write before setup. Use mounts instead.

• gateways (Optional[Dict[str, Gateways]]) – (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’}}

• launch_parameters (Optional[LaunchParameters]) – 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’.

• mcp (Optional[Dict[str, Mcp]]) – [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’}}

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

• mounts (Optional[Iterable[Union[ObjectMount, AgentMount, CodeMount, FileMount, BrokerMount]]]) – A list of mounts to be included in the Devbox.

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

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

• tunnel (Optional[Tunnel]) – Configuration for creating a V2 tunnel. When specified at Devbox creation, a tunnel will be automatically provisioned.

typeddict runloop_api_client.types.devbox_create_params.Gateways

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.

Optional Keys:

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

• secret (Required[str]) – The secret containing the MCP server credential. Can be a secret ID or name.

typeddict runloop_api_client.types.devbox_create_params.Mcp

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

Optional Keys:

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

• secret (Required[str]) – The secret containing the MCP server credential. Can be a secret ID or name.

typeddict runloop_api_client.types.devbox_create_params.Tunnel

Configuration for creating a V2 tunnel.

When specified at Devbox creation, a tunnel will be automatically provisioned.

Optional Keys:

• auth_mode (Optional[Literal['open', 'authenticated']]) – Authentication mode for the tunnel. Defaults to open if omitted: the hostname is a public capability and does not require a tunnel bearer token.

• http_keep_alive (Optional[bool]) – When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. Defaults to true if not specified.

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

class runloop_api_client.types.devbox_create_ssh_key_response.DevboxCreateSSHKeyResponse(**data)

id: str

The ID of the Devbox.

ssh_private_key: str

The ssh private key, in PEM format.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ssh_user: str

The Linux user to use for SSH connections to this Devbox.

url: str

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

typeddict runloop_api_client.types.devbox_download_file_params.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.devbox_enable_tunnel_params.DevboxEnableTunnelParams

typing.TypedDict.

Optional Keys:

• auth_mode (Optional[Literal['open', 'authenticated']]) – Authentication mode for the tunnel. Defaults to open if omitted: the hostname is a public capability and does not require a tunnel bearer token.

• http_keep_alive (Optional[bool]) – When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer. Defaults to true if not specified.

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

class runloop_api_client.types.devbox_eviction_event_view.DevboxEvictionEventView(**data)

devbox_id: str

The ID of the Devbox with a pending eviction.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

eviction_deadline_ms: int

Unix timestamp (milliseconds) after which the Devbox will be suspended.

Advisory and best-effort.

typeddict runloop_api_client.types.devbox_execute_async_params.DevboxExecuteAsyncParams

typing.TypedDict.

Optional Keys:

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

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

typeddict runloop_api_client.types.devbox_execute_params.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, up to 25 seconds. Defaults to 25 seconds. Operation is not killed.

• 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.devbox_execute_sync_params.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.devbox_execution_detail_view.DevboxExecutionDetailView(**data)

devbox_id: str

Devbox id where command was executed.

exit_status: int

Exit status of command execution.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

stderr: str

Standard error generated by command.

stdout: str

Standard out generated by command.

shell_name: Optional[str]

Shell name.

typeddict runloop_api_client.types.devbox_list_disk_snapshots_params.DevboxListDiskSnapshotsParams

typing.TypedDict.

Optional Keys:

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

typing.TypedDict.

Optional Keys:

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

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

class runloop_api_client.types.devbox_list_view.DevboxListView(**data)

devboxes: List[DevboxView]

List of devboxes matching filter.

has_more: bool

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: Optional[int]

typeddict runloop_api_client.types.devbox_read_file_contents_params.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.devbox_read_file_contents_response.DevboxReadFileContentsResponse

alias of str

class runloop_api_client.types.devbox_resource_usage_view.DevboxResourceUsageView(**data)

id: str

The devbox ID.

disk_gb_seconds: int

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.

memory_gb_seconds: int

Memory usage in GB-seconds (total_active_seconds multiplied by memory in GB).

start_time_ms: int

The devbox creation time in milliseconds since epoch.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: str

The current status of the devbox.

total_active_seconds: int

Total time in seconds the devbox was actively running (excludes time spent suspended).

total_elapsed_seconds: int

Total elapsed time in seconds from devbox creation to now (or end time if terminated). Includes all time regardless of devbox state.

vcpu_seconds: int

vCPU usage in vCPU-seconds (total_active_seconds multiplied by the number of vCPUs).

end_time_ms: Optional[int]

The devbox end time in milliseconds since epoch, or null if still running.

class runloop_api_client.types.devbox_send_std_in_result.DevboxSendStdInResult(**data)

devbox_id: str

Devbox id where command is executing.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

execution_id: str

Execution id that received the stdin.

success: bool

Whether the stdin was successfully sent.

typeddict runloop_api_client.types.devbox_shutdown_params.DevboxShutdownParams

typing.TypedDict.

Optional Keys:

• force (str) – If true, force shutdown even if snapshots are in progress. Defaults to false.

typeddict runloop_api_client.types.devbox_snapshot_disk_async_params.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.devbox_snapshot_disk_params.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.devbox_snapshot_list_view.DevboxSnapshotListView(**data)

has_more: bool

snapshots: List[DevboxSnapshotView]

List of snapshots matching filter.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_count: Optional[int]

class runloop_api_client.types.devbox_snapshot_view.DevboxSnapshotView(**data)

id: str

The unique identifier of the snapshot.

create_time_ms: int

Creation time of the Snapshot (Unix timestamp milliseconds).

metadata: Dict[str, str]

User defined metadata associated with the snapshot.

source_devbox_id: str

The source Devbox ID this snapshot was created from.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

commit_message: Optional[str]

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

name: Optional[str]

(Optional) The custom name of the snapshot.

size_bytes: Optional[int]

(Optional) The size of the snapshot in bytes, relative to the base blueprint.

source_blueprint_id: Optional[str]

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

typeddict runloop_api_client.types.devbox_update_params.DevboxUpdateParams

typing.TypedDict.

Optional Keys:

• metadata (Optional[Dict[str, str]]) – User defined metadata to replace the Devbox metadata. Omit to leave unchanged or set to an empty map to clear it.

• name (Optional[str]) – A user specified name to give the Devbox. Omit to leave unchanged or set to an empty string to clear it.

typeddict runloop_api_client.types.devbox_upload_file_params.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.devbox_view.DevboxView(**data)

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.

id: str

The ID of the Devbox.

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

A list of capability groups this devbox has access to.

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.

launch_parameters: LaunchParameters

The launch parameters used to create the Devbox.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

metadata: Dict[str, str]

The user defined Devbox metadata.

state_transitions: List[StateTransition]

A list of state transitions in order with durations

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

The current status of the Devbox.

blueprint_id: Optional[str]

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

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

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.

gateway_specs: Optional[Dict[str, GatewaySpecs]]

Gateway specifications configured for this devbox.

Map key is the environment variable prefix (e.g., ‘GWS_ANTHROPIC’).

initiator_id: Optional[str]

The ID of the initiator that created the Devbox.

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

The type of initiator that created the Devbox.

mcp_specs: Optional[Dict[str, McpSpecs]]

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

name: Optional[str]

The name of the Devbox.

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

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.

snapshot_id: Optional[str]

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

tunnel: Optional[TunnelView]

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

class runloop_api_client.types.devbox_view.StateTransition(**data)

failure_reason: Optional[str]

The failure that caused this state transition, if applicable.

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

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.

transition_time_ms: Optional[object]

The time the status change occurred

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.devbox_view.GatewaySpecs(**data)

gateway_config_id: str

The ID of the gateway config (e.g., gwc_123abc).

secret_id: str

The ID of the secret containing the credential.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.devbox_view.McpSpecs(**data)

mcp_config_id: str

The ID of the MCP config (e.g., mcp_123abc).

secret_id: str

The ID of the secret containing the credential.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.devbox_wait_for_command_params.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 25 seconds. Defaults to 25 seconds.

typeddict runloop_api_client.types.devbox_write_file_contents_params.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.devboxes.devbox_logs_list_view.DevboxLogsListView(**data)

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

logs: List[Log]

List of logs for the given devbox.

class runloop_api_client.types.devboxes.devbox_logs_list_view.Log(**data)

level: str

Log line severity level.

source: Literal['setup_commands', 'entrypoint', 'exec', 'files', 'stats', 'kmsg']

The source of the log.

timestamp_ms: int

Time of log (Unix timestamp milliseconds).

cmd: Optional[str]

The Command Executed

cmd_id: Optional[str]

Identifier of the associated command the log is sourced from.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exit_code: Optional[int]

The Exit Code of the command

message: Optional[str]

Log line message.

shell_name: Optional[str]

The Shell name the cmd executed in.

class runloop_api_client.types.devboxes.devbox_snapshot_async_status_view.DevboxSnapshotAsyncStatusView(**data)

status: Literal['in_progress', 'error', 'complete', 'deleted']

The current status of the snapshot operation.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

error_message: Optional[str]

Error message if the operation failed.

snapshot: Optional[DevboxSnapshotView]

The snapshot details if the operation completed successfully.

typeddict runloop_api_client.types.devboxes.disk_snapshot_list_params.DiskSnapshotListParams

typing.TypedDict.

Optional Keys:

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• 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.devboxes.disk_snapshot_update_params.DiskSnapshotUpdateParams

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.devboxes.execution_execute_async_params.ExecutionExecuteAsyncParams

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.devboxes.execution_execute_sync_params.ExecutionExecuteSyncParams

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.devboxes.execution_kill_params.ExecutionKillParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

• kill_process_group (Optional[bool]) – Whether to kill the entire process group (default: false). If true, kills all processes in the same process group as the target process.

typeddict runloop_api_client.types.devboxes.execution_retrieve_params.ExecutionRetrieveParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

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

typeddict runloop_api_client.types.devboxes.execution_send_std_in_params.ExecutionSendStdInParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

• signal (Optional[Literal['EOF', 'INTERRUPT']]) – Signal to send to std in of the running execution.

• text (Optional[str]) – Text to send to std in of the running execution.

typeddict runloop_api_client.types.devboxes.execution_stream_stderr_updates_params.ExecutionStreamStderrUpdatesParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

• offset (str) – The byte offset to start the stream from (if unspecified, starts from the beginning of the stream)

typeddict runloop_api_client.types.devboxes.execution_stream_stdout_updates_params.ExecutionStreamStdoutUpdatesParams

typing.TypedDict.

Optional Keys:

• devbox_id (Required[str])

• offset (str) – The byte offset to start the stream from (if unspecified, starts from the beginning of the stream)

class runloop_api_client.types.devboxes.execution_update_chunk.ExecutionUpdateChunk(**data)

output: str

The latest log stream chunk.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

offset: Optional[int]

The byte offset of this chunk of log stream.

typeddict runloop_api_client.types.devboxes.log_list_params.LogListParams

typing.TypedDict.

Optional Keys:

• execution_id (str) – ID of execution to filter logs by.

• shell_name (str) – Shell Name to filter logs by.

typeddict runloop_api_client.types.gateway_config_create_params.GatewayConfigCreateParams

typing.TypedDict.

Optional Keys:

• auth_mechanism (Required[AuthMechanism]) – How credentials should be applied to proxied requests. Specify the type (‘header’, ‘bearer’) and optional key field.

• endpoint (Required[str]) – The target endpoint URL (e.g., ‘https://api.anthropic.com’).

• name (Required[str]) – The human-readable name for the GatewayConfig. Names are labels and may be reused.

• custom_headers (Optional[Iterable[CustomHeader]]) – Additional headers applied to proxied requests after the auth mechanism. At most 8 entries.

• description (Optional[str]) – Optional description for this gateway configuration.

typeddict runloop_api_client.types.gateway_config_list_params.GatewayConfigListParams

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

• search (str) – Search by gateway config 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.gateway_config_list_view.GatewayConfigListView(**data)

A paginated list of GatewayConfigs.

gateway_configs: List[GatewayConfigView]

The list of GatewayConfigs.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

has_more: bool

Whether there are more results available beyond this page.

total_count: Optional[int]

Total count of GatewayConfigs that match the query.

typeddict runloop_api_client.types.gateway_config_update_params.GatewayConfigUpdateParams

typing.TypedDict.

Optional Keys:

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.

• description (Optional[str]) – New description for this gateway configuration.

• endpoint (Optional[str]) – New target endpoint URL (e.g., ‘https://api.anthropic.com’).

• name (Optional[str]) – New name for the GatewayConfig. Names are labels and may be reused.

class runloop_api_client.types.gateway_config_view.GatewayConfigView(**data)

A GatewayConfig defines a configuration for proxying API requests through the agent gateway. It specifies the target endpoint and how credentials should be applied.

id: str

The unique identifier of the GatewayConfig.

auth_mechanism: AuthMechanism

How credentials should be applied to proxied requests.

create_time_ms: int

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

endpoint: str

//api.anthropic.com’).

Type:

The target endpoint URL (e.g., ‘https

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

The human-readable name of the GatewayConfig. Names may be reused.

account_id: Optional[str]

The account ID that owns this config.

custom_headers: Optional[List[CustomHeader]]

Additional headers applied to proxied requests after the auth mechanism.

Secret-backed entries reference the secret by ‘sec__’ id; values are never returned.

description: Optional[str]

Optional description for this gateway configuration.

class runloop_api_client.types.gateway_token_view.GatewayTokenView(**data)

token: str

The token to send to the gateway as a Bearer token in the Authorization header.

Only accepted for requests originating from the bound Devbox.

auth_mechanism: AuthMechanism

How the gateway applies the credential to proxied requests.

devbox_id: str

The Devbox the token is bound to.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

endpoint: str

The target API endpoint the gateway proxies to.

gateway_config_id: str

The ID of the gateway config the token proxies through.

url: str

The gateway URL to send requests to.

Matches the value of the &#123;prefix&#125;__URL environment variable inside the Devbox.

typeddict runloop_api_client.types.mcp_config_create_params.McpConfigCreateParams

typing.TypedDict.

Optional Keys:

• allowed_tools (Required[Sequence[str]]) – Glob patterns specifying which tools are allowed from this MCP server. Examples: [‘*’] for all tools, [‘github.search_*’, ‘github.get_*’] for specific patterns.

• endpoint (Required[str]) – The target MCP server endpoint URL (e.g., ‘https://mcp.example.com’).

• name (Required[str]) – The human-readable name for the McpConfig. Names are labels and may be reused. The first segment before ‘-’ is used as the service name for tool routing (e.g., ‘github-readonly’ uses ‘github’ as the service name).

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – Additional headers applied to upstream requests after the credential. At most 8 entries.

• description (Optional[str]) – Optional description for this MCP configuration.

typeddict runloop_api_client.types.mcp_config_list_params.McpConfigListParams

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• name (str) – Filter by name (prefix match supported).

• search (str) – Search by MCP config 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.mcp_config_list_view.McpConfigListView(**data)

A paginated list of McpConfigs.

has_more: bool

Whether there are more results available beyond this page.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mcp_configs: List[McpConfigView]

The list of McpConfigs.

total_count: Optional[int]

Total count of McpConfigs that match the query.

typeddict runloop_api_client.types.mcp_config_update_params.McpConfigUpdateParams

typing.TypedDict.

Optional Keys:

• allowed_tools (Optional[Sequence[str]]) – New glob patterns specifying which tools are allowed. Examples: [‘*’] for all tools, [‘github.search_*’] for specific patterns.

• auth_mechanism (Optional[AuthMechanism]) – Defines how the primary credential is applied to requests proxied to the upstream.

• custom_headers (Optional[Iterable[CustomHeader]]) – New list of additional headers. Replaces the existing list entirely; use an empty list to clear all custom headers. At most 8 entries.

• description (Optional[str]) – New description for this MCP configuration.

• endpoint (Optional[str]) – New target MCP server endpoint URL.

• name (Optional[str]) – New name for the McpConfig. Names are labels and may be reused.

class runloop_api_client.types.mcp_config_view.McpConfigView(**data)

An McpConfig defines a configuration for connecting to an upstream MCP (Model Context Protocol) server. It specifies the target endpoint and which tools are allowed.

id: str

The unique identifier of the McpConfig.

allowed_tools: List[str]

Glob patterns specifying which tools are allowed from this MCP server (e.g., [‘github.search_*’, ‘github.get_*’] or [‘*’] for all tools).

auth_mechanism: AuthMechanism

How the primary credential is applied to upstream requests.

create_time_ms: int

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

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

endpoint: str

//mcp.example.com’).

Type:

The target MCP server endpoint URL (e.g., ‘https

name: str

The human-readable name of the McpConfig. Names may be reused.

custom_headers: Optional[List[CustomHeader]]

Additional headers applied to upstream requests after the credential.

Secret-backed entries reference the secret by ‘sec__’ id; values are never returned.

description: Optional[str]

Optional description for this MCP configuration.

class runloop_api_client.types.mcp_token_view.McpTokenView(**data)

token: str

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.

allowed_tools: List[str]

Glob patterns for the tools the token permits.

devbox_id: str

The Devbox the token is bound to.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

endpoint: str

The upstream MCP server endpoint the hub proxies to.

mcp_config_id: str

The ID of the MCP config the token grants access to.

url: str

The MCP hub URL the token authenticates against.

Matches the RL_MCP_URL environment variable inside the Devbox.

typeddict runloop_api_client.types.network_policy_create_params.NetworkPolicyCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The human-readable name for the NetworkPolicy. Names are labels and may be reused.

• allow_agent_gateway (Optional[bool]) – (Optional) If true, allows devbox egress to the agent gateway for credential proxying. Defaults to false.

• allow_all (Optional[bool]) – (Optional) If true, all egress traffic is allowed (ALLOW_ALL policy). Defaults to false.

• allow_devbox_to_devbox (Optional[bool]) – (Optional) If true, allows traffic between the account’s own devboxes via tunnels. Defaults to false. If allow_all is true, this is automatically set to true.

• allow_mcp_gateway (Optional[bool]) – (Optional) If true, allows devbox egress to the MCP hub for MCP server access. Defaults to false.

• allow_runloop_mirrors (Optional[bool]) – (Optional) If true, allows devbox egress to Runloop’s package/image registry mirrors. Defaults to false. Implicitly allowed when allow_all is true.

• allowed_cidrs (Optional[Iterable[AllowedCidrParam]]) – (Optional) IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames. Example: [{‘cidr’: ‘10.12.0.0/16’, ‘ports’: [{‘port’: 443}]}].

• allowed_hostnames (Optional[Sequence[str]]) – (Optional) DNS-based allow list with wildcard support. Examples: [‘github.com’, ‘*.npmjs.org’].

• description (Optional[str]) – Optional description for the NetworkPolicy.

typeddict runloop_api_client.types.network_policy_list_params.NetworkPolicyListParams

typing.TypedDict.

Optional Keys:

• id (str) – Filter by ID.

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

• search (str) – Search by network policy 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.network_policy_list_view.NetworkPolicyListView(**data)

A list of NetworkPolicies with pagination information.

has_more: bool

Whether there are more results available.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

network_policies: List[NetworkPolicyView]

The list of NetworkPolicies.

total_count: Optional[int]

Total count of items in this response.

typeddict runloop_api_client.types.network_policy_update_params.NetworkPolicyUpdateParams

typing.TypedDict.

Optional Keys:

• allow_agent_gateway (Optional[bool]) – If true, allows devbox egress to the agent gateway.

• allow_all (Optional[bool]) – If true, all egress traffic is allowed (ALLOW_ALL policy).

• allow_devbox_to_devbox (Optional[bool]) – If true, allows traffic between the account’s own devboxes via tunnels.

• allow_mcp_gateway (Optional[bool]) – If true, allows devbox egress to the MCP hub.

• allow_runloop_mirrors (Optional[bool]) – If true, allows devbox egress to Runloop’s package/image registry mirrors. Implicitly allowed when allow_all is true.

• allowed_cidrs (Optional[Iterable[AllowedCidrParam]]) – Updated IPv4 CIDR-based allow list with optional port restrictions, additive with allowed_hostnames.

• allowed_hostnames (Optional[Sequence[str]]) – Updated DNS-based allow list with wildcard support. Examples: [‘github.com’, ‘*.npmjs.org’].

• description (Optional[str]) – Updated description for the NetworkPolicy.

• name (Optional[str]) – Updated human-readable name for the NetworkPolicy.

class runloop_api_client.types.network_policy_view.NetworkPolicyView(**data)

A NetworkPolicy defines egress network access rules for devboxes.

Policies can be applied to blueprints, devboxes, and snapshot resumes.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

The unique identifier of the NetworkPolicy.

create_time_ms: int

The creation time of the NetworkPolicy (Unix timestamp in milliseconds).

egress: Egress

The egress rules for this policy.

name: str

The human-readable name of the NetworkPolicy. Names may be reused.

update_time_ms: int

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

description: Optional[str]

Optional description of the NetworkPolicy.

class runloop_api_client.types.network_policy_view.Egress(**data)

The egress rules for this policy.

allow_agent_gateway: bool

If true, allows devbox egress to the agent gateway for credential proxying.

allow_all: bool

If true, all egress traffic is allowed and other fields are ignored.

Used for ALLOW_ALL policies.

allow_devbox_to_devbox: bool

If true, allows traffic between the account’s own devboxes via tunnels.

allow_mcp_gateway: bool

If true, allows devbox egress to the MCP hub for MCP server access.

allow_runloop_mirrors: bool

If true, allows devbox egress to Runloop’s package/image registry mirrors.

Implicitly allowed when allow_all is true.

allowed_cidrs: List[AllowedCidr]

CIDR-based allow list with optional port restrictions, additive with allowed_hostnames.

allowed_hostnames: List[str]

DNS-based allow list with wildcard support.

Examples: [‘github.com’, ‘*.npmjs.org’, ‘api.openai.com’]. Empty list with allow_all=false means no network access (DENY_ALL behavior).

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.object_create_params.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.object_download_params.ObjectDownloadParams

typing.TypedDict.

Optional Keys:

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

class runloop_api_client.types.object_download_url_view.ObjectDownloadURLView(**data)

A response containing a presigned download URL for an Object.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

download_url: str

The presigned download URL for the Object.

typeddict runloop_api_client.types.object_list_params.ObjectListParams

typing.TypedDict.

Optional Keys:

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

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

typing.TypedDict.

Optional Keys:

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

• include_total_count (bool) – If true (default), includes total_count in the response. Set to false to skip the count query for better performance on large datasets.

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

• 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.object_list_view.ObjectListView(**data)

A paginated list of Objects.

has_more: bool

True if there are more results available beyond this page.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

objects: List[ObjectView]

List of Object entities.

total_count: Optional[int]

Total number of Objects across all pages.

class runloop_api_client.types.object_view.ObjectView(**data)

An Object represents a stored data entity with metadata.

id: str

The unique identifier of the Object.

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.

name: str

The name of the Object.

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

The current state of the Object.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

delete_after_time_ms: Optional[int]

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

metadata: Optional[Dict[str, str]]

User defined metadata to attach to the Object for organization.

size_bytes: Optional[int]

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

upload_headers: Optional[Dict[str, str]]

HTTP headers required when uploading to upload_url (only present when needed on create).

upload_url: Optional[str]

Presigned URL for uploading content with HTTP PUT (only present on create).

class runloop_api_client.types.port_rule.PortRule(**data)

A port or port range allowed for a CIDR egress rule.

port: int

The allowed port (1-65535), or the start of a port range.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

end_port: Optional[int]

(Optional) Inclusive end of the port range (port-65535).

Omit for a single port.

protocol: Optional[Literal['TCP', 'UDP']]

L4 protocol for a port rule.

typeddict runloop_api_client.types.port_rule_param.PortRuleParam

A port or port range allowed for a CIDR egress rule.

Optional Keys:

• port (Required[int]) – The allowed port (1-65535), or the start of a port range.

• end_port (Optional[int]) – (Optional) Inclusive end of the port range (port-65535). Omit for a single port.

• protocol (Optional[Literal['TCP', 'UDP']]) – L4 protocol for a port rule.

typeddict runloop_api_client.types.pty_connect_params.PtyConnectParams

typing.TypedDict.

Optional Keys:

• cols (int) – Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored.

• rows (int) – Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored.

class runloop_api_client.types.pty_connect_view.PtyConnectView(**data)

attached: bool

created: bool

cols: Optional[int]

connect_url: Optional[str]

idle_ttl_seconds: Optional[int]

protocol_version: Optional[str]

rows: Optional[int]

session_name: Optional[str]

status: Optional[str]

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.pty_control_params.PtyControlParams

typing.TypedDict.

Optional Keys:

• action (Literal['resize', 'signal', 'close'])

• cols (int)

• rows (int)

• signal (str)

class runloop_api_client.types.pty_control_result_view.PtyControlResultView(**data)

session_name: Optional[str]

status: Optional[str]

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.pty_tunnel_view.PtyTunnelView(**data)

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

auth_token: str

Bearer token for tunnel authentication.

Always required for PTY tunnels. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tunnel_key: str

The encrypted tunnel key used to construct the tunnel URL.

URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}

class runloop_api_client.types.publish_result_view.PublishResultView(**data)

sequence: int

Assigned sequence number.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

timestamp_ms: int

Timestamp in milliseconds since epoch.

typeddict runloop_api_client.types.restricted_key_create_params.RestrictedKeyCreateParams

typing.TypedDict.

Optional Keys:

• expires_at_ms (Optional[int])

• name (str)

• scopes (Iterable[ScopeEntryViewParam])

class runloop_api_client.types.restricted_key_created_view.RestrictedKeyCreatedView(**data)

id: Optional[str]

expires_at_ms: Optional[int]

key_secret: Optional[str]

name: Optional[str]

scopes: Optional[List[ScopeEntryView]]

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.scope_entry_view.ScopeEntryView(**data)

access_level: Optional[Literal['ACCESS_LEVEL_NONE', 'ACCESS_LEVEL_READ', 'ACCESS_LEVEL_WRITE']]

resource_type: Optional[Literal['RESOURCE_TYPE_DEVBOXES', 'RESOURCE_TYPE_BLUEPRINTS', 'RESOURCE_TYPE_SNAPSHOTS', 'RESOURCE_TYPE_AGENTS', 'RESOURCE_TYPE_OBJECTS', 'RESOURCE_TYPE_ACCOUNT']]

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

typeddict runloop_api_client.types.scope_entry_view_param.ScopeEntryViewParam

typing.TypedDict.

Optional Keys:

• access_level (Literal['ACCESS_LEVEL_NONE', 'ACCESS_LEVEL_READ', 'ACCESS_LEVEL_WRITE'])

• resource_type (Literal['RESOURCE_TYPE_DEVBOXES', 'RESOURCE_TYPE_BLUEPRINTS', 'RESOURCE_TYPE_SNAPSHOTS', 'RESOURCE_TYPE_AGENTS', 'RESOURCE_TYPE_OBJECTS', 'RESOURCE_TYPE_ACCOUNT'])

typeddict runloop_api_client.types.secret_create_params.SecretCreateParams

typing.TypedDict.

Optional Keys:

• name (Required[str]) – The 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.secret_list_params.SecretListParams

typing.TypedDict.

Optional Keys:

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

class runloop_api_client.types.secret_list_view.SecretListView(**data)

A paginated list of Secrets.

has_more: bool

True if there are more results available beyond this page.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

secrets: List[SecretView]

List of Secret objects. Values are omitted for security.

total_count: Optional[int]

Total number of Secrets across all pages.

typeddict runloop_api_client.types.secret_update_by_id_params.SecretUpdateByIDParams

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’

typeddict runloop_api_client.types.secret_update_params.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.secret_view.SecretView(**data)

A Secret represents a key-value pair that can be securely stored and used in Devboxes as environment variables.

id: str

The unique identifier of the Secret.

create_time_ms: int

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

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

The 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).

class runloop_api_client.types.shared.after_idle.AfterIdle(**data)

idle_time_seconds: int

After idle_time_seconds, on_idle action will be taken.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

Action to take after Devbox becomes idle.

class runloop_api_client.types.shared.agent_mount.AgentMount(**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

type: Literal['agent_mount']

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.

class runloop_api_client.types.shared.agent_source.AgentSource(**data)

Agent source configuration.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str

npm, pip, object, or git

Type:

Source type

git: Optional[Git]

Git-based agent source configuration.

npm: Optional[Npm]

NPM-based agent source configuration.

object: Optional[Object]

Object store agent source configuration.

pip: Optional[Pip]

Pip-based agent source configuration.

class runloop_api_client.types.shared.agent_source.Git(**data)

Git-based agent source configuration.

repository: str

Git repository URL

agent_setup: Optional[List[str]]

Setup commands to run after cloning

ref: Optional[str]

Optional Git ref (branch/tag/commit), defaults to main/HEAD

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.shared.agent_source.Npm(**data)

NPM-based agent source configuration.

package_name: str

NPM package name

agent_setup: Optional[List[str]]

Setup commands to run after installation

registry_url: Optional[str]

NPM registry URL

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.shared.agent_source.Object(**data)

Object store agent source configuration.

object_id: str

Object ID

agent_setup: Optional[List[str]]

Setup commands to run after unpacking

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.shared.agent_source.Pip(**data)

Pip-based agent source configuration.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

package_name: str

Pip package name

agent_setup: Optional[List[str]]

Setup commands to run after installation

registry_url: Optional[str]

Pip registry URL

class runloop_api_client.types.shared.auth_mechanism.AuthMechanism(**data)

Defines how the primary credential is applied to requests proxied to the upstream.

type: str

‘header’, ‘bearer’, or ‘basic’.

For ‘basic’, store the secret as plain ‘user:pass’; the proxy base64-encodes it.

Type:

The type of authentication mechanism

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

key: Optional[str]

The header name (e.g., ‘x-api-key’).

Required for ‘header’ type; invalid for other types.

class runloop_api_client.types.shared.broker_mount.BrokerMount(**data)

axon_id: str

The ID of the axon event stream to mount onto the Devbox.

type: Literal['broker_mount']

agent_binary: Optional[str]

Binary to launch the agent (e.g., ‘opencode’).

Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

launch_args: Optional[List[str]]

Arguments to pass to the agent command (e.g., [‘acp’]).

Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).

protocol: Optional[Literal['acp', 'claude_json', 'codex_json', 'pi_json']]

The protocol used by the broker to deliver events to the agent.

working_directory: Optional[str]

Working directory in which to launch the agent binary.

Defaults to the home directory if not specified.

class runloop_api_client.types.shared.code_mount_parameters.CodeMountParameters(**data)

repo_name: str

The name of the repo to mount.

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

repo_owner: str

The owner of the repo.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

token: Optional[str]

The authentication token necessary to pull repo.

git_ref: Optional[str]

Optional git ref (branch or tag) to checkout.

Defaults to the repository default branch.

install_command: Optional[str]

Installation command to install and setup repository.

class runloop_api_client.types.shared.custom_header.CustomHeader(**data)

An additional header applied to upstream requests alongside the primary credential. The value comes from an account secret or a literal string; exactly one of ‘secret’ and ‘value’ must be set.

name: str

The header name (e.g., ‘DD-APPLICATION-KEY’).

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

secret: Optional[str]

Account secret providing the header value.

Accepts a secret name or ‘sec*’ id on writes; reads always return the ‘sec*’ id.

value: Optional[str]

Literal header value.

Stored in plaintext and returned by reads - use ‘secret’ for credentials or other sensitive values.

class runloop_api_client.types.shared.launch_parameters.LaunchParameters(**data)

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

after_idle: Optional[AfterIdle]

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.

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

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

available_ports: Optional[List[int]]

[Deprecated] A list of ports to make available on the Devbox.

This field is ignored.

custom_cpu_cores: Optional[float]

Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.

custom_disk_size: Optional[int]

Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB.

custom_gb_memory: Optional[int]

Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.

lifecycle: Optional[LifecycleConfiguration]

Lifecycle configuration for Devbox idle and resume behavior.

Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.

network_policy_id: Optional[str]

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

provisioning_tier: Optional[Literal['standard', 'flex']]

(Optional, Alpha) standard is default and flex is lazily provisioned and may be pre-empted. This is an alpha feature and its behavior may change without notice.

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']]

The size of the Devbox resources for Runloop to allocate.

X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.

user_parameters: Optional[UserParameters]

Configuration for the Linux user in the Devbox environment.

class runloop_api_client.types.shared.launch_parameters.UserParameters(**data)

Configuration for the Linux user in the Devbox environment.

uid: int

User ID (UID) for the Linux user. Must be a non-negative integer.

username: str

Username for the Linux user.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.shared.lifecycle_configuration.LifecycleConfiguration(**data)

Lifecycle configuration for Devbox idle and resume behavior.

Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.

after_idle: Optional[AfterIdle]

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.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

lifecycle_hooks: Optional[LifecycleHooks]

Lifecycle hooks for Devbox suspend.

suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.

resume_triggers: Optional[ResumeTriggers]

Triggers that can resume a suspended Devbox.

class runloop_api_client.types.shared.lifecycle_hooks.LifecycleHooks(**data)

Lifecycle hooks for Devbox suspend.

suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.

suspend_commands: Optional[List[str]]

Commands to run through the suspend path before the Devbox suspends (e.g.

cleanup, quiesce daemons).

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

suspend_deadline_ms: Optional[int]

Deadline in milliseconds for broker drain and suspend_commands during suspend.

Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM.

class runloop_api_client.types.shared.mount.CodeMount(**data)

repo_name: str

The name of the repo to mount.

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

repo_owner: str

The owner of the repo.

type: Literal['code_mount']

token: Optional[str]

The authentication token necessary to pull repo.

git_ref: Optional[str]

Optional git ref (branch or tag) to checkout.

Defaults to the repository default branch.

install_command: Optional[str]

Installation command to install and setup repository.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class runloop_api_client.types.shared.mount.FileMount(**data)

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

content: str

Content of the file to mount.

target: str

Target path where the file should be mounted.

type: Literal['file_mount']

class runloop_api_client.types.shared.object_mount.ObjectMount(**data)

object_id: str

The ID of the object to write.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.shared.resume_triggers.ResumeTriggers(**data)

Triggers that can resume a suspended Devbox.

axon_event: Optional[bool]

When true, axon events targeting a suspended Devbox will trigger a resume.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

http: Optional[bool]

When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.

typeddict runloop_api_client.types.shared_params.after_idle.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.agent_mount.AgentMount

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.agent_source.AgentSource

Agent source configuration.

Optional Keys:

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

• git (Optional[Git]) – Git-based agent source configuration.

• npm (Optional[Npm]) – NPM-based agent source configuration.

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

• pip (Optional[Pip]) – Pip-based agent source configuration.

typeddict runloop_api_client.types.shared_params.agent_source.Git

Git-based agent source configuration.

Optional Keys:

• repository (Required[str]) – Git repository URL

• agent_setup (Optional[Sequence[str]]) – Setup commands to run after installation

• ref (Optional[str]) – Optional Git ref (branch/tag/commit), defaults to main/HEAD

typeddict runloop_api_client.types.shared_params.agent_source.Npm

NPM-based agent source configuration.

Optional Keys:

• package_name (Required[str]) – Pip package name

• agent_setup (Optional[Sequence[str]]) – Setup commands to run after installation

• registry_url (Optional[str]) – Pip registry URL

typeddict runloop_api_client.types.shared_params.agent_source.Object

Object store agent source configuration.

Optional Keys:

• object_id (Required[str]) – Object ID

• agent_setup (Optional[Sequence[str]]) – Setup commands to run after installation

typeddict runloop_api_client.types.shared_params.agent_source.Pip

Pip-based agent source configuration.

Optional Keys:

• package_name (Required[str]) – Pip package name

• agent_setup (Optional[Sequence[str]]) – Setup commands to run after installation

• registry_url (Optional[str]) – Pip registry URL

typeddict runloop_api_client.types.shared_params.auth_mechanism.AuthMechanism

Defines how the primary credential is applied to requests proxied to the upstream.

Optional Keys:

• type (Required[str]) – The type of authentication mechanism: ‘header’, ‘bearer’, or ‘basic’. For ‘basic’, store the secret as plain ‘user:pass’; the proxy base64-encodes it.

• key (Optional[str]) – The header name (e.g., ‘x-api-key’). Required for ‘header’ type; invalid for other types.

typeddict runloop_api_client.types.shared_params.broker_mount.BrokerMount

typing.TypedDict.

Optional Keys:

• axon_id (Required[str]) – The ID of the axon event stream to mount onto the Devbox.

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

• agent_binary (Optional[str]) – Binary to launch the agent (e.g., ‘opencode’). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).

• launch_args (Optional[Sequence[str]]) – Arguments to pass to the agent command (e.g., [‘acp’]). Used by protocols that launch a subprocess (acp, claude_json, codex_json, pi_json).

• protocol (Optional[Literal['acp', 'claude_json', 'codex_json', 'pi_json']]) – The protocol used by the broker to deliver events to the agent.

• working_directory (Optional[str]) – Working directory in which to launch the agent binary. Defaults to the home directory if not specified.

typeddict runloop_api_client.types.shared_params.code_mount_parameters.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}.

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

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

• git_ref (Optional[str]) – Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.

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

typeddict runloop_api_client.types.shared_params.custom_header.CustomHeader

An additional header applied to upstream requests alongside the primary credential. The value comes from an account secret or a literal string; exactly one of ‘secret’ and ‘value’ must be set.

Optional Keys:

• name (Required[str]) – The header name (e.g., ‘DD-APPLICATION-KEY’).

• secret (Optional[str]) – Account secret providing the header value. Accepts a secret name or ‘sec*’ id on writes; reads always return the ‘sec*’ id.

• value (Optional[str]) – Literal header value. Stored in plaintext and returned by reads - use ‘secret’ for credentials or other sensitive values.

typeddict runloop_api_client.types.shared_params.launch_parameters.LaunchParameters

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

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. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead.

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

• available_ports (Optional[Iterable[int]]) – [Deprecated] A list of ports to make available on the Devbox. This field is ignored.

• custom_cpu_cores (Optional[float]) – Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16.

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

• custom_gb_memory (Optional[int]) – Custom memory size in GiB. Must be 1 or a multiple of 2. 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.

• lifecycle (Optional[LifecycleConfiguration]) – Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.

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

• provisioning_tier (Optional[Literal['standard', 'flex']]) – (Optional, Alpha) standard is default and flex is lazily provisioned and may be pre-empted. This is an alpha feature and its behavior may change without notice.

• 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']]) – The size of the Devbox resources for Runloop to allocate. X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.

• user_parameters (Optional[UserParameters]) – Configuration for the Linux user in the Devbox environment.

typeddict runloop_api_client.types.shared_params.launch_parameters.UserParameters

Configuration for the Linux user in the Devbox environment.

Optional Keys:

• uid (Required[int]) – User ID (UID) for the Linux user. Must be a non-negative integer.

• username (Required[str]) – Username for the Linux user.

typeddict runloop_api_client.types.shared_params.lifecycle_configuration.LifecycleConfiguration

Lifecycle configuration for Devbox idle and resume behavior.

Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks.

Optional Keys:

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

• lifecycle_hooks (Optional[LifecycleHooks]) – Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.

• resume_triggers (Optional[ResumeTriggers]) – Triggers that can resume a suspended Devbox.

typeddict runloop_api_client.types.shared_params.lifecycle_hooks.LifecycleHooks

Lifecycle hooks for Devbox suspend.

suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume.

Optional Keys:

• suspend_commands (Optional[Sequence[str]]) – Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons).

• suspend_deadline_ms (Optional[int]) – Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM.

typeddict runloop_api_client.types.shared_params.mount.CodeMount

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

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

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

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

• git_ref (Optional[str]) – Optional git ref (branch or tag) to checkout. Defaults to the repository default branch.

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

typeddict runloop_api_client.types.shared_params.mount.FileMount

typing.TypedDict.

Optional Keys:

• content (Required[str]) – Content of the file to mount.

• target (Required[str]) – Target path where the file should be mounted.

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

typeddict runloop_api_client.types.shared_params.object_mount.ObjectMount

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.resume_triggers.ResumeTriggers

Triggers that can resume a suspended Devbox.

Optional Keys:

• axon_event (Optional[bool]) – When true, axon events targeting a suspended Devbox will trigger a resume.

• http (Optional[bool]) – When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume.

class runloop_api_client.types.tunnel_view.TunnelView(**data)

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

auth_mode: Literal['open', 'authenticated']

The authentication mode for the tunnel.

create_time_ms: int

Creation time of the tunnel (Unix timestamp milliseconds).

http_keep_alive: bool

When true, HTTP traffic through the tunnel counts as activity for idle lifecycle policies, resetting the idle timer.

model_config: ClassVar[ConfigDict] = {'defer_build': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tunnel_key: str

The encrypted tunnel key used to construct the tunnel URL.

URL format: https://{port}-{tunnel_key}.tunnel.runloop.{domain}

wake_on_http: bool

When true, HTTP traffic to a suspended devbox will automatically trigger a resume.

auth_token: Optional[str]

Bearer token for tunnel authentication.

Only present when auth_mode is ‘authenticated’. Pass as X-Runloop-Tunnel-Authorization: Bearer {auth_token}.