# smol machines — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Cloud microVM platform. Create isolated Linux VMs, execute commands, run code, manage files and volumes. Each machine has its own kernel with configurable CPU, memory, networking, and storage.

**Verified:** no

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Run Code

Run Python or JavaScript code directly in a machine

`POST /v1/machines/{id}/code`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `code` | string | Yes |  |
| `cwd` | string | No |  |
| `env` | object | No |  |
| `language` | string | Yes |  |
| `timeoutSeconds` | number | No |  |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/code","body":{"code":"<string>","cwd":"<string>","env":"<object>","language":"<string>","timeoutSeconds":"<number>"}}'
```

### Upload File

Upload a file to a machine

`POST /v1/machines/{id}/files`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/files"}'
```

### Create Session

Create a persistent session that preserves working directory and environment across exec calls

`POST /v1/machines/{id}/sessions`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `cwd` | string | No |  |
| `env` | object | No |  |
| `id` | string | No |  |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/sessions","body":{"cwd":"<string>","env":"<object>","id":"<string>"}}'
```

### List Sessions

List sessions for a machine

`GET /v1/machines/{id}/sessions`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/sessions","method":"GET"}'
```

### Delete Session

Delete a session

`DELETE /v1/machines/{id}/sessions/{session_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `session_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id}, {session_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/sessions/{session_id}","method":"DELETE"}'
```

### Download File

Download a file from a machine

`GET /v1/machines/{id}/files`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/files","method":"GET"}'
```

### Machine Events

Get machine event log

`GET /v1/machines/{id}/events`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/events","method":"GET"}'
```

### Session Exec

Execute a command within a persistent session

`POST /v1/machines/{id}/sessions/{session_id}/exec`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `session_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `command` | object | Yes |  |
| `cwd` | string | No |  |
| `env` | object | No |  |
| `stdin` | string | No |  |
| `stream` | boolean | No |  |
| `timeoutSeconds` | number | No |  |

```bash
# Replace {id}, {session_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/sessions/{session_id}/exec","body":{"command":"<object>","cwd":"<string>","env":"<object>","stdin":"<string>","stream":"<boolean>","timeoutSeconds":"<number>"}}'
```

### Execute Command

Run a command inside a machine. Accepts shell string or argv array.

`POST /v1/machines/{id}/exec`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `command` | object | Yes |  |
| `cwd` | string | No |  |
| `env` | object | No |  |
| `stdin` | string | No |  |
| `stream` | boolean | No |  |
| `timeoutSeconds` | number | No |  |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/exec","body":{"command":"<object>","cwd":"<string>","env":"<object>","stdin":"<string>","stream":"<boolean>","timeoutSeconds":"<number>"}}'
```

### Get Machine

Get machine details and status. Poll until ready is true before executing commands.

`GET /v1/machines/{id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}","method":"GET"}'
```

### Create Machine

Create a new microVM with specified image, resources, and network policy

`POST /v1/machines`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source` | object | Yes | OCI image or .smolmachine reference |
| `resources` | object | Yes | Machine resources: {cpus, memoryMb} |
| `ttlSeconds` | number | Yes | Max machine lifetime in seconds |
| `name` | string | No | Machine name |
| `network` | object | No | Network policy: {mode: open\|blocked} |
| `env` | object | No | Environment variables |
| `workdir` | string | No | Working directory |
| `autoStopSeconds` | number | No | Auto-stop after inactivity |
| `ephemeral` | boolean | No | Delete on stop |
| `mounts` | array | No | Volume mounts |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines","body":{"source":"<object>","resources":"<object>","ttlSeconds":"<number>","name":"<string>","network":"<object>","env":"<object>","workdir":"<string>","autoStopSeconds":"<number>","ephemeral":"<boolean>","mounts":"<array>"}}'
```

### Start Machine

Start a stopped machine

`POST /v1/machines/{id}/start`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/start"}'
```

### Delete Machine

Permanently delete a machine and its storage

`DELETE /v1/machines/{id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}","method":"DELETE"}'
```

### Stop Machine

Stop a running machine. Preserves disk state.

`POST /v1/machines/{id}/stop`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"smolmachines","path":"/v1/machines/{id}/stop"}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/smolmachines