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.

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: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "checkpoint": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "checkpoint": "<string>"
}
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>', checkpoint: '<string>'})
};

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' => '<string>',
    'checkpoint' => '<string>'
  ]),
  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/{sid}/fork"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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/{sid}/fork")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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>"
}

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

Authorizations

Authorization

string

header

required

API key

Path Parameters

sid

string<uuid>

required

Sandbox UUID

Query Parameters

wait

boolean

default:false

Hold the request for a completed sandbox lifecycle transition

Body

application/json

name

string

Name for the fork. A random word-list name is generated when omitted.

Required string length: 1 - 63

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

checkpoint

string

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.

Response

The fork was created and its start is pending

success

boolean

required

Example:

true

data

object

required

Show child attributes

Fork a sandbox

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/sandboxes/{sid}/fork \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "checkpoint": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "checkpoint": "<string>"
}
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>', checkpoint: '<string>'})
};

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' => '<string>',
    'checkpoint' => '<string>'
  ]),
  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/{sid}/fork"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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/{sid}/fork")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"checkpoint\": \"<string>\"\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>"
}

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

Overview

Disks

Serverless Execution

Sandboxes

Disk Users

API Tokens

Fork Sandbox

Authorizations

Path Parameters

Query Parameters

Body

Response