POST
/
v1
/
devboxes
import Runloop from '@runloop/api-client';

const client = new Runloop({
  bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const devboxView = await client.devboxes.create();

  console.log(devboxView.id);
}

main();
{
  "id": "<string>",
  "name": "<string>",
  "status": "provisioning",
  "create_time_ms": 123,
  "end_time_ms": 123,
  "blueprint_id": "<string>",
  "snapshot_id": "<string>",
  "metadata": {},
  "failure_reason": "out_of_memory",
  "shutdown_reason": "api_shutdown",
  "launch_parameters": {
    "launch_commands": [
      "<string>"
    ],
    "resource_size_request": "X_SMALL",
    "keep_alive_time_seconds": 123,
    "available_ports": [
      123
    ],
    "after_idle": {
      "idle_time_seconds": 123,
      "on_idle": "shutdown"
    },
    "custom_cpu_cores": 123,
    "custom_gb_memory": 123
  },
  "capabilities": [
    "unknown"
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string | null

(Optional) A user specified name to give the Devbox.

​
environment_variables
object | null

(Optional) Environment variables used to configure your Devbox.

​
file_mounts
object | null

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

​
entrypoint
string | null

(Optional) When specified, the Devbox will run this script as its main executable. The devbox lifecycle will be bound to entrypoint, shutting down when the process is complete.

​
blueprint_id
string | null

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
string | null

Name of Blueprint to use for the Devbox. When set, this will load the latest successfully built Blueprint with the given name. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.

​
launch_parameters
object

Parameters to configure the resources and launch time behavior of the Devbox.

​
snapshot_id
string | null

Snapshot ID to use for the Devbox. Only one of (Snapshot ID, Blueprint ID, Blueprint name) should be specified.

​
prebuilt
string | null

Reference to prebuilt Blueprint to create the Devbox from. Should not be used together with (Snapshot ID, Blueprint ID, or Blueprint name).

​
metadata
object | null

User defined metadata to attach to the devbox for organization.

​
code_mounts
object[] | null

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

Response

200 - application/json
OK

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
string
required

The ID of the Devbox.

​
status
enum<string>
required

The current status of the Devbox.

Available options:
provisioning,
initializing,
running,
suspending,
suspended,
resuming,
failure,
shutdown
​
create_time_ms
integer
required

Creation time of the Devbox (Unix timestamp milliseconds).

​
metadata
object
required

The user defined Devbox metadata.

​
launch_parameters
object
required

The launch parameters used to create the Devbox.

​
capabilities
enum<string>[]
required

A list of capability groups this devbox has access to. This allows devboxes to be compatible with certain tools sets like computer usage APIs.

Available options:
unknown,
computer_usage,
browser_usage,
language_server
​
name
string | null

The name of the Devbox.

​
end_time_ms
integer | null

The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.

​
blueprint_id
string | null

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

​
snapshot_id
string | null

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

​
failure_reason
enum<string>

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

Available options:
out_of_memory,
out_of_disk,
execution_failed
​
shutdown_reason
enum<string>

The shutdown reason if the Devbox shutdown, if the Devbox has a 'shutdown' status.

Available options:
api_shutdown,
keep_alive_timeout,
entrypoint_exit,
idle,
lambda_lifecycle

Was this page helpful?