Quickstart

Create a machine from the command line, then run whoami && uname -a from an SDK, the CLI, or SSH.

Using a coding agent? Install the agent skill for CLI setup and machine operations.

Install the CLI

curl -fsSL https://raw.githubusercontent.com/dedalus-labs/dedalus-cli/main/scripts/install.sh | bash

brew install dedalus-labs/tap/dedalus

irm https://raw.githubusercontent.com/dedalus-labs/dedalus-cli/main/scripts/install.ps1 | iex

Set your API key

Create an API key in the Dashboard, then export it in the terminal session to be used by the CLI to authenticate. The key identifies your organization. You do not need to find or set an organization ID. Leave DEDALUS_ORG_ID and --dedalus-org-id unset.

export DEDALUS_API_KEY="dsk_your_api_key"

Create a machine

dedalus machines create \
  --vcpu 1 \
  --memory-mib 4096 \
  --storage-gib 10 \
  --autosleep never

# Example output:
# {
#   "machine_id": "dm-...",
#   "vcpu": 1,
#   "memory_mib": 4096,
#   "storage_gib": 10,
#   "autosleep_seconds": 0,
#   "desired_state": "running",
#   "phase": "accepted"
# }

Save the returned machine_id. The dedalus machines create function takes flags for vCPU, memory, storage, and autosleep that determine the shape and behavior of your machine. You can leave the resource flags unset to use the default values shown in this example. Autosleep defaults to five minutes. Set autosleep to a different duration, or use never to keep the machine awake indefinitely.

Run your first command

Each option below runs the same command, returning the Linux user and kernel information. Use the CLI for agents or from a script, the SDK for backend services, or SSH when you need an interactive terminal session.

Create an execution, wait for it to succeed, then retrieve its output:

MACHINE_ID="dm-..."
dedalus machines executions create \
  --machine-id "$MACHINE_ID" \
  --command '["/bin/bash", "-c", "whoami && uname -a"]'

EXECUTION_ID="wexec-..."
dedalus machines executions retrieve \
  --machine-id "$MACHINE_ID" \
  --execution-id "$EXECUTION_ID"
dedalus --transform stdout --raw-output machines executions output \
  --machine-id "$MACHINE_ID" \
  --execution-id "$EXECUTION_ID"

# Example output:
# root
# Linux dedalus <kernel details> x86_64 GNU/Linux

The retrieve response must report succeeded before you request output. For production polling, follow the execution workflow.

Install the Python SDK:

pip install dedalus-sdk

Run a command and print its output:

import time

from dedalus_sdk import Dedalus

client = Dedalus()
machine_id = "dm-..."
done = {"succeeded", "failed", "cancelled", "expired"}

execution = client.machines.executions.create(
    machine_id=machine_id,
    command=["/bin/bash", "-c", "whoami && uname -a"],
)
while execution.status not in done:
    time.sleep((execution.retry_after_ms or 500) / 1000)
    execution = client.machines.executions.retrieve(
        machine_id=machine_id,
        execution_id=execution.execution_id,
    )
if execution.status != "succeeded":
    raise RuntimeError(f"{execution.status}: {execution.error_message}")

output = client.machines.executions.output(
    machine_id=machine_id,
    execution_id=execution.execution_id,
)
print(output.stdout)

# Example output:
# root
# Linux dedalus <kernel details> x86_64 GNU/Linux

Prefer another language? Use the TypeScript or Go SDK.

Open an interactive shell for human debugging, then run the same command inside the machine:

dedalus ssh dm-...
whoami && uname -a

# Example output:
# root
# Linux dedalus <kernel details> x86_64 GNU/Linux

Agents should prefer executions because they provide structured status and captured output. See SSH for session details and host verification.

Manage sleep, wake, autosleep, and deletion in Lifecycle.

Introduction

Lifecycle