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

# Dedalus Machines API

> Programmatic access to secure, on-demand cloud workspaces for AI agents and developers

export const LibCard = ({icon, name, version, install, github, docs}) => <div style={{
  border: "1px solid var(--border-primary, #e5e7eb)",
  borderRadius: "2px",
  padding: "20px",
  display: "flex",
  flexDirection: "column",
  gap: "14px"
}}>
    <div style={{
  display: "flex",
  alignItems: "center",
  gap: "12px"
}}>
      <span style={{
  fontFamily: "var(--font-mono, monospace)",
  fontSize: "20px",
  fontWeight: 700,
  letterSpacing: "-0.02em",
  opacity: 0.7,
  minWidth: "36px"
}}>{icon}</span>
      <div>
        <div style={{
  fontWeight: 600,
  fontSize: "14px",
  letterSpacing: "-0.01em"
}}>{name}</div>
        <div style={{
  fontSize: "11px",
  opacity: 0.4,
  fontFamily: "var(--font-mono, monospace)"
}}>{version}</div>
      </div>
    </div>
    <div style={{
  fontFamily: "var(--font-mono, monospace)",
  fontSize: "12px",
  background: "var(--background-secondary, #f8f8f8)",
  borderRadius: "2px",
  padding: "8px 10px",
  whiteSpace: "nowrap",
  overflow: "hidden",
  textOverflow: "ellipsis",
  letterSpacing: "-0.01em"
}}>{install}</div>
    <div style={{
  display: "flex",
  alignItems: "center",
  gap: "6px",
  borderTop: "1px solid var(--border-primary, #e5e7eb)",
  paddingTop: "12px"
}}>
      <a href={github} target="_blank" rel="noopener noreferrer" style={{
  opacity: 0.35,
  display: "flex",
  alignItems: "center"
}}>
        <Icon icon="github" size={15} />
      </a>
      <a href={docs} target="_blank" rel="noopener noreferrer" style={{
  flex: 1,
  textAlign: "center",
  fontSize: "12px",
  fontWeight: 500,
  padding: "5px 0",
  border: "1px solid var(--border-primary, #e5e7eb)",
  borderRadius: "2px",
  textDecoration: "none",
  color: "inherit",
  letterSpacing: "-0.01em"
}}>
        Read Docs
      </a>
    </div>
  </div>;

## Libraries

<div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))", gap: "12px" }}>
  <LibCard icon="TS" name="TypeScript" version="0.2.0" install="npm install dedalus" github="https://github.com/dedalus-labs/dedalus-typescript" docs="https://github.com/dedalus-labs/dedalus-typescript#readme" />

  <LibCard icon="PY" name="Python" version="0.2.0" install="pip install dedalus-sdk" github="https://github.com/dedalus-labs/dedalus-python" docs="https://github.com/dedalus-labs/dedalus-python#readme" />

  <LibCard icon="GO" name="Go" version="0.3.0" install="go get github.com/dedalus-labs/dedalus-go" github="https://github.com/dedalus-labs/dedalus-go" docs="https://pkg.go.dev/github.com/dedalus-labs/dedalus-go" />

  <LibCard icon="$>" name="CLI" version="0.3.0" install="brew install dedalus-labs/tap/dedalus" github="https://github.com/dedalus-labs/dedalus-cli" docs="https://github.com/dedalus-labs/dedalus-cli#readme" />

  <LibCard icon="TF" name="Terraform" version="0.1.0" install="dedalus-labs/dedalus" github="https://github.com/dedalus-labs/terraform-provider-dedalus" docs="https://registry.terraform.io/providers/dedalus-labs/dedalus/latest/docs" />
</div>

## Getting Started

<Steps>
  <Step title="Get an API key">
    Sign up at the [Dedalus Dashboard](https://dedaluslabs.ai/dashboard/api-keys) and create an API key.
  </Step>

  <Step title="Install an SDK">
    Pick a language from the **Install** tabs above.
  </Step>

  <Step title="Create a machine">
    Create your first cloud workspace with 2 vCPUs, 4 GB RAM, 20 GB storage, and 5-minute auto-sleep.

    <CodeGroup>
      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import Dedalus from "dedalus";

      const client = new Dedalus();
      const machine = await client.machines.create({
        vcpu: 2, memory_mib: 4096, storage_gib: 20, autosleep: "5m",
      });
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      from dedalus_sdk import Dedalus

      client = Dedalus()
      machine = client.machines.create(
          vcpu=2, memory_mib=4096, storage_gib=20, autosleep="5m",
      )
      ```

      ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://dcs.dedaluslabs.ai/v1/machines \
        -H "Authorization: Bearer $DEDALUS_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"vcpu": 2, "memory_mib": 4096, "storage_gib": 20, "autosleep": "5m"}'
      ```
    </CodeGroup>
  </Step>
</Steps>

## Authentication

All endpoints require a Bearer token.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer YOUR_API_KEY
```

## Lifecycle payloads

`POST /v1/machines` creates a running machine. `PATCH /v1/machines/{machine_id}` updates size or sleep policy. Mutating requests require an `Idempotency-Key` header.

Create request:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "vcpu": 2,
  "memory_mib": 4096,
  "storage_gib": 20,
  "autosleep": "5m"
}
```

Update the sleep policy without resizing:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "autosleep": "15m"
}
```

Disable auto-sleep:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "autosleep": "never"
}
```

Resize request:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "vcpu": 4,
  "memory_mib": 8192,
  "storage_gib": 50
}
```

All lifecycle mutations return the machine shape:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "machine_id": "dm-abc123",
  "vcpu": 2,
  "memory_mib": 4096,
  "storage_gib": 20,
  "autosleep_seconds": 300,
  "desired_state": "running",
  "status": {
    "phase": "accepted",
    "reason": "machine create accepted",
    "retryable": false,
    "revision": "rv-abc123",
    "last_transition_at": "2026-05-07T12:00:00Z",
    "last_progress_at": "2026-05-07T12:00:00Z"
  }
}
```

`POST /v1/machines/{machine_id}/sleep` and `POST /v1/machines/{machine_id}/wake` have no request body and return the same machine shape. `autosleep` defaults to `"5m"`. Valid request values are duration strings like `"30s"`, `"30m"`, `"2h"`, `"7d3h4s"`, or `"1w3d"`, raw seconds as strings from `"0"` through `"9223372036"`, or `"never"` to disable auto-sleep. Responses expose the resolved value as `autosleep_seconds`.

## Machines

| Method   | Path                              | Description                                                         |
| -------- | --------------------------------- | ------------------------------------------------------------------- |
| `POST`   | `/v1/machines`                    | [Create machine](/dcs/api/machine-lifecycle/create-machine)         |
| `GET`    | `/v1/machines`                    | [List machines](/dcs/api/machine-lifecycle/list-machines)           |
| `GET`    | `/v1/machines/{machine_id}`       | [Get machine](/dcs/api/machine-lifecycle/get-machine)               |
| `PATCH`  | `/v1/machines/{machine_id}`       | [Update machine](/dcs/api/machine-lifecycle/update-machine)         |
| `DELETE` | `/v1/machines/{machine_id}`       | [Destroy machine](/dcs/api/machine-lifecycle/destroy-machine)       |
| `POST`   | `/v1/machines/{machine_id}/wake`  | [Wake machine](/dcs/api/machine-lifecycle/wake-a-sleeping-machine)  |
| `POST`   | `/v1/machines/{machine_id}/sleep` | [Sleep machine](/dcs/api/machine-lifecycle/sleep-a-running-machine) |

## SSH

| Method   | Path                                         | Description                                                         |
| -------- | -------------------------------------------- | ------------------------------------------------------------------- |
| `POST`   | `/v1/machines/{machine_id}/ssh`              | [Create SSH session](/dcs/api/machine-lifecycle/create-ssh-session) |
| `GET`    | `/v1/machines/{machine_id}/ssh`              | [List SSH sessions](/dcs/api/machine-lifecycle/list-ssh-sessions)   |
| `DELETE` | `/v1/machines/{machine_id}/ssh/{session_id}` | [Delete SSH session](/dcs/api/machine-lifecycle/delete-ssh-session) |

## Executions

| Method   | Path                                                  | Description                                                     |
| -------- | ----------------------------------------------------- | --------------------------------------------------------------- |
| `POST`   | `/v1/machines/{machine_id}/executions`                | [Create execution](/dcs/api/machine-lifecycle/create-execution) |
| `GET`    | `/v1/machines/{machine_id}/executions`                | [List executions](/dcs/api/machine-lifecycle/list-executions)   |
| `DELETE` | `/v1/machines/{machine_id}/executions/{execution_id}` | [Delete execution](/dcs/api/machine-lifecycle/delete-execution) |

## Terminals

| Method | Path                                                       | Description                                                                          |
| ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `POST` | `/v1/machines/{machine_id}/terminals`                      | [Create terminal](/dcs/api/machine-lifecycle/create-terminal)                        |
| `GET`  | `/v1/machines/{machine_id}/terminals/{terminal_id}/stream` | [Connect WebSocket](/dcs/api/machine-lifecycle/connect-to-terminal-websocket-stream) |

## Previews & Artifacts

| Method | Path                                  | Description                                                 |
| ------ | ------------------------------------- | ----------------------------------------------------------- |
| `POST` | `/v1/machines/{machine_id}/previews`  | [Create preview](/dcs/api/machine-lifecycle/create-preview) |
| `GET`  | `/v1/machines/{machine_id}/artifacts` | [List artifacts](/dcs/api/machine-lifecycle/list-artifacts) |

## Usage & Metering

| Method | Path                         | Description                              |
| ------ | ---------------------------- | ---------------------------------------- |
| `GET`  | `/v1/usage`                  | Get usage summary                        |
| `GET`  | `/v1/usage/machines/compute` | List per-machine compute usage breakdown |
| `GET`  | `/v1/usage/machines/storage` | List per-machine storage usage breakdown |
| `GET`  | `/v1/metering/health`        | Get metering pipeline health             |