Start a durable background command

curl --request POST \
  --url https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "python3 -m http.server 3000",
  "wait_for_port": 3000
}
'

import requests

url = "https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes"

payload = {
    "command": "python3 -m http.server 3000",
    "wait_for_port": 3000
}
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({command: 'python3 -m http.server 3000', wait_for_port: 3000})
};

fetch('https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes', 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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes",
  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([
    'command' => 'python3 -m http.server 3000',
    'wait_for_port' => 3000
  ]),
  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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes"

	payload := strings.NewReader("{\n  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes")

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  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\n}"

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

{
  "id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

Processes

Start a Durable Background Command

Runs a command in the background in a Bash login shell and returns a process ID. The process keeps running between your calls: read its output, write to its input, or cancel it later, from any client. The sandbox’s lifetime bounds how long it can run; cancel it to end it sooner.

The sandbox image needs Linux /proc, Bash, and a few standard tools (setsid, nohup, tail, base64). If one is missing, the call fails with unsupported_feature before anything starts.

stdin defaults to false. Setting it to true, to write to the process later, needs a sandbox created with the processes.input requirement and a route that supports writing to the process after it reconnects (reattached_stdin). To check ahead of time which routes qualify, send the same requirements to POST /sandboxes/match.

With wait_for_port, the call returns once that port accepts TCP connections inside the sandbox. If the process exits first, or the port is still closed after 30 seconds, the process is ended and the call fails with 409 port_not_listening. details carries port, stdout_tail, stderr_tail and, when the process exited, exit_code.

Start a durable background command

curl --request POST \
  --url https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "python3 -m http.server 3000",
  "wait_for_port": 3000
}
'

import requests

url = "https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes"

payload = {
    "command": "python3 -m http.server 3000",
    "wait_for_port": 3000
}
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({command: 'python3 -m http.server 3000', wait_for_port: 3000})
};

fetch('https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes', 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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes",
  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([
    'command' => 'python3 -m http.server 3000',
    'wait_for_port' => 3000
  ]),
  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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes"

	payload := strings.NewReader("{\n  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\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://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.boxrouter.ai/api/v1/sandboxes/{sandbox_id}/processes")

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  \"command\": \"python3 -m http.server 3000\",\n  \"wait_for_port\": 3000\n}"

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

{
  "id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "outcome": "not_started",
    "retry": "safe",
    "retry_after_seconds": 1,
    "details": {
      "selection_version": 1,
      "considered": 1,
      "excluded": [
        {
          "provider": "<string>"
        }
      ],
      "closest": {},
      "nearest": [
        {}
      ],
      "requirement": "<string>",
      "purchase_id": "<string>",
      "preview": {
        "unused": 1,
        "held_excluded": 1,
        "fee": 1,
        "principal": 1,
        "tax": 1,
        "total": 1,
        "card": {
          "brand": "<string>",
          "last4": "<string>",
          "type": "card",
          "email": "jsmith@example.com"
        }
      },
      "quote": {
        "amount": 2,
        "tax": 1,
        "total": 2,
        "address_required": true,
        "fee_minor": 1,
        "missing": [
          "<string>"
        ]
      },
      "redemption": {
        "code": "<string>",
        "amount_nanodollars": "<string>",
        "description": "<string>",
        "redeemed_at": "2023-11-07T05:31:56Z"
      },
      "scope": "workspace",
      "period": "total",
      "limit_nanodollars": 2,
      "requested_nanodollars": 2,
      "sign_in_method": "<string>",
      "masked_email": "<string>",
      "failure_reason": "<string>",
      "names": [
        "<string>"
      ],
      "fields": [
        "preferences.order"
      ],
      "volume_id": "<string>",
      "writer_sandbox_id": "<string>",
      "checkpoint": 2,
      "limit_bytes": 1,
      "observed_bytes": 1,
      "mismatch": {
        "field": "image",
        "recorded": "<string>",
        "requested": "<string>"
      },
      "volume_phase": "check",
      "phase": "code",
      "command": "<string>",
      "exit_code": 123,
      "stderr_tail": "<string>",
      "stdout_tail": "<string>",
      "agent": "<string>",
      "port": 32768,
      "revoked": true,
      "preview_id": "<string>",
      "url": "<string>"
    },
    "doc_url": "<string>",
    "fix": "<string>",
    "operation_id": "<string>",
    "provider": "<string>",
    "native_code": "<string>",
    "native_status": 123,
    "native_message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

BoxRouter API key; never an upstream provider key.

Headers

Idempotency-Key

string

Optional for this operation. Preserve the same stable identifier when retrying an uncertain response; never reuse it for new work. If omitted where allowed, Cloud generates a request-scoped key that cannot reconcile a later retry. Do not include credentials or payloads. Stable identifier for one logical mutation.

Required string length: 1 - 128

Path Parameters

sandbox_id

string

required

Workspace-owned BoxRouter sandbox ID, not an upstream ID.

Minimum string length: 1

Pattern: ^[^\u0000]*$

Body

application/json

command

string

required

Bash source run in a login shell.

Pattern: ^[^\u0000]*$

env

object | null

Environment overrides for the command.

Show child attributes

cwd

string | null

Absolute working directory within the sandbox.

Pattern: ^/[^\u0000]*$

stdin

boolean

default:false

Keep stdin open for subsequent input requests. Requires named processes.input and selected-route reattached_stdin metadata; otherwise stdin: true is refused as unsupported_feature before process launch.

wait_for_port

integer | null

Return only after this port accepts TCP connections inside the sandbox, so the caller needs no readiness loop. Waits at most 30 seconds. If the process exits first, or the port is still closed after the wait, the process is ended and the answer is 409 port_not_listening with the output so far in details. Null returns as soon as the process starts.

Required range: 1 <= x <= 65535

Response

Durable process handle created.

string

required

Minimum string length: 1

Overview

Sandboxes

Commands

Processes

Files

Terminals

Previews

Volumes

Images

Operations

Routing Settings

Providers

Price Versions

Agent Catalog

Agent Launches

Launch Runs

Workspace Secrets

Artifacts

GitHub

GitHub Actions

Provider Accounts

Credits and Billing

Spend Limits

Start a Durable Background Command

Authorizations

Headers

Path Parameters

Body

Response