HEhedra-labs
Sandboxes

Create a sandbox

Changed on

Start one instance per replica, paying the first lease from the API wallet before any instance is created. The sandbox runs until you stop it, its command exits, the wallet cannot pay a lease, or its ttl_seconds ends, when you give one. 404 while sandboxes are not enabled for your workspace.

post/sandboxes

Request

  • Base URL
    https://api.hedra.com/v3
  • Auth
    • API key in header Authorization
    • or HTTP bearer

Headers

Idempotency-Keystring

Caller-chosen key that makes retrying this create safe. A repeat create with the same key and body answers the same sandbox instead of creating and charging a second one. Keys are scoped to the calling user and workspace. A create refused with 402, 429 or 503 releases its key, so a retry under it is a new create. Reusing a key with a different body is a 409 ALREADY_EXISTS, and retrying while the original is still being created is a 409 ALREADY_IN_PROGRESS carrying Retry-After.

Request body

namestring required

The sandbox's name: lowercase letters, digits and hyphens, starting and ending with a letter or digit, at most 32 characters. Unique among your creating, active and stopping sandboxes.

imagestring required

The image reference to run.

acceleratorstring required

A GPU model and a GPU count per instance, <gpu model>:<count> such as h100:1. The count is 1 to 99; GET /sandboxes/gpus lists the GPU models.

replicasinteger

How many instances, at most your workspace's sandbox quota.

commandstring[] nullable

What runs in place of the image's entrypoint; at most 16384 bytes written as JSON. Absent runs the image's ENTRYPOINT/CMD. The main process's stdin stays open, as under docker run -i, so a shell or an interpreter waits for input. The sandbox ends when the main process exits unless restart restarts it; set idle for a sandbox with no main process.

idleboolean

Run no main process: the sandbox starts with nothing running and stays up for sessions until you stop it, or, when you give them, ttl_seconds ends or it is idle for idle_ttl_seconds. Not with command; restart has no effect. The image's entrypoint is not run.

restart'never' | 'on-failure' | 'always'

When hedra-compute restarts the command; hedra-compute's own values.

envobject

Environment variables for every instance; at most 32768 bytes written as JSON, no empty key or key containing =, and no key starting SANDBOX_, which the sandbox reserves. Answers return the keys only, as env_keys.

ttl_secondsinteger nullable

The sandbox's lifetime in seconds, counted from create, 120 to 31,536,000 (365 days); every instance is stopped when it ends. Leave it out for a sandbox that runs until you stop it, its command exits, or the wallet cannot pay a lease.

idle_ttl_secondsinteger nullable

For an idle sandbox only: end it, with end_reason idle_ttl_ended, once it has had no activity for this many seconds, 120 to 31,536,000. Activity is an exec or shell session, from its start until its process exits, and a request to its url, until its response ends; a port-forward, an attach, and a process left running after its session ends are not. With more than one replica, the instances stop together once every one is idle. The stop can land a minute or so after the limit. Leave it out for no idle limit.

secretsstring[] nullable

The names of workspace secrets every instance receives, each as an environment variable of its own name; at most 32. GET /sandboxes/secrets lists the names your workspace holds.

Response

Successful Response

idstring required

The sandbox's id (sandbox_<uuid>).

namestring required

The sandbox's name, as created.

acceleratorstring required

The request's accelerator.

gpu_modelstring required

The accelerator's GPU model.

replicasinteger required

How many instances.

status'creating' | 'active' | 'stopping' | 'ended' | 'failed' required

Where a sandbox is in its life; stored in sandbox_billings.status.

end_reason'caller_stopped' | 'ttl_ended' | 'exited' | 'instance_failed' | 'unpaid' | 'lease_lapsed' | 'access_removed' | 'idle_ttl_ended' required

Why a sandbox ended, or, on an active one, that its last lease was refused.

created_atstring date-time required
started_atstring date-time nullable required

The earliest started_at of its instances; null on the list and before any instance starts.

ended_atstring date-time nullable required

When the last instance stopped; null until then.

ttl_ends_atstring date-time nullable required

When the sandbox's lifetime ends: created_at plus ttl_seconds; null for a sandbox created without ttl_seconds.

env_keysstring[] required

The keys of env, never its values.

imagestring nullable

The image the sandbox runs, as created. Set wherever instances is and the sandbox has an instance; null on the list, on the create answer, and while it has none.

commandstring[] nullable

The command the sandbox runs, as created and returned as given, so a secret belongs in env rather than here; null when image is, when the image's own ENTRYPOINT/CMD runs, and for an idle sandbox.

urlstring nullable

The address of the port in ports, the same for every replica; call it with a token from POST /sandboxes/{sandbox_id}/endpoint-token. Set wherever instances is; null on the list, for a sandbox created without ports, and while its pool serves no address.

Changes

  • 6ef35a11cefeRevision changes
    • warning

      added the new idle_ttl_ended enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 5a58ee38990eRevision changes
    • info

      added the new optional request property //