Sandbox lifecycle

Stop and archive sandbox

Stop active work and archive/snapshot the sandbox for later resume or fork.

A stop always saves the sandbox’s disk first. If that save is failing, the stop is refused and the sandbox keeps running so your work is not discarded, we retry automatically and email you. You are not billed for time spent in that state.

The stop is an operation: the response and the sandbox carry it as stop, with an id and a status. Poll GET /sandboxes/{sandboxId} until stop.status is completed. A failed attempt shows failing with its error and is retried until the sandbox archives; commands and prompts you send meanwhile do not cancel it. Only a resume ends it early (superseded). Calling stop again while one is pending returns the same id.

Set force: true to stop anyway, accepting the loss of everything written since the last successful snapshot. This is irreversible; only reach for it after a stop has already failed.

POST

sandboxes

{sandboxId}

stop

Stop and archive sandbox

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://boat.dev/api/v1/sandboxes/{sandboxId}/stop"

payload = { "force": False }
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({force: false})
};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/stop', 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://boat.dev/api/v1/sandboxes/{sandboxId}/stop",
  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([
    'force' => false
  ]),
  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://boat.dev/api/v1/sandboxes/{sandboxId}/stop"

	payload := strings.NewReader("{\n  \"force\": false\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://boat.dev/api/v1/sandboxes/{sandboxId}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/stop")

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  \"force\": false\n}"

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

{
  "ok": true,
  "type": "sandbox.stopping",
  "id": "bx_23456789",
  "status": "archiving",
  "sandbox": {
    "id": "bx_23456789",
    "name": "Sandbox 2026-05-31 12:00",
    "state": "archiving",
    "desktopAvailable": true,
    "snapshotAvailable": false
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Path Parameters

sandboxId

string

required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Body

application/json

Options for stopping a sandbox.

force

boolean

default:false

Stop the sandbox even if its disk cannot be snapshotted. Everything written since the last successful snapshot is permanently LOST. Without this, a sandbox whose snapshot pipeline is failing is left running rather than discarding your work, and you are not billed for that time. Only use this after a stop has already been refused.

Response

Boat archival started or already in progress.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Example:

"sandbox.stopping"

string

required

status

string

required

Example:

"archiving"

sandbox

object | null

Show child attributes

giftLimitNotice

string

Present on resume or fork when a fair-use cap on a gifted account shortened the requested auto-stop time.

conversationId

string

On interrupt, the conversation whose turn was interrupted.

Stop and archive sandbox

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://boat.dev/api/v1/sandboxes/{sandboxId}/stop"

payload = { "force": False }
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({force: false})
};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/stop', 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://boat.dev/api/v1/sandboxes/{sandboxId}/stop",
  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([
    'force' => false
  ]),
  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://boat.dev/api/v1/sandboxes/{sandboxId}/stop"

	payload := strings.NewReader("{\n  \"force\": false\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://boat.dev/api/v1/sandboxes/{sandboxId}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/stop")

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  \"force\": false\n}"

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

{
  "ok": true,
  "type": "sandbox.stopping",
  "id": "bx_23456789",
  "status": "archiving",
  "sandbox": {
    "id": "bx_23456789",
    "name": "Sandbox 2026-05-31 12:00",
    "state": "archiving",
    "desktopAvailable": true,
    "snapshotAvailable": false
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}