Create a Sailbox

curl --request POST \
  --url https://sailbox-api.sailresearch.com/v1/sailboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "worker-1",
  "app_id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
  "size": "m",
  "image": {
    "base": "BASE_IMAGE_DEBIAN"
  },
  "ingress_ports": [
    {
      "guest_port": 8000,
      "protocol": "http",
      "allowlist": [
        "203.0.113.0/24"
      ]
    }
  ]
}
'

import requests

url = "https://sailbox-api.sailresearch.com/v1/sailboxes"

payload = {
    "name": "worker-1",
    "app_id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
    "size": "m",
    "image": { "base": "BASE_IMAGE_DEBIAN" },
    "ingress_ports": [
        {
            "guest_port": 8000,
            "protocol": "http",
            "allowlist": ["203.0.113.0/24"]
        }
    ]
}
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: 'worker-1',
    app_id: 'app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03',
    size: 'm',
    image: {base: 'BASE_IMAGE_DEBIAN'},
    ingress_ports: [{guest_port: 8000, protocol: 'http', allowlist: ['203.0.113.0/24']}]
  })
};

fetch('https://sailbox-api.sailresearch.com/v1/sailboxes', 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://sailbox-api.sailresearch.com/v1/sailboxes",
  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' => 'worker-1',
    'app_id' => 'app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03',
    'size' => 'm',
    'image' => [
        'base' => 'BASE_IMAGE_DEBIAN'
    ],
    'ingress_ports' => [
        [
                'guest_port' => 8000,
                'protocol' => 'http',
                'allowlist' => [
                                '203.0.113.0/24'
                ]
        ]
    ]
  ]),
  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://sailbox-api.sailresearch.com/v1/sailboxes"

	payload := strings.NewReader("{\n  \"name\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\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://sailbox-api.sailresearch.com/v1/sailboxes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sailbox-api.sailresearch.com/v1/sailboxes")

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\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\n    }\n  ]\n}"

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

{
  "sailbox_id": "sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d",
  "status": "running"
}

{
  "error": {
    "message": "memory_gib for size m must be between 8 and 128",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Your API key has been disabled due to insufficient credits. Visit https://app.sailresearch.com/billing to add credits.",
    "type": "billing_error",
    "param": null,
    "code": "credits_exhausted",
    "billing_url": "https://app.sailresearch.com/billing"
  }
}

{
  "error": {
    "message": "sailboxes require an organization-scoped API key",
    "type": "permission_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "sailbox \"sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d\" not found",
    "type": "not_found_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "idempotency key reused with a different request body",
    "type": "conflict_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "request body too large",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Too many concurrent requests. Please retry after some of your organization's in-flight requests complete.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limited"
  }
}

{
  "error": {
    "message": "failed to fetch sailbox",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Authentication service unavailable",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "idempotent request still in flight",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

POST

sailboxes

Create a Sailbox

curl --request POST \
  --url https://sailbox-api.sailresearch.com/v1/sailboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "worker-1",
  "app_id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
  "size": "m",
  "image": {
    "base": "BASE_IMAGE_DEBIAN"
  },
  "ingress_ports": [
    {
      "guest_port": 8000,
      "protocol": "http",
      "allowlist": [
        "203.0.113.0/24"
      ]
    }
  ]
}
'

import requests

url = "https://sailbox-api.sailresearch.com/v1/sailboxes"

payload = {
    "name": "worker-1",
    "app_id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
    "size": "m",
    "image": { "base": "BASE_IMAGE_DEBIAN" },
    "ingress_ports": [
        {
            "guest_port": 8000,
            "protocol": "http",
            "allowlist": ["203.0.113.0/24"]
        }
    ]
}
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: 'worker-1',
    app_id: 'app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03',
    size: 'm',
    image: {base: 'BASE_IMAGE_DEBIAN'},
    ingress_ports: [{guest_port: 8000, protocol: 'http', allowlist: ['203.0.113.0/24']}]
  })
};

fetch('https://sailbox-api.sailresearch.com/v1/sailboxes', 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://sailbox-api.sailresearch.com/v1/sailboxes",
  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' => 'worker-1',
    'app_id' => 'app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03',
    'size' => 'm',
    'image' => [
        'base' => 'BASE_IMAGE_DEBIAN'
    ],
    'ingress_ports' => [
        [
                'guest_port' => 8000,
                'protocol' => 'http',
                'allowlist' => [
                                '203.0.113.0/24'
                ]
        ]
    ]
  ]),
  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://sailbox-api.sailresearch.com/v1/sailboxes"

	payload := strings.NewReader("{\n  \"name\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\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://sailbox-api.sailresearch.com/v1/sailboxes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sailbox-api.sailresearch.com/v1/sailboxes")

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\": \"worker-1\",\n  \"app_id\": \"app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03\",\n  \"size\": \"m\",\n  \"image\": {\n    \"base\": \"BASE_IMAGE_DEBIAN\"\n  },\n  \"ingress_ports\": [\n    {\n      \"guest_port\": 8000,\n      \"protocol\": \"http\",\n      \"allowlist\": [\n        \"203.0.113.0/24\"\n      ]\n    }\n  ]\n}"

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

{
  "sailbox_id": "sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d",
  "status": "running"
}

{
  "error": {
    "message": "memory_gib for size m must be between 8 and 128",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Your API key has been disabled due to insufficient credits. Visit https://app.sailresearch.com/billing to add credits.",
    "type": "billing_error",
    "param": null,
    "code": "credits_exhausted",
    "billing_url": "https://app.sailresearch.com/billing"
  }
}

{
  "error": {
    "message": "sailboxes require an organization-scoped API key",
    "type": "permission_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "sailbox \"sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d\" not found",
    "type": "not_found_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "idempotency key reused with a different request body",
    "type": "conflict_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "request body too large",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Too many concurrent requests. Please retry after some of your organization's in-flight requests complete.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limited"
  }
}

{
  "error": {
    "message": "failed to fetch sailbox",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "Authentication service unavailable",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

{
  "error": {
    "message": "idempotent request still in flight",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Makes the request retry-safe. Sail remembers the answer it sent under a key, including a 400 or a 409, and replays it with Idempotent-Replayed: true for a retry that repeats the key, the method, the path, and the body. Bodies are compared byte for byte. Reusing a key for a different request returns 409, so send a corrected request under a new key. A key that is blank or only spaces is ignored, and the request runs without idempotency.

Any string of up to 255 bytes works, and characters outside ASCII count for more than one. A UUID is a good default. Keys are remembered for at least 24 hours and scoped to the API key that sent them.

A server error, or a failure to record the answer, can leave a key unsettled, and creating a Sailbox is where that matters. See Retrying safely.

Maximum string length: 255

Body

application/json

name

string

required

Human-readable name for the new Sailbox. Names are not unique, so keep hold of the returned sailbox_id. It is stored as you send it, surrounding spaces included, so trim it yourself if you compare names later. Control characters are not allowed.

Required string length: 1 - 128

Pattern: \S

app_id

string

required

Id of the app that will own the Sailbox. Use POST /apps/find to look one up by name.

Minimum string length: 1

Pattern: \S

image

object

required

Describes the environment the Sailbox boots into. A base image on its own is ready to boot. Adding build steps, environment variables, or a Python version describes an image that has to be built before a Sailbox can start from it, and building one takes an SDK or the CLI.

Show child attributes

size

enum<string>

default:m

Machine size. s is 1 vCPU, m is 4 vCPUs, l is 8 vCPUs.

Available options:

s,

m,

l,

memory_limit_gib

integer

Memory limit in GiB. Allowed ranges are 2 to 64 for size s, 8 to 128 for m, and 16 to 256 for l. Omit it to take the default for the size: 16 for s, 32 for m, and 64 for l.

state_disk_limit_gib

integer

Disk limit in GiB. Allowed ranges are 8 to 128 for size s, 32 to 512 for m, and 64 to 1024 for l. Omit it to take the default for the size: 32 for s, 128 for m, and 256 for l.

ingress_ports

object[]

Ports to publish. You can also publish ports later without restarting.

Show child attributes

volume_mounts

object[]

Volumes to mount into the Sailbox.

Show child attributes

visibility

enum<string>

default:org

org lets anyone in your organization operate the Sailbox. private restricts that to the user whose key created it, so it needs a user-scoped key. An organization admin can still pause, resume, sleep, schedule a wake, upgrade, or terminate it by sending X-Sail-Owner-Override-Reason.

Available options:

org,

private,

Response

Check status: running means the Sailbox is ready, and failed means it did not start, with error_message saying why.

sailbox_id

string

required

Id of the new Sailbox.

status

string

required

Current state of the Sailbox. Values in use today are creating, running, paused, sleeping, terminating, terminated, failed, create_failed, interrupted_restorable, and interrupted_unsafe_to_retry. New values can appear over time, so treat this as an open set.

error_message

string

Why the Sailbox failed to start, when it did.

List Sailboxes Retrieve a Sailbox

⌘I

Inference APIs

Usage API

Sailbox

Voyages

Tinker

CLI

SDKs

Create a Sailbox

Authorizations

Headers

Body

Response