---
name: dedalus-machines
description: Set up and operate Dedalus Machines. Use when an agent needs a persistent Linux sandbox, remote code execution, SSH, a temporary service, or help configuring CLI authentication and the API base URL.
---

# Dedalus Machines

## API address

Use `https://dcs.dedaluslabs.ai` for DCS requests. Set the address in the
agent's shell so every command uses the same endpoint:

```bash
export DEDALUS_BASE_URL=https://dcs.dedaluslabs.ai
```

You can also pass `--base-url https://dcs.dedaluslabs.ai` on each command.
Use the full HTTPS URL without adding `/v1`. Make sure separate agent shells
inherit `DEDALUS_BASE_URL` and `DEDALUS_API_KEY`, including for SSH, polling,
sleep, and deletion.

## Setup and access check

1. Run `dedalus --version` and `dedalus --help`. Command examples below were
   checked against CLI v0.5.0 help. Consult installed command help for differences.
2. If missing, install with `curl -fsSL https://www.dedaluslabs.ai/install/dedalus | bash`.
   Ensure the binary is on PATH. If macOS blocks it, have the user approve the
   official binary in System Settings > Privacy & Security > Allow Anyway.
3. Use the user's API key through `DEDALUS_API_KEY`. Reuse an existing
   configured key without printing it. If absent, ask the user to configure it
   in the agent's environment. Do not put keys in this skill, command arguments,
   source files, or logs. A key exported in a separate terminal may not be
   available inside Cursor or another agent process.
4. The API key determines its organization. Do not ask the user to find an org
   ID. Leave `DEDALUS_ORG_ID`, `--dedalus-org-id`, and `X-Dedalus-Org-Id` unset
   for ordinary API-key setup, even if command help or OpenAPI exposes them.
   If supplied, the ID must match the key's organization. It cannot switch organizations.
5. Verify access with a read-only request before creating a machine:

   ```bash
   dedalus --format json machines list --limit 1
   ```

An empty successful list is valid. A successful list verifies authentication.
Creation also requires beta access and available account quota.

## Create and use a machine

Create only when the user's task needs a new machine. Otherwise reuse the
specified machine. Use autosleep for ordinary agent work.

```bash
MACHINE_ID=$(dedalus \
  --format json --transform machine_id --raw-output machines create \
  --vcpu 1 --memory-mib 1024 --storage-gib 10 --autosleep 30m) &&
dedalus --format jsonl \
  machines watch --machine-id "$MACHINE_ID"
```

Inspect the final lifecycle state before using the machine. Preserve its ID
across agent tool calls. A shell variable may not survive the next call.
Machine IDs are bare, lowercase, hyphenated UUIDs. Pass the returned value unchanged.

Use `dedalus ssh "$MACHINE_ID"`
for an interactive shell.

For agent-driven commands, prefer structured executions:

```bash
EXEC_ID=$(dedalus \
  --format json --transform execution_id --raw-output machines executions create \
  --machine-id "$MACHINE_ID" --command '["/bin/bash","-lc","uname -a && whoami"]' \
  --cwd /root --timeout-ms 60000)

dedalus --format json \
  machines executions retrieve --machine-id "$MACHINE_ID" --execution-id "$EXEC_ID"

dedalus --format json \
  machines executions output --machine-id "$MACHINE_ID" --execution-id "$EXEC_ID"
```

Creation returns before execution finishes. Poll `retrieve` until terminal,
then fetch `output` and check the exit code. Report failures with the request
ID and safe error details. Use `/root`. Do not assume `/home/machine` exists.
For other operations, discover flags with `dedalus machines <command> --help`.

## Persistence

Sleep a machine when pausing durable work. Wake it before resuming. Keep its ID.

```bash
dedalus machines sleep --machine-id "$MACHINE_ID"
dedalus machines wake --machine-id "$MACHINE_ID"
```

Delete only a clearly disposable machine or when the user wants its data gone:

```bash
dedalus machines delete --machine-id "$MACHINE_ID"
```

Do not delete while executions are running unless cancellation is intended.
Use `--autosleep never` deliberately for services that must stay reachable.

## Authentication troubleshooting

- **401:** First verify that the actual failing command uses the intended
  base URL and inherits `DEDALUS_API_KEY`. Check for unintended `DEDALUS_X_API_KEY`
  or org overrides without printing their values. Do not rotate a working key
  when the client used the wrong API address.
- **403 `BETA_ACCESS_REQUIRED`:** Authentication passed, but the key's organization
  lacks DCS beta admission. Ask the Dedalus support contact to check its grant.
- **Other failures:** Preserve the HTTP status, error code, and request ID. Do not
  label capacity, billing, or service errors as invalid-key failures.

See the [CLI reference](https://docs.dedaluslabs.ai/dcs/cli) for other operations.
Use the same API address when following public examples. Command syntax checked
against CLI v0.5.0 on 2026-09-08.