Sandboxes ›

Create sandbox

POST/v1/sandboxes

Create, from templateId or from default. Needs Idempotency-Key.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.create({
name: "agent-1",
size: "small",
idempotencyKey: "task-42",
});

Answer201 Created · Sandbox

{
"id": string,
"name": string,
"region": string,
"size": "tiny" | "small" | "medium" | "large",
"status": "creating" | "running" | "stopped" | "error" | "deleted" | "restoring" | …,
"hostId": string | null,
"vmIsolation": boolean,
"resources": {
"vcpu": integer,
"memoryMb": integer,
"diskGb": integer,
},
"error": string | null,
… 20 more
}

Sandbox created and running.

Headers

`Authorization`required Bearer key	An API key that may make this call.
`Idempotency-Key`required string	Required on create. The same key and body return the original sandbox. A timed-out create is recovered on retry. e.g. `"create-agent-1"`
`Agental-Max-Burst-Fee` string	The most this start may cost in burst fees, in millionths of a US dollar: 0 refuses any fee. A start that would cost more is refused with 429 burst_fee_too_high, which says when it would cost nothing. Left out, it pays what the account's monthly budget allows. See GET /v1/burst. e.g. `"50000"`

Body

`name`required string	Lowercase letters, digits, and hyphens. 1–63 characters. Must not start or end with a hyphen. e.g. `"agent-1"`
`size` "tiny" \| "small" \| "medium" \| "large"	Fixed size. Left out, it is the size the template starts sandboxes as, or the size the snapshot was taken on when snapshotId is given. e.g. `"small"`
`region` string	The region to make it in: eu (Europe: servers in the European Economic Area or the United Kingdom), us or apac, of those that have servers now. Left out, or main, it is eu, or the region of the snapshot it is made from. A region with no servers answers 400 unsupported_region, and one asked for that is not the snapshot's answers 400 region_mismatch. When the region is full the create answers 409 capacity_exceeded, and the sandbox is not made in another. e.g. `"eu"`
`regions` array of string	In place of region: up to three regions in the order to try them. It is made in the first of them that has room, and regions with no servers are passed over. When none has room it answers 409 capacity_exceeded, with regionsWithRoom. Not with region. e.g. `["eu","us"]`
`snapshotId` string or null	Make the sandbox from one of your snapshots: it starts with the disk as the snapshot holds it. The sandbox the snapshot was taken of is not touched, and may have been deleted. size then defaults to the size the snapshot was taken on, and cannot be one with less disk. Left out, it is the snapshot the template starts sandboxes from, if it names one. Null makes a new machine, whatever the template's start says. e.g. `"snap_7f3c1a9e0b24d658"`
`templateId` string	The template to make it from, one of your own. Left out, it is your account's default. The sandbox is on that template from then on: its commands get the template's variables and files, and the template's start says its size and what it starts from, where size and snapshotId here do not. e.g. `"tpl_0123456789abcdef"`
`ttlSeconds` integer or null	Seconds the sandbox runs after each start before it is stopped. Left out, it is what the template's start says, and where that says none, the deployment's default. Null is the deployment's default, whatever the template says. At most maxTtlSeconds of GET /v1/policy. PATCH /v1/sandboxes/{id} changes it later, and PUT /v1/sandboxes/{id}/auto-stop moves the stop of the run under way. e.g. `7200`
`network` object	Addresses the sandbox may reach on top of its template's outbound rule. It is held to the two from its first boot, so it never runs open first. Left out, it has none of its own. The rule itself is its template's: PUT /v1/templates/{id}/network. PUT /v1/sandboxes/{id}/network changes its own addresses later, while it runs. A fork has its source's. Sending outbound here is refused with rule_on_template. Only where GET /v1/policy says networkPolicy.
`sshKeys` array of string	OpenSSH public key lines let in to the sandbox's machine as root as it is made, on top of the keys its template lets in (GET /v1/templates/{id}/ssh). It turns nothing on: SSH is on as it is made only where its template says so, and otherwise PUT /v1/sandboxes/{id}/ssh turns it on. Takes the action ssh. A key that cannot be let in fails the create. Only where GET /v1/policy says ssh. e.g. `["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGNvbnRyb2wtcGxhbmUtdGVzdC1rZXktMDAwMDAwMDAw you@laptop"]`
`tags` array of string	Tags of its own, on top of its template's. Lowercase letters, digits and hyphens, 1 to 63 characters each, at most 30. Left out, it has its template's alone. Not for secrets. e.g. `["run-7f3a","branch-auth"]`
`metadata` object	Metadata of its own: its value for a key is used in place of its template's. At most 50 keys, of lowercase letters, digits, underscores, dots and hyphens, up to 40 characters, and values of up to 500. Left out, it has its template's alone. Not for secrets. e.g. `{"repo":"honzabit/agental","customer_id":"cus_0042"}`

Returns

201 Sandbox created and running. With snapshotId, it starts as that snapshot holds the disk.

Sandbox29 fields

id

string

name

string

region

string

The region it runs in.

It is placed, moved and kept on servers of that region and no other.

size

tinysmallmediumlarge

status

creatingrunningstoppederrordeletedrestoringmigrating

running: use it.

stopped: start it. creating, restoring or migrating: wait, and read it again. restoring is a stopped sandbox whose start is under way: one that was accepted with 202, or one the service makes itself after moving a sandbox that was running. Its machine is being brought back from storage, or was being archived or moved when the start arrived, or has just been moved. Read the sandbox every 10 seconds until its status is running. If the start fails, the status is stopped again and error says why: start it again. migrating is a stopped sandbox whose machine is being moved to another server, with its disk and its snapshots. What needs the machine answers 409 sandbox_migrating meanwhile: read the sandbox every 10 seconds until its status changes, then carry on. A start of one that is migrating is accepted with 202, and its status is restoring from then until it is running. A sandbox that is running can be moved too, for maintenance of the server it is on. It is moved while it runs: its status is running all the while, it stands still for a few seconds, what is running in it goes on, and its machine's own network address changes, so connections that were open are lost. A request cut at that moment answers 503 sandbox_moved and is sent again, and what would change its machine answers 409 sandbox_migrating for as long as the move takes. More rarely, when it cannot be moved while it runs, it is stopped, and its status is then migrating, then restoring, then running again, with nothing asked of its owner. Its disk is kept and what was running in it is not, as after a stop and a start, and migratedAt says when.

hostId

stringnull

vmIsolation

boolean

True when the sandbox runs in its own virtual machine.

resources

MachineResources3 fields

vcpu

integer

memoryMb

integer

diskGb

integer

error

stringnull

What went wrong, or null.

On a sandbox that is stopped, it says why a start that was accepted with 202 failed. A start that is accepted, or one that works, clears it.

createdAt

string

updatedAt

string

stoppedAt

stringnull

ttlSeconds

integernull

Seconds the sandbox runs after a start before it is stopped.

Stop keeps the disk. Null uses the deployment default. The count begins again at every start, the one that follows a move to another server included. PUT /v1/sandboxes/{id}/auto-stop moves the stop of the run under way.

autoStopAt

stringnull

When this running sandbox will be stopped: the time PUT /v1/sandboxes/{id}/auto-stop set for the run under way, or else its last start plus ttlSeconds.

Null when it is not running, or has no time limit: it then runs until it is stopped.

subdomain

stringnull

Stored only.

This is not registered in DNS.

shared

boolean

Organization share flag.

Stored only. It does not publish a URL.

templateId

stringnull

The template the sandbox is on.

Its commands get that template's variables and files as they were when it last started, or was applied to, with the sandbox's own on top. GET /v1/sandboxes/{id}/template says whether it is up to date with the template.

organizationId

string

The organization it belongs to, which pays for it: the one the request that made it acted in.

createdBy

stringnull

The account that made it, whose address its mail to its account is sent to.

Null when it was made with the dev key, and once that account is erased.

archived

boolean

True when the sandbox's machine is kept in storage and not where sandboxes run.

Its status is stopped and nothing on its disk is lost. A start brings it back, which takes longer than a start of one that is not archived. While it is brought back its status is restoring, and this is still true.

archivedAt

stringnull

When it was archived.

Null when it is not.

migratedAt

stringnull

When the service last stopped the sandbox, while it was running, to move it to another server.

It was stopped, moved and started again, so its disk is as it was and what was running in it then is gone: start that again. It is set also when the move could not be made and the sandbox was started again where it was. Null if it never happened. A move of a sandbox that was already stopped does not set it, and neither does a move of one while it runs, which stops nothing.

memoryKept

boolean

True while it is stopped with its memory kept, by POST /v1/sandboxes/{id}/stop with keepMemory: a start puts back every process as it was, and its clock is set again.

It costs 10% of its running price meanwhile, and is not archived. A snapshot put back while it is stopped lets the memory go. False whenever it is not stopped.

memoryLost

stringnull

Why the memory its last stop kept was not put back by its last start, which started it from its disk: as after an upgrade of the server it is on, which the memory cannot be put back across.

Null when it was put back, or none was kept.

network

SandboxNetwork2 fields

outbound

openblockedallowlist

What the sandbox may reach outside itself: its template's rule with its own addresses on top.

open is the internet, which is what a sandbox has when nothing is asked. blocked lets nothing out: names still resolve, and no connection leaves. allowlist lets out only what goes to an address in allow. It is enforced outside the sandbox, on the server it runs on, so nothing running in the sandbox can change it, root included. What reaches the sandbox is not affected: commands, files and its public addresses work as before. Whatever this says, no sandbox reaches another sandbox or a private network, or delivers mail on port 25.

allow

string[]

The IPv4 addresses and ranges an allowlist lets out to, over any protocol and port: its template's and its own.

Empty for open and blocked.

tags

string[]

Its template's tags and its own, each once: the template's first.

A change to its template's tags shows here at once. GET /v1/sandboxes?tag= finds sandboxes by them.

metadata

object

Its template's metadata, with its own value for a key in place of the template's.

A change to its template's shows here at once, for the keys it does not set itself.

ownTags

string[]

Of its tags, the ones it has itself, and not from its template.

PATCH /v1/sandboxes/{id} sets them.

ownMetadata

object

Of its metadata, the keys it sets itself.

PATCH /v1/sandboxes/{id} changes them.

Errors and other answers

202	Not made yet: send the same request again with the same Idempotency-Key in 10 seconds. With sandbox and operation, the create was accepted and its host result is uncertain. With waiting, no server has room for it right now: nothing is made, and a try with the same key places it as soon as there is room, until waiting.until, kept from its first try. After that it is refused with 409 capacity_exceeded.
400	Invalid request, missing Idempotency-Key, or size_too_small for the snapshot.
400	`unsupported_region` there are no servers in the region asked for, and the message names the regions there are.
400	`region_mismatch` the region asked for is not the region of the snapshot it has to be made from.
400	`ttl_too_long` ttlSeconds, or the template's, is over maxTtlSeconds of GET /v1/policy.
400	`invalid_network_policy` an address in network.allow cannot be allowed, and the message says which and why.
400	`rule_on_template` network.outbound was sent, and the message says where a rule is set now.
402	`billing_required` the account is on the free plan with no card saved.
402	`out_of_credit` its credits, the plan's and the top-ups, are used.
402	`size_not_on_plan` the plan does not make sandboxes of this size, and the message names the plan that does. Nothing was created.
404	`not_found` there is no such snapshot.
409	Capacity exceeded, name taken, or idempotency key reused with a different body.
409	`too_many_addresses` the template's rule and network.allow come to more than 100 addresses.
422	This idempotency key already failed.
429	`running_limit_reached` the account runs as many sandboxes as its plan's runningUnits allows.
429	`burst_fee_too_high` the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows.
429	`burst_budget_reached` the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. Nothing was created.
501	`network_policy_unavailable` network.allow names addresses, or the template holds the sandbox to blocked or an allowlist, where GET /v1/policy says networkPolicy is false. Nothing was created.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← List sandboxes Get sandbox →