> ## 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.

# Quickstart

> Use the Dedalus CLI to create a Dedalus Machine.

Create a machine, run a command, retrieve output, then open SSH.

## CLI

Control machines from a terminal, script, or agent.

<Steps>
  <Step title="Install the CLI">
    <CodeGroup>
      ```bash macOS/Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -fsSL https://raw.githubusercontent.com/dedalus-labs/dedalus-cli/main/scripts/install.sh | bash
      ```

      ```bash Homebrew theme={"theme":{"light":"github-light","dark":"github-dark"}}
      brew install dedalus-labs/tap/dedalus
      ```

      ```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
      irm https://raw.githubusercontent.com/dedalus-labs/dedalus-cli/main/scripts/install.ps1 | iex
      ```

      ```bash GitHub theme={"theme":{"light":"github-light","dark":"github-dark"}}
      git clone https://github.com/dedalus-labs/dedalus-cli.git
      cd dedalus-cli
      go install ./cmd/dedalus
      ```
    </CodeGroup>
  </Step>

  <Step title="Set your API key">
    Get a Dedalus API key from the [Dashboard](https://www.dedaluslabs.ai/dashboard/api-keys) and set it in your shell.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export DEDALUS_API_KEY=<your-key>
    ```
  </Step>

  <Step title="Create a machine">
    The CLI calls the [Machines API](/api-reference/dcs).

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dedalus machines create --vcpu 1 \
                            --memory-mib 1024 \
                            --storage-gib 5 \
                            --autosleep never
    ```

    Save the `machine_id`. Later commands use it.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "machine_id": "dm-0197f2a9-4d1c-7b8f-9f9b-3b7c1a5e0a12",
      "vcpu": 1,
      "memory_mib": 1024,
      "storage_gib": 5,
      "autosleep_seconds": 0,
      "desired_state": "running",
      "status": {
        "phase": "accepted",
        "reason": "Accepted",
        "retryable": true,
        "revision": "1",
        "last_transition_at": "2026-06-18T00:00:00Z",
        "last_progress_at": "2026-06-18T00:00:00Z"
      }
    }
    ```
  </Step>

  <Step title="Run a command">
    The CLI runs commands directly, without opening a shell.

    <Tip>Machine IDs start with `dm-`.</Tip>

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dedalus machines executions create \
      --machine-id <machine_id> \
      --command '["/bin/bash", "-c", "whoami && uname -a"]'
    ```

    Save the `execution_id`. Use it to retrieve the result.

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "execution_id": "wexec-7e2f9d4b8c1a4f0d9e6c2b1a5d8f3c0e4a9b6d7c",
      "machine_id": "dm-0197f2a9-4d1c-7b8f-9f9b-3b7c1a5e0a12",
      "status": "queued",
      "command": ["/bin/bash", "-c", "whoami && uname -a"],
      "created_at": "2026-06-18T00:00:02Z"
    }
    ```
  </Step>

  <Step title="Get the result">
    Poll the execution until its status is `succeeded`, then fetch the captured output.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dedalus machines executions retrieve \
      --machine-id <machine_id> \
      --execution-id <execution_id>

    dedalus machines executions output \
      --machine-id <machine_id> \
      --execution-id <execution_id>
    ```
  </Step>
</Steps>

## SSH

Use executions for agents. Use SSH for human shells and debugging.

Install packages and run normal Linux commands.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus ssh <machine_id>

# Inside the machine:
whoami && uname -a
```

## SDK

These examples create a machine, run a command, and print output.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import time

  from dedalus_sdk import Dedalus

  client = Dedalus()
  DONE = {"succeeded", "failed", "cancelled", "expired"}

  dm = client.machines.create(vcpu=1, memory_mib=1024, storage_gib=10)
  stream = client.machines.watch(machine_id=dm.machine_id)
  for _ in stream:
      pass

  exc = client.machines.executions.create(
      machine_id=dm.machine_id,
      command=["/bin/bash", "-c", "whoami && uname -a"],
  )
  while exc.status not in DONE:
      time.sleep(0.5)
      exc = client.machines.executions.retrieve(
          machine_id=dm.machine_id,
          execution_id=exc.execution_id,
      )
  if exc.status != "succeeded":
      raise RuntimeError(f"{exc.status}: {exc.error_code}: {exc.error_message}")

  out = client.machines.executions.output(
      machine_id=dm.machine_id,
      execution_id=exc.execution_id,
  )
  print(out.stdout)
  ```

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

  const client = new Dedalus();
  const DONE = new Set(["succeeded", "failed", "cancelled", "expired"]);
  const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

  const dm = await client.machines.create({
    vcpu: 1,
    memory_mib: 1024,
    storage_gib: 10,
  });
  const stream = await client.machines.watch({ machine_id: dm.machine_id });
  for await (const _ of stream) {}

  let exc = await client.machines.executions.create({
    machine_id: dm.machine_id,
    command: ["/bin/bash", "-c", "whoami && uname -a"],
  });
  while (!DONE.has(exc.status)) {
    await sleep(500);
    exc = await client.machines.executions.retrieve({
      machine_id: dm.machine_id,
      execution_id: exc.execution_id,
    });
  }
  if (exc.status !== "succeeded") {
    throw new Error(`${exc.status}: ${exc.error_code}: ${exc.error_message}`);
  }

  const out = await client.machines.executions.output({
    machine_id: dm.machine_id,
    execution_id: exc.execution_id,
  });
  console.log(out.stdout);
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  package main

  import (
      "context"
      "fmt"
      "time"

      dedalus "github.com/dedalus-labs/dedalus-go"
  )

  func main() {
      client := dedalus.NewClient()
      ctx := context.Background()
      done := map[dedalus.ExecutionStatus]bool{
          dedalus.ExecutionStatusSucceeded: true,
          dedalus.ExecutionStatusFailed:    true,
          dedalus.ExecutionStatusCancelled: true,
          dedalus.ExecutionStatusExpired:   true,
      }

      dm, err := client.Machines.New(ctx, dedalus.MachineNewParams{
          CreateParams: dedalus.CreateParams{
              VCPU: 1, MemoryMiB: 1024, StorageGiB: 10,
          },
      })
      check(err)
      stream := client.Machines.WatchStreaming(ctx, dedalus.MachineWatchParams{
          MachineID: dm.MachineID,
      })
      for stream.Next() {
      }
      check(stream.Err())

      exc, err := client.Machines.Executions.New(ctx, dedalus.MachineExecutionNewParams{
          MachineID: dm.MachineID,
          ExecutionCreateParams: dedalus.ExecutionCreateParams{
              Command: []string{"/bin/bash", "-c", "whoami && uname -a"},
          },
      })
      check(err)

      for !done[exc.Status] {
          time.Sleep(500 * time.Millisecond)
          exc, err = client.Machines.Executions.Get(ctx, dedalus.MachineExecutionGetParams{
              MachineID: dm.MachineID, ExecutionID: exc.ExecutionID,
          })
          check(err)
      }
      if exc.Status != dedalus.ExecutionStatusSucceeded {
          panic(fmt.Sprintf("%s: %s", exc.ErrorCode, exc.ErrorMessage))
      }

      out, err := client.Machines.Executions.Output(ctx, dedalus.MachineExecutionOutputParams{
          MachineID: dm.MachineID, ExecutionID: exc.ExecutionID,
      })
      check(err)
      fmt.Println(out.Stdout)
  }

  func check(err error) {
      if err != nil {
          panic(err)
      }
  }
  ```
</CodeGroup>

Next: sleep, wake, watch, or delete the machine in [Lifecycle](/dcs/dm/lifecycle).