> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# run

Execute command in isolated container. Spawns microVM (\~2-5s startup).

## Parameters

| Parameter            | Type    | Default  | Description                                                                                                  |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `command`            | string  | required | Shell command to execute                                                                                     |
| `image`              | string  | required | Image UUID or `tag:name`                                                                                     |
| `shell`              | boolean | `true`   | Whether command is a shell expression                                                                        |
| `disposable`         | boolean | `true`   | Discard changes after execution                                                                              |
| `directory_state_id` | integer | -        | Files from rsync                                                                                             |
| `files`              | object  | -        | Map of container paths to upload UUIDs: `{"/path/in/container": "uuid"}` — key is destination, value is UUID |
| `wait`               | boolean | `true`   | Block until complete                                                                                         |
| `timeout`            | integer | `30`     | Max seconds                                                                                                  |
| `env`                | object  | -        | Environment variables                                                                                        |
| `cwd`                | string  | `/root`  | Working directory                                                                                            |
| `stdin`              | string  | -        | Input via stdin                                                                                              |
| `truncate_output_at` | integer | `8000`   | Max bytes for output                                                                                         |

## Examples

**Basic:**

```json theme={null}
{"command": "python --version", "image": "tag:python:3.11"}
```

**With local files:**

```json theme={null}
{"command": "python /app/main.py", "image": "uuid", "directory_state_id": 42}
```

**Save changes:**

```json theme={null}
{"command": "pip install flask", "image": "uuid", "disposable": false}
```

Returns: `{"result_image": "new-uuid", "filesystem_changed": true}`

**Async:**

```json theme={null}
{"command": "python long_task.py", "image": "uuid", "wait": false}
```

Returns: `{"operation_id": "op-xxx"}`

**With uploaded files:**

```json theme={null}
// Step 1: Upload file
{"tool": "upload", "args": {"content": "print('hello')"}}
// Returns: {"uuid": "file-uuid-123"}

// Step 2: Inject into container and run
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "tag:python:3.11",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

> **Common mistake:** The `files` key is the **container path** (destination), the value is the **UUID** (from upload). Not the other way around. One UUID can be mounted to multiple paths.

**Environment variables:**

```json theme={null}
{"command": "echo $MY_VAR", "image": "uuid", "env": {"MY_VAR": "hello"}}
```

## Response

```json theme={null}
{
  "exit_code": 0,
  "timed_out": false,
  "state": "SUCCESS",
  "result_image": "uuid-if-disposable-false",
  "filesystem_changed": true,
  "stdout": "output",
  "stderr": null
}
```

## Errors

* **Image not found**: Use `list_images` to find valid UUIDs
* **Directory state not found**: Re-run `rsync`
* **timed\_out: true**: Increase `timeout` parameter