Sandboxes
Fork Sandbox
Checkpoints a running source sandbox and creates an isolated writable disk branch. Forks from running or paused sources resume from the source’s CPU, memory, and disk state. Forks from stopped sources cold-boot from the saved disk checkpoint. A running source is resumed after its checkpoint; paused and stopped sources remain inactive. Forked sandboxes may themselves be forked.
Passing checkpoint forks that saved state without touching the
source, so clients can pause once, wait for the checkpoint, and fork
it from any number of places. Without checkpoint the server pauses a
running source inside the request and resumes it afterwards; that path
is kept for older clients and is bounded by the request timeout.
Sandboxes with additional disk mounts must be stopped before forking.
The fork inherits mounts of the same external disks; only the internal
root disk is branched, so external disk contents are not isolated.
POST
/
api
/
sandboxes
/
{sid}
/
fork
Fork a sandbox
curl --request POST \
--url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "agent-fork"
}
'import requests
url = "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork"
payload = { "name": "agent-fork" }
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-fork'})
};
fetch('https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork', 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/{sid}/fork",
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-fork'
]),
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/{sid}/fork"
payload := strings.NewReader("{\n \"name\": \"agent-fork\"\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/{sid}/fork")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"agent-fork\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork")
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-fork\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"sandbox_id": "019d158f-5b60-7000-8000-0123456789ab",
"name": "agent-fork",
"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
Archil API key, including its key- prefix
Path Parameters
Sandbox UUID
Query Parameters
Hold the request for a completed sandbox lifecycle transition
Body
application/json
Name for the fork. A random word-list name is generated when omitted.
Required string length:
1 - 63Pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$Fork this checkpoint of the source, as returned by pause, stop, or describe, instead of the source's live state. The source is neither paused nor resumed. Only the current session's checkpoint and the one before it are accepted; an uncommitted or superseded checkpoint is rejected with 409.
Was this page helpful?
Fork a sandbox
curl --request POST \
--url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "agent-fork"
}
'import requests
url = "https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork"
payload = { "name": "agent-fork" }
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-fork'})
};
fetch('https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork', 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/{sid}/fork",
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-fork'
]),
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/{sid}/fork"
payload := strings.NewReader("{\n \"name\": \"agent-fork\"\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/{sid}/fork")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"agent-fork\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork")
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-fork\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"sandbox_id": "019d158f-5b60-7000-8000-0123456789ab",
"name": "agent-fork",
"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"
}
}