---
canonical_url: "https://docs.composio.dev/toolkits/smol_machines"
markdown_url: "https://docs.composio.dev/toolkits/smol_machines.md"
product: "platform"
version: null
last_updated: null
---

# Smol Machines

Create and operate isolated Smol Cloud machines, run bounded commands, transfer files, and inspect account and usage information.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 12
- **Triggers:** 0
- **Slug:** `SMOL_MACHINES`
- **Version:** 00000000_00

## Tools

### Create Machine

**Slug:** `SMOL_MACHINES_CREATE_MACHINE`

Create one bounded Smol Cloud machine in the stopped state with explicit resources, a finite auto-stop interval and deletion TTL, and an explicit outbound network policy. Published ports remain authenticated by default. The conservative blocked default denies egress and may prevent uncached image pulls; unrestricted networking and unauthenticated public ingress each require explicit opt-in.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `env` | object | No | Environment variables configured inside the guest. At most 64 entries; keys and values are bounded by Composio policy. Do not include secrets unless the workload should be able to read them. |
| `cpus` | integer | No | Requested vCPUs, bounded to 1-8 by Composio policy; the account's effective maximum may be lower. |
| `name` | string | No | Optional display name only; later tools still require the exact returned machine id. |
| `ports` | array | No | Guest ports to publish, at most 16. Services must listen on 0.0.0.0. Published ports remain authenticated unless public is explicitly true. |
| `labels` | object | No | Optional labels used by LIST_MACHINES filters. Keys must match the provider's lowercase label syntax and values are limited to 255 characters. |
| `public` | boolean | No | Whether published ports allow unauthenticated public ingress. Defaults to false; set true only for a service that provides its own authentication. |
| `disk_gb` | integer | No | Requested disk in GiB, bounded to 1-100 by Composio policy; stored disk can continue billing while stopped. |
| `workdir` | string | No | Optional absolute guest working directory used by the machine. |
| `ephemeral` | boolean | No | Whether to use the provider's ephemeral-machine behavior in addition to the finite TTL. |
| `memory_mb` | integer | No | Requested memory in MiB, bounded to 512-16384 by Composio policy; the account's effective maximum may be lower. |
| `source_type` | string ("image" | "smolmachine") | No | Source kind: a container image reference or a Smol machine reference. |
| `ttl_seconds` | integer | No | Seconds until provider deletion, bounded to 300-86400 by Composio policy so the resource cannot live indefinitely. |
| `architecture` | string ("arm64" | "amd64") | No | Optional requested source architecture; omit to let the provider choose. |
| `network_mode` | string ("allowCidrs" | "blocked" | "open") | No | Outbound network policy. The default blocked mode denies all egress and may prevent an uncached image pull; choose allowCidrs with at least one host or CIDR for restricted egress, or open explicitly for unrestricted egress. |
| `network_cidrs` | array | No | IPv4 or IPv6 CIDR allowlist used only with allowCidrs. Each entry is limited to 253 characters by Composio policy; leave empty for the conservative default. |
| `network_hosts` | array | No | Host allowlist used only with allowCidrs. Each entry is limited to 253 characters by Composio policy; leave empty for the conservative default. |
| `source_reference` | string | Yes | Provider source reference, such as a documented container image reference. |
| `auto_stop_seconds` | integer | No | Idle seconds before compute stops, bounded to 60-3600 by Composio policy. Stopping does not delete storage or end disk billing. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Machine

**Slug:** `SMOL_MACHINES_DELETE_MACHINE`

Permanently delete one Smol Cloud machine by its exact machine ID. This irreversible operation removes all machine-local storage, ends its storage billing, and requires explicit confirmation. Export important data before calling this tool. Do not automatically retry after an ambiguous failure.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `machine_id` | string | Yes | Exact MachineInfo.id to permanently delete, typically beginning mach-. Machine names are not accepted or resolved. |
| `include_usage` | boolean | No | Whether to request synchronously settled usage and cost in the deletion response. Set false to request the empty 204 response variant. |
| `confirm_delete` | boolean | Yes | Must be true to confirm irreversible deletion of the exact machine and all of its machine-local storage. This value is validated locally and is never sent to Smol Machines. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download File

**Slug:** `SMOL_MACHINES_DOWNLOAD_FILE`

Download and offload one file from an exact cloud machine. Downloads are limited to 10 MB by Composio policy, and the read resets the machine's auto-stop idle timer.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Guest path relative to root, with no leading slash, NUL, empty segment, '.' segment, or '..' segment; at most 1024 UTF-8 bytes. |
| `machine_id` | string | Yes | Exact MachineInfo.id; machine names are not accepted or resolved. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Execute Command

**Slug:** `SMOL_MACHINES_EXEC_COMMAND`

Run one bounded foreground argv command on an exact hosted Smol Cloud machine. Execution can auto-start billable compute and can modify or delete guest data. Output is text-only, streaming and background execution are disabled, and the action never retries automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cwd` | string | No | Optional absolute guest working directory, limited to 1024 UTF-8 bytes by Composio policy. |
| `env` | object | No | Optional command environment variables. At most 32 entries are allowed; keys are limited to 128 characters, values to 2048 characters, and the combined keys and values to 16384 UTF-8 bytes by Composio policy. Do not place credentials here unless the task explicitly requires exposing them to the guest process. |
| `argv` | array | Yes | Executable and arguments as an argv array, for example ["python", "--version"]. No shell string parsing is performed. Each item is limited to 4096 characters and the array to 16384 UTF-8 bytes by Composio policy. |
| `user` | string | No | Optional image user name or numeric uid[:gid]. The provider must fail if the user is unsupported rather than silently selecting another user. |
| `stdin` | string | No | Optional non-interactive text sent to standard input, limited to 65536 UTF-8 bytes by Composio policy. |
| `machine_id` | string | Yes | Exact MachineInfo.id on the hosted provider, typically beginning mach-. Machine names are not accepted or resolved, and execution never falls back to the local host. |
| `timeout_seconds` | integer | No | Guest command timeout in seconds, bounded to 1-300 by Composio policy. The provider request gets 30 additional seconds of bounded network headroom. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account

**Slug:** `SMOL_MACHINES_GET_ACCOUNT`

Get the connected account's status, plan, effective machine limits, billing-period usage, and spend in integer micros.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Usage

**Slug:** `SMOL_MACHINES_GET_ACCOUNT_USAGE`

Get metered usage for the connected account's provider-defined period, keeping the requested and consumed metric windows distinct.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Machine

**Slug:** `SMOL_MACHINES_GET_MACHINE`

Get configuration, lifecycle state, and readiness for one cloud machine by its exact machine id, not by name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `machine_id` | string | Yes | Exact MachineInfo.id returned by create or list, typically beginning mach-; machine names are not accepted or resolved. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Machine Usage

**Slug:** `SMOL_MACHINES_GET_MACHINE_USAGE`

Get billing-period usage and cost in integer micros for one exact machine ID. CPU and memory metering can lag by several minutes while a machine is running, so mid-life usage and cost are a lower bound until metering rolls up; stop and delete trigger a final sample. Deleted machine usage remains available for the provider-documented 30-day lookup period.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `machine_id` | string | Yes | Exact MachineInfo.id, including a deleted machine ID for up to the provider-documented 30-day lookup period. Machine names are not accepted or resolved. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Machines

**Slug:** `SMOL_MACHINES_LIST_MACHINES`

List cloud machines owned by the connected account, optionally requiring all supplied labels to match.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | No | Optional label filters in key=value form; every supplied label must match. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Start Machine

**Slug:** `SMOL_MACHINES_START_MACHINE`

Start one stopped cloud machine by exact machine ID. A detached start returns before readiness and requires polling GET_MACHINE until ready=true.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `detach` | boolean | No | Set true to return immediately after the provider accepts the start. Then poll GET_MACHINE until ready is true. False waits for the blocking start response. |
| `machine_id` | string | Yes | Exact MachineInfo.id of the stopped machine, not a machine name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Stop Machine

**Slug:** `SMOL_MACHINES_STOP_MACHINE`

Stop compute for one cloud machine by exact id while preserving its filesystem. Stopping does not delete the machine: stored disk can continue billing and the machine can continue occupying a plan slot until deletion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `machine_id` | string | Yes | Exact MachineInfo.id returned by create, list, or get, not a machine name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload File

**Slug:** `SMOL_MACHINES_UPLOAD_FILE`

Upload a file of at most 8,000,000 bytes to a safe relative guest path on one cloud machine identified by its exact machine ID. This can replace existing guest data and resets the machine's auto-stop idle timer.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | File content to write, limited to 8,000,000 bytes. |
| `path` | string | Yes | Guest path relative to root with no leading slash, empty segments, dot segments, or NUL, for example workspace/app.py. |
| `machine_id` | string | Yes | Exact MachineInfo.id returned by create or list, not a machine name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |