Create Sandbox

POST

api

sandboxes

Create a sandbox

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "vcpu_count": 1,
  "mem_size_mib": 2048,
  "base_image": "ubuntu:26.04",
  "ports": [
    32768
  ],
  "enable_service_ingress": false,
  "env": {},
  "network": {},
  "max_ttl_seconds": 86400,
  "idle_ttl_seconds": 43200,
  "max_concurrent_execs": 123
}
'

import requests

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

payload = {
    "name": "<string>",
    "vcpu_count": 1,
    "mem_size_mib": 2048,
    "base_image": "ubuntu:26.04",
    "ports": [32768],
    "enable_service_ingress": False,
    "env": {},
    "network": {},
    "max_ttl_seconds": 86400,
    "idle_ttl_seconds": 43200,
    "max_concurrent_execs": 123
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    vcpu_count: 1,
    mem_size_mib: 2048,
    base_image: 'ubuntu:26.04',
    ports: [32768],
    enable_service_ingress: false,
    env: {},
    network: {},
    max_ttl_seconds: 86400,
    idle_ttl_seconds: 43200,
    max_concurrent_execs: 123
  })
};

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' => '<string>',
    'vcpu_count' => 1,
    'mem_size_mib' => 2048,
    'base_image' => 'ubuntu:26.04',
    'ports' => [
        32768
    ],
    'enable_service_ingress' => false,
    'env' => [
        
    ],
    'network' => [
        
    ],
    'max_ttl_seconds' => 86400,
    'idle_ttl_seconds' => 43200,
    'max_concurrent_execs' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\n}")

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

	req.Header.Add("Authorization", "<api-key>")
	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", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\n}"

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

{
  "success": true,
  "data": {
    "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "pending",
    "vcpu_count": 123,
    "mem_size_mib": 123,
    "max_ttl_seconds": 123,
    "idle_ttl_seconds": 123,
    "max_concurrent_execs": 123,
    "base_image": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "last_active_at": "2023-11-07T05:31:56Z",
    "platform": "arm64",
    "endpoints": [
      {
        "port": 32768,
        "hostname": "<string>"
      }
    ],
    "enable_service_ingress": false,
    "running_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z",
    "exit_reason": "<string>",
    "checkpoint": "<string>"
  }
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

API key

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

default:ubuntu:26.04

Public Linux OCI image reference. Docker shorthand and tags are accepted; the selected platform manifest is pinned at creation.

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

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.

Required range: 60 <= x <= 86400

idle_ttl_seconds

integer

Pause after this many seconds without a direct process connection, preserving memory and processes for resume. Omit or set to zero to disable idle expiry.

Required range: 0 <= x <= 86400

max_concurrent_execs

integer

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

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: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "vcpu_count": 1,
  "mem_size_mib": 2048,
  "base_image": "ubuntu:26.04",
  "ports": [
    32768
  ],
  "enable_service_ingress": false,
  "env": {},
  "network": {},
  "max_ttl_seconds": 86400,
  "idle_ttl_seconds": 43200,
  "max_concurrent_execs": 123
}
'

import requests

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

payload = {
    "name": "<string>",
    "vcpu_count": 1,
    "mem_size_mib": 2048,
    "base_image": "ubuntu:26.04",
    "ports": [32768],
    "enable_service_ingress": False,
    "env": {},
    "network": {},
    "max_ttl_seconds": 86400,
    "idle_ttl_seconds": 43200,
    "max_concurrent_execs": 123
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    vcpu_count: 1,
    mem_size_mib: 2048,
    base_image: 'ubuntu:26.04',
    ports: [32768],
    enable_service_ingress: false,
    env: {},
    network: {},
    max_ttl_seconds: 86400,
    idle_ttl_seconds: 43200,
    max_concurrent_execs: 123
  })
};

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' => '<string>',
    'vcpu_count' => 1,
    'mem_size_mib' => 2048,
    'base_image' => 'ubuntu:26.04',
    'ports' => [
        32768
    ],
    'enable_service_ingress' => false,
    'env' => [
        
    ],
    'network' => [
        
    ],
    'max_ttl_seconds' => 86400,
    'idle_ttl_seconds' => 43200,
    'max_concurrent_execs' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\n}")

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

	req.Header.Add("Authorization", "<api-key>")
	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", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"vcpu_count\": 1,\n  \"mem_size_mib\": 2048,\n  \"base_image\": \"ubuntu:26.04\",\n  \"ports\": [\n    32768\n  ],\n  \"enable_service_ingress\": false,\n  \"env\": {},\n  \"network\": {},\n  \"max_ttl_seconds\": 86400,\n  \"idle_ttl_seconds\": 43200,\n  \"max_concurrent_execs\": 123\n}"

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

{
  "success": true,
  "data": {
    "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "pending",
    "vcpu_count": 123,
    "mem_size_mib": 123,
    "max_ttl_seconds": 123,
    "idle_ttl_seconds": 123,
    "max_concurrent_execs": 123,
    "base_image": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "last_active_at": "2023-11-07T05:31:56Z",
    "platform": "arm64",
    "endpoints": [
      {
        "port": 32768,
        "hostname": "<string>"
      }
    ],
    "enable_service_ingress": false,
    "running_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z",
    "exit_reason": "<string>",
    "checkpoint": "<string>"
  }
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

{
  "success": false,
  "error": "Invalid request parameters",
  "code": "<string>"
}

Overview

Disks

Serverless Execution

Sandboxes

Disk Users

API Tokens

Create Sandbox

Authorizations

Query Parameters

Body

Response