Sandboxes

Create Sandbox

Provisions a sandbox VM with the requested shape and an internal, persistent Archil disk backing its root filesystem. This backing disk cannot be disabled or replaced with an existing disk. Use mounts to attach additional existing disks at guest paths; omit it or pass an empty list to create a sandbox without additional disks. By default the response reports pending after the runtime accepts the start. Set wait=true to hold for running; if the wait budget expires, the response remains pending and startup continues.

POST

api

sandboxes

Create a sandbox

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "agent-workspace",
  "base_image": "python:3.13",
  "vcpu_count": 2,
  "mem_size_mib": 4096,
  "mounts": [
    {
      "disk_id": "dsk-0123456789abcdef",
      "path": "/mnt/archil"
    }
  ]
}
'

import requests

url = "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes"

payload = {
    "name": "agent-workspace",
    "base_image": "python:3.13",
    "vcpu_count": 2,
    "mem_size_mib": 4096,
    "mounts": [
        {
            "disk_id": "dsk-0123456789abcdef",
            "path": "/mnt/archil"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'agent-workspace',
    base_image: 'python:3.13',
    vcpu_count: 2,
    mem_size_mib: 4096,
    mounts: [{disk_id: 'dsk-0123456789abcdef', path: '/mnt/archil'}]
  })
};

fetch('https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'agent-workspace',
    'base_image' => 'python:3.13',
    'vcpu_count' => 2,
    'mem_size_mib' => 4096,
    'mounts' => [
        [
                'disk_id' => 'dsk-0123456789abcdef',
                'path' => '/mnt/archil'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes"

	payload := strings.NewReader("{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "sandbox_id": "019d158e-7100-7000-8000-0123456789ab",
    "name": "agent-workspace",
    "status": "pending",
    "vcpu_count": 2,
    "mem_size_mib": 4096,
    "max_ttl_seconds": 86400,
    "idle_ttl_seconds": 0,
    "max_concurrent_execs": 32,
    "enable_service_ingress": false,
    "base_image": "python:3.13",
    "mounts": [
      {
        "disk_id": "dsk-0123456789abcdef",
        "path": "/mnt/archil"
      }
    ],
    "created_at": "2026-10-06T12:00:00Z",
    "last_active_at": "2026-10-06T12:00:00Z"
  }
}

Authorizations

Authorization

string

header

required

Archil API key, including its key- prefix

Query Parameters

wait

boolean

default:false

Hold the request for a completed sandbox lifecycle transition

Body

application/json

name

string

Sandbox name, unique within the account. A random word-list name is generated when omitted.

Required string length: 1 - 63

Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

vcpu_count

integer

default:1

Required range: 1 <= x <= 32

mem_size_mib

integer

default:2048

Required range: 256 <= x <= 65536

base_image

string

Public Linux OCI image reference with a linux/amd64 manifest for Archil's public sandbox service. Docker shorthand and tags are accepted; the deployment's platform manifest is pinned at creation. Defaults to node:24-bookworm (Debian with Node.js, Python, git, and a C toolchain) when neither this nor image_id is set. Mutually exclusive with image_id.

image_id

string

ID from Build Image, for a public or private image. For private images, build with registry_auth first, then pass the returned ID here. The sandbox boots the image's current digest. Mutually exclusive with base_image.

Pattern: ^[0-9a-f]{64}$

ports

integer[]

TCP ports to expose publicly when the sandbox is created.

Required range: 1 <= x <= 65535

enable_service_ingress

boolean

default:false

Allow services inside the sandbox to expose ingress. When false, services still run but their ports must be exposed explicitly through the API. Retained across starts, resumes, and forks.

env

object

Environment variables applied to every process

Show child attributes

network

object

Sandbox network policy. New sandboxes on free plans receive deny-all egress with no allowlist exceptions. Start/resume and forks retain the stored policy. For paid accounts, egress is unrestricted when omitted.

Show child attributes

mounts

object[]

Archil disks mounted inside the guest for the first session; start can replace them for later sessions. Inherited by forks. A sandbox with mounts must be stopped before it can be forked.

Show child attributes

max_ttl_seconds

integer

default:86400

Lifetime budget applied independently to each powered-on session. Expiry pauses the sandbox, preserving memory and processes for resume. Timeout resets cannot extend a session beyond 24 hours.

Required range: 60 <= x <= 86400

idle_ttl_seconds

integer

default:1800

Pause after this many seconds without a direct process connection, preserving memory and processes for resume. Defaults to 1800 (30 minutes) when omitted. Zero disables idle expiry.

Required range: 0 <= x <= 86400

max_concurrent_execs

integer

default:32

Maximum number of concurrently attached process sessions. Detached processes and one-shot process controls do not count.

Required range: 1 <= x <= 256

Response

The sandbox was created

success

boolean

required

Example:

true

data

object

required

Show child attributes

Create a sandbox

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "agent-workspace",
  "base_image": "python:3.13",
  "vcpu_count": 2,
  "mem_size_mib": 4096,
  "mounts": [
    {
      "disk_id": "dsk-0123456789abcdef",
      "path": "/mnt/archil"
    }
  ]
}
'

import requests

url = "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes"

payload = {
    "name": "agent-workspace",
    "base_image": "python:3.13",
    "vcpu_count": 2,
    "mem_size_mib": 4096,
    "mounts": [
        {
            "disk_id": "dsk-0123456789abcdef",
            "path": "/mnt/archil"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'agent-workspace',
    base_image: 'python:3.13',
    vcpu_count: 2,
    mem_size_mib: 4096,
    mounts: [{disk_id: 'dsk-0123456789abcdef', path: '/mnt/archil'}]
  })
};

fetch('https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'agent-workspace',
    'base_image' => 'python:3.13',
    'vcpu_count' => 2,
    'mem_size_mib' => 4096,
    'mounts' => [
        [
                'disk_id' => 'dsk-0123456789abcdef',
                'path' => '/mnt/archil'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes"

	payload := strings.NewReader("{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"agent-workspace\",\n  \"base_image\": \"python:3.13\",\n  \"vcpu_count\": 2,\n  \"mem_size_mib\": 4096,\n  \"mounts\": [\n    {\n      \"disk_id\": \"dsk-0123456789abcdef\",\n      \"path\": \"/mnt/archil\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "sandbox_id": "019d158e-7100-7000-8000-0123456789ab",
    "name": "agent-workspace",
    "status": "pending",
    "vcpu_count": 2,
    "mem_size_mib": 4096,
    "max_ttl_seconds": 86400,
    "idle_ttl_seconds": 0,
    "max_concurrent_execs": 32,
    "enable_service_ingress": false,
    "base_image": "python:3.13",
    "mounts": [
      {
        "disk_id": "dsk-0123456789abcdef",
        "path": "/mnt/archil"
      }
    ],
    "created_at": "2026-10-06T12:00:00Z",
    "last_active_at": "2026-10-06T12:00:00Z"
  }
}

Overview

Disks

Serverless Execution

Sandboxes

Disk Users

API Tokens

Billing

Create Sandbox

Authorizations

Query Parameters

Body

Response