> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Start command

POST https://ca.compute.islo.dev/sandboxes/{sandbox_name}/exec
Content-Type: application/json

Start a command in an existing sandbox and receive an exec ID. The command runs asynchronously, so the response confirms that execution started rather than returning its output. Use the exec ID with the result endpoint to read stdout, stderr, exit code, and final status.

Reference: https://docs.islo.dev/api-reference/sandboxes/exec-in-sandbox

## Request

### Path parameters

- `sandbox_name` (string, required) — Sandbox name

### Body (application/json)

This endpoint expects an ExecRequest.

- `command` (list of string, required) — Command to execute.
- `env` (map from string to string, optional, nullable) — Environment variables to inject into this execution session.
- `timeout_secs` (long, optional, nullable) — Optional client-side timeout hint. Currently accepted for API compatibility.
- `user` (string, optional, nullable) — User to run the command as (e.g., "islo"). If not provided, uses image default.
- `workdir` (string, optional, nullable) — Working directory for command execution inside the sandbox.

## Response

### 200

Command execution started

- `exec_id` (string, required)
- `sandbox_id` (string, required)
- `status` (string, required)

## Errors

### 400 Bad Request Error

Invalid request

- `code` (enum, required)
  - Allowed values: `AUTH_REQUIRED`, `INVALID_REQUEST`, `NOT_FOUND`, `VALIDATION_ERROR`, `SANDBOX_NOT_FOUND`, `SANDBOX_ALREADY_EXISTS`, `SANDBOX_INVALID_STATE`, `SANDBOX_PROVISIONING_FAILED`, `RESOURCE_NOT_FOUND`, `FILE_NOT_FOUND`, `COMMAND_NOT_FOUND`, `EXEC_FAILED`, `FILE_OPERATION_ERROR`, `RESOURCE_UNAVAILABLE`, `ACCESS_DENIED`, `CACHE_CONFLICT`, `BILLING_NOT_ALLOWED`, `TENANT_SUSPENDED`, `TENANT_DELETED`, `RATE_LIMITED`, `TIMEOUT`, `GONE`, `BAD_GATEWAY`, `INTERNAL_ERROR`
- `message` (string, required)
- `available` (long, optional, nullable)
- `limit` (long, optional, nullable)
- `request_id` (string, optional, nullable)
- `requested` (long, optional, nullable)
- `resource` (string, optional, nullable) — Optional capacity fields populated for `InsufficientResources` errors so clients (including peer agents) can recover the typed payload across HTTP boundaries instead of collapsing it to an opaque message.

### 401 Unauthorized Error

Unauthorized

- `code` (enum, required)
  - Allowed values: `AUTH_REQUIRED`, `INVALID_REQUEST`, `NOT_FOUND`, `VALIDATION_ERROR`, `SANDBOX_NOT_FOUND`, `SANDBOX_ALREADY_EXISTS`, `SANDBOX_INVALID_STATE`, `SANDBOX_PROVISIONING_FAILED`, `RESOURCE_NOT_FOUND`, `FILE_NOT_FOUND`, `COMMAND_NOT_FOUND`, `EXEC_FAILED`, `FILE_OPERATION_ERROR`, `RESOURCE_UNAVAILABLE`, `ACCESS_DENIED`, `CACHE_CONFLICT`, `BILLING_NOT_ALLOWED`, `TENANT_SUSPENDED`, `TENANT_DELETED`, `RATE_LIMITED`, `TIMEOUT`, `GONE`, `BAD_GATEWAY`, `INTERNAL_ERROR`
- `message` (string, required)
- `available` (long, optional, nullable)
- `limit` (long, optional, nullable)
- `request_id` (string, optional, nullable)
- `requested` (long, optional, nullable)
- `resource` (string, optional, nullable) — Optional capacity fields populated for `InsufficientResources` errors so clients (including peer agents) can recover the typed payload across HTTP boundaries instead of collapsing it to an opaque message.

### 404 Not Found Error

Sandbox not found

- `code` (enum, required)
  - Allowed values: `AUTH_REQUIRED`, `INVALID_REQUEST`, `NOT_FOUND`, `VALIDATION_ERROR`, `SANDBOX_NOT_FOUND`, `SANDBOX_ALREADY_EXISTS`, `SANDBOX_INVALID_STATE`, `SANDBOX_PROVISIONING_FAILED`, `RESOURCE_NOT_FOUND`, `FILE_NOT_FOUND`, `COMMAND_NOT_FOUND`, `EXEC_FAILED`, `FILE_OPERATION_ERROR`, `RESOURCE_UNAVAILABLE`, `ACCESS_DENIED`, `CACHE_CONFLICT`, `BILLING_NOT_ALLOWED`, `TENANT_SUSPENDED`, `TENANT_DELETED`, `RATE_LIMITED`, `TIMEOUT`, `GONE`, `BAD_GATEWAY`, `INTERNAL_ERROR`
- `message` (string, required)
- `available` (long, optional, nullable)
- `limit` (long, optional, nullable)
- `request_id` (string, optional, nullable)
- `requested` (long, optional, nullable)
- `resource` (string, optional, nullable) — Optional capacity fields populated for `InsufficientResources` errors so clients (including peer agents) can recover the typed payload across HTTP boundaries instead of collapsing it to an opaque message.

## Examples

**Request**

```json
{
  "command": [
    "sh",
    "-lc",
    "pwd"
  ],
  "workdir": "/tmp"
}
```

**Response**

```json
{
  "exec_id": "exec_1234567890",
  "sandbox_id": "sbx_1234567890",
  "status": "running"
}
```

**SDK Code**

```python sandboxes_exec_in_sandbox_example
import requests

url = "https://ca.compute.islo.dev/sandboxes/sandbox_name/exec"

payload = {
    "command": ["sh", "-lc", "pwd"],
    "workdir": "/tmp"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript sandboxes_exec_in_sandbox_example
const url = 'https://ca.compute.islo.dev/sandboxes/sandbox_name/exec';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"command":["sh","-lc","pwd"],"workdir":"/tmp"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go sandboxes_exec_in_sandbox_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ca.compute.islo.dev/sandboxes/sandbox_name/exec"

	payload := strings.NewReader("{\n  \"command\": [\n    \"sh\",\n    \"-lc\",\n    \"pwd\"\n  ],\n  \"workdir\": \"/tmp\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby sandboxes_exec_in_sandbox_example
require 'uri'
require 'net/http'

url = URI("https://ca.compute.islo.dev/sandboxes/sandbox_name/exec")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": [\n    \"sh\",\n    \"-lc\",\n    \"pwd\"\n  ],\n  \"workdir\": \"/tmp\"\n}"

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

```java sandboxes_exec_in_sandbox_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://ca.compute.islo.dev/sandboxes/sandbox_name/exec")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": [\n    \"sh\",\n    \"-lc\",\n    \"pwd\"\n  ],\n  \"workdir\": \"/tmp\"\n}")
  .asString();
```

```php sandboxes_exec_in_sandbox_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://ca.compute.islo.dev/sandboxes/sandbox_name/exec', [
  'body' => '{
  "command": [
    "sh",
    "-lc",
    "pwd"
  ],
  "workdir": "/tmp"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp sandboxes_exec_in_sandbox_example
using RestSharp;

var client = new RestClient("https://ca.compute.islo.dev/sandboxes/sandbox_name/exec");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"command\": [\n    \"sh\",\n    \"-lc\",\n    \"pwd\"\n  ],\n  \"workdir\": \"/tmp\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift sandboxes_exec_in_sandbox_example
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "command": ["sh", "-lc", "pwd"],
  "workdir": "/tmp"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://ca.compute.islo.dev/sandboxes/sandbox_name/exec")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```