You've been invited to Dedalus Labs

Here's $20 in free credits to power your projects and start building agents with the Dedalus SDK in minutes.

$20 Free Credits

Loading…

SDK Quickstart

50+

AI Models

100+

MCP Servers

<5min

To First Agent

24/7

Discord Support

Quick Start

Get Started in Minutes

Install the CLI, drop in your key, and spin up an isolated Linux VM. The commands below are the same ones we ship on the homepage — copy, paste, run.

Claim Your Free Credits

Scroll up to claim your $20 in free credits. Credits are valid for 30 days after claiming.

Install the Dedalus CLI

One install command per shell. Use the curl or PowerShell tab to match your machine.

$ curl -fsSL https://www.dedaluslabs.ai/install/dedalus | bash

Set your API key

Grab your key from the dashboard and export it in your shell, or stash it in a .env file.

$ export DEDALUS_API_KEY=<YOUR_API_KEY>

Create a machine

Boots a fresh Linux VM with durable storage. Note the returned machine id (dm-…).

Terminal

$ dedalus machines create --vcpu 1 --memory-mib 1024 --storage-gib 10

Run a command

Headless exec against the running machine. Works great from an agent loop.

Terminal

$ dedalus machines exec --machine-id dm-<id> -- whoami

SSH into the machine

When you need a real shell. Same VM, same storage, stateful across sessions.

Terminal

$ dedalus ssh dm-<id>

Dedalus Machines Docs SDK Reference

Agent Instructions

Paste this into your coding agent

The canonical Dedalus Machines quickstart — the same doc we ship on /beta/dedalus-machines. Copy the whole thing into Claude Code, Cursor, Codex, or any coding agent to teach it how to drive a VM.

Open full page

# Quickstart

Dedalus Machines are isolated Linux microVMs with durable storage, SSH,
and a headless execution API. Copy, paste, run.

## Setup

```bash
brew install dedalus-labs/tap/dedalus
```

```bash
export DEDALUS_BASE_URL=https://dev.dcs.dedaluslabs.ai
export DEDALUS_API_KEY=<YOUR_DEDALUS_API_KEY>
```

### SDKs

```bash
pip install dedalus-sdk          # Python
npm install dedalus              # TypeScript
go get github.com/dedalus-labs/dedalus-go  # Go
```

## Create a machine and run a command

### CLI

```bash
dedalus machines create --vcpu 1 --memory-mib 1024 --storage-gib 10
# Note the machine_id (dm-...)

dedalus machines exec --machine-id dm-<id> -- whoami
```

### Python

```python
from dedalus_sdk import Dedalus
import os, time

client = Dedalus(
    api_key=os.environ["DEDALUS_API_KEY"],
    base_url="https://dev.dcs.dedaluslabs.ai",
)

dm = client.machines.create(vcpu=1, memory_mib=1024, storage_gib=10)

while dm.status.phase != "running":
    time.sleep(1)
    dm = client.machines.retrieve(machine_id=dm.machine_id)

exc = client.machines.executions.create(
    machine_id=dm.machine_id,
    command=["/bin/bash", "-c", "whoami && uname -a"],
)
while exc.status not in ("succeeded", "failed"):
    time.sleep(0.5)
    exc = client.machines.executions.retrieve(
        machine_id=dm.machine_id, execution_id=exc.execution_id,
    )
output = client.machines.executions.output(
    machine_id=dm.machine_id, execution_id=exc.execution_id,
)
print(output.stdout)
```

### TypeScript

```typescript
import Dedalus from "dedalus";

const client = new Dedalus({
  apiKey: process.env.DEDALUS_API_KEY,
  baseURL: "https://dev.dcs.dedaluslabs.ai",
});

let dm = await client.machines.create({
  vcpu: 1,
  memory_mib: 1024,
  storage_gib: 10,
});

while (dm.status.phase !== "running") {
  await new Promise((r) => setTimeout(r, 1000));
  dm = await client.machines.retrieve({ machine_id: dm.machine_id });
}

const exec = await client.machines.executions.create({
  machine_id: dm.machine_id,
  command: ["/bin/bash", "-c", "whoami && uname -a"],
});
let result = exec;
while (result.status !== "succeeded" && result.status !== "failed") {
  await new Promise((r) => setTimeout(r, 500));
  result = await client.machines.executions.retrieve({
    machine_id: dm.machine_id,
    execution_id: exec.execution_id,
  });
}
const output = await client.machines.executions.output({
  machine_id: dm.machine_id,
  execution_id: exec.execution_id,
});
console.log(output.stdout);
```

### Go

```go
package main

import (
    "context"
    "fmt"
    "time"

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

func main() {
    client := dedalus.NewClient(
        option.WithAPIKey("your-api-key"),
        option.WithBaseURL("https://dev.dcs.dedaluslabs.ai"),
    )
    ctx := context.Background()

    dm, _ := client.Machines.New(ctx, dedalus.MachineNewParams{
        CreateParams: dedalus.CreateParams{
            VCPU: 1, MemoryMiB: 1024, StorageGiB: 10,
        },
    })

    for dm.Status.Phase != "running" {
        time.Sleep(time.Second)
        dm, _ = client.Machines.Get(ctx, dedalus.MachineGetParams{
            MachineID: dm.MachineID,
        })
    }

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

    for exc.Status != "succeeded" && exc.Status != "failed" {
        time.Sleep(500 * time.Millisecond)
        exc, _ = client.Machines.Executions.Get(ctx, dedalus.MachineExecutionGetParams{
            MachineID: dm.MachineID, ExecutionID: exc.ExecutionID,
        })
    }

    output, _ := client.Machines.Executions.Output(ctx, dedalus.MachineExecutionOutputParams{
        MachineID: dm.MachineID, ExecutionID: exc.ExecutionID,
    })
    fmt.Println(output.Stdout)
}
```

## Watch machine status (SSE)

Instead of polling, stream status changes via Server-Sent Events (SSE):

```bash
curl -N https://dev.dcs.dedaluslabs.ai/v1/machines/dm-<id>/status/stream \
  -H "Authorization: Bearer $DEDALUS_API_KEY" \
  -H "Accept: text/event-stream"
```

Each event is a JSON object with the full machine state:

```text
event: status
data: {"machine_id":"dm-...","status":{"phase":"running",...}}
```

In code, use any SSE client. The stream stays open until the machine is
destroyed or you disconnect.

```python
import os, json, urllib.request

machine_id = "dm-..."  # from create output
url = f"https://dev.dcs.dedaluslabs.ai/v1/machines/{machine_id}/status/stream"
req = urllib.request.Request(url, headers={
    "Authorization": f"Bearer {os.environ['DEDALUS_API_KEY']}",
    "Accept": "text/event-stream",
})
with urllib.request.urlopen(req) as resp:
    for line in resp:
        line = line.decode().strip()
        if line.startswith("data: "):
            status = json.loads(line[6:])
            print(status["status"]["phase"])
            if status["status"]["phase"] == "running":
                break
```

## Exec patterns

Machines are stateful Linux VMs. You're root inside your own box, `$HOME` is
`/root`, and everything under `~` persists. Files written in one exec are visible
in the next. The machine stays running until you sleep or delete it.

```python
def exec_cmd(client, machine_id, command):
    """Run a command and return stdout."""
    exc = client.machines.executions.create(
        machine_id=machine_id, command=command,
    )
    while exc.status not in ("succeeded", "failed"):
        time.sleep(0.5)
        exc = client.machines.executions.retrieve(
            machine_id=machine_id, execution_id=exc.execution_id,
        )
    output = client.machines.executions.output(
        machine_id=machine_id, execution_id=exc.execution_id,
    )
    return output.stdout


machine_id = dm.machine_id  # from create output above

exec_cmd(client, machine_id, ["apt-get", "install", "-y", "python3-pip"])

exec_cmd(client, machine_id, ["/bin/bash", "-c",
    "cd ~ && git clone https://github.com/org/repo"])

exec_cmd(client, machine_id, ["/bin/bash", "-c",
    "cd ~/repo && python -m pytest -v 2>&1"])

exec_cmd(client, machine_id, ["/bin/bash", "-c",
    "nohup python server.py > /tmp/server.log 2>&1 &"])

exec_cmd(client, machine_id, ["cat", "/root/repo/output.json"])

exec_cmd(client, machine_id, ["/bin/bash", "-c",
    "echo 'hello' > ~/test.txt"])

exec_cmd(client, machine_id, ["/bin/bash", "-c",
    "free -h && df -h ~"])
```

## Machine lifecycle

```bash
dedalus machines list

dedalus machines retrieve --machine-id dm-<id>

# Sleep (zero compute cost, storage persists)
dedalus machines update --machine-id dm-<id> --desired-state sleeping

# Wake
dedalus machines update --machine-id dm-<id> --desired-state running

# Resize (live, no restart)
dedalus machines update --machine-id dm-<id> --vcpu 2 --memory-mib 2048

# Delete (grab revision from retrieve output)
dedalus machines delete --machine-id dm-<id> --if-match <revision>
```

## Examples

- [openclaw-ddls](https://github.com/annyzhou/openclaw-ddls): Host OpenClaw on a Dedalus Machine!

Resources

Featured Projects & Tutorials

Explore what builders are creating with Dedalus and learn from step-by-step tutorials.

Featured Projects

Real projects built by developers using Dedalus

Winner

Discer.io

by Roman Slack

1st Place YC Challenge + Best Use of Dedalus - HackPrinceton 2025

Learn Agentic AI through play. An MMO sandbox to build and deploy AI workflows with drag-and-drop blocks, like Scratch, but for AI agents.

Agentic AIEducationalGame

GitHub Devpost

Winner

SpatialMD

by Aaryaman Bajaj

Best Use of Dedalus - HackPrinceton 2025

Surgical AR guidance system that enables remote experts to guide rural surgeons using 3D reconstructions and AI-powered safety analysis.

HealthcareARAI Safety

GitHub Devpost

Winner

CourtRoom

by Mehul Goel, Utsav Kataria

Best Use of Dedalus API - TartanHacks 2026

AI courtroom debate engine where defense and prosecution agents argue with citation-locked evidence, cross-examine each other, and stream a judge verdict in real time.

AI DebateMulti-AgentCitations

GitHub

Winner

Jiri

by Nihal Josyula, Deepansh Saxena, Rithvik Duddupudi, Vedant Joshi

Best Use of Tool Calling - TartanHacks 2025

Self-improving agent that starts with zero tools, discovers MCP servers at runtime from user intent, and uses caching plus metrics-based preloading to speed future calls.

Tool CallingDynamic DiscoveryMCP

GitHub

Winner

CADly

by Nayansh Patni

Best Use of Dedalus Tool Calling (Runners Up) - TartanHacks 2026

AI-powered design-for-manufacturing platform that checks CAD parts for process violations, auto-fixes geometry, and runs Dedalus multi-agent design reviews.

CADManufacturingMulti-Agent

GitHub

Messenger AI

by Jaehun Baek, John Kim, Joshua Song

AI-powered group messaging assistant that reads texts, PDFs, and images to enrich conversations using Dedalus Labs and Photon's iMessage Kit.

MessagingiMessageMulti-modal

Devpost

Amelia

by Aaryaman Bajaj

AI co-pilot for air traffic controllers that surfaces real-time flight and weather insights, automating routine communication and reducing cognitive load.

AviationReal-time DataSafety

Devpost

Medverse

by Dongkon Lee, Kevin Park

The world's first AI-interactive 3D medical textbook, explore anatomy models of the brain, heart, and skeleton guided by an adaptive AI tutor.

Healthcare3DEducation

Devpost

GreenTrip

by Brooke Xu, +3 more

Sustainable travel planning platform that generates personalized itineraries with carbon footprint tracking, eco-credits, and geographically optimized activities.

TravelSustainabilityPlanning

Devpost

Tutorials & Guides

Step-by-step guides to build your first project

TutorialBlog + Video

Build a CRM Agent with X API Integration

Learn how to build a CRM agent that searches X for high-value leads using DAuth.

TutorialBlog + Video

Finance Research Agent Tutorial

Create an AI agent that analyzes market data and generates investment insights.

TutorialBlog + Video

One-Click PDF Generator with MCP

Build a PDF generation system using MCP servers and the Dedalus SDK.

Product

DAuth: Secure Authentication for AI Agents

Learn how DAuth keeps your API keys secure while enabling powerful integrations.

Community

Join Our Community

Get help, share your progress, and connect with other builders on Discord. Star our repos to stay updated!

Join Dedalus Discord

Get help and connect with other builders

Active Now

Join Server

Star Our Repos

Support us and stay updated with the latest features

dedalus-cli

Command-line client for Dedalus Machines

Rust

...

dedalus-python

Python SDK for Dedalus Machines and the chat API

Python

...

dedalus-typescript

TypeScript SDK for Dedalus Machines and the chat API

TypeScript

...

dedalus-go

Go SDK for Dedalus Machines and the chat API

...

dedalus-sdk-python

Python SDK for building AI agents with Dedalus

Python

...

dedalus-sdk-typescript

TypeScript/JavaScript SDK for Dedalus

TypeScript

...

dedalus-mcp-python

MCP framework for building MCP servers

Python

...

wingman

AI coding assistant powered by Dedalus

TypeScript

...

View all repositories on GitHub

# Quickstart Dedalus Machines are isolated Linux microVMs with durable storage, SSH, and a headless execution API. Copy, paste, run. ## Setup ```bash brew install dedalus-labs/tap/dedalus ``` ```bash export DEDALUS_BASE_URL=https://dev.dcs.dedaluslabs.ai export DEDALUS_API_KEY=<YOUR_DEDALUS_API_KEY> ``` ### SDKs ```bash pip install dedalus-sdk # Python npm install dedalus # TypeScript go get github.com/dedalus-labs/dedalus-go # Go ``` ## Create a machine and run a command ### CLI ```bash dedalus machines create --vcpu 1 --memory-mib 1024 --storage-gib 10 # Note the machine_id (dm-...) dedalus machines exec --machine-id dm-<id> -- whoami ``` ### Python ```python from dedalus_sdk import Dedalus import os, time client = Dedalus( api_key=os.environ["DEDALUS_API_KEY"], base_url="https://dev.dcs.dedaluslabs.ai", ) dm = client.machines.create(vcpu=1, memory_mib=1024, storage_gib=10) while dm.status.phase != "running": time.sleep(1) dm = client.machines.retrieve(machine_id=dm.machine_id) exc = client.machines.executions.create( machine_id=dm.machine_id, command=["/bin/bash", "-c", "whoami && uname -a"], ) while exc.status not in ("succeeded", "failed"): time.sleep(0.5) exc = client.machines.executions.retrieve( machine_id=dm.machine_id, execution_id=exc.execution_id, ) output = client.machines.executions.output( machine_id=dm.machine_id, execution_id=exc.execution_id, ) print(output.stdout) ``` ### TypeScript ```typescript import Dedalus from "dedalus"; const client = new Dedalus({ apiKey: process.env.DEDALUS_API_KEY, baseURL: "https://dev.dcs.dedaluslabs.ai", }); let dm = await client.machines.create({ vcpu: 1, memory_mib: 1024, storage_gib: 10, }); while (dm.status.phase !== "running") { await new Promise((r) => setTimeout(r, 1000)); dm = await client.machines.retrieve({ machine_id: dm.machine_id }); } const exec = await client.machines.executions.create({ machine_id: dm.machine_id, command: ["/bin/bash", "-c", "whoami && uname -a"], }); let result = exec; while (result.status !== "succeeded" && result.status !== "failed") { await new Promise((r) => setTimeout(r, 500)); result = await client.machines.executions.retrieve({ machine_id: dm.machine_id, execution_id: exec.execution_id, }); } const output = await client.machines.executions.output({ machine_id: dm.machine_id, execution_id: exec.execution_id, }); console.log(output.stdout); ``` ### Go ```go package main import ( "context" "fmt" "time" "github.com/dedalus-labs/dedalus-go" "github.com/dedalus-labs/dedalus-go/option" ) func main() { client := dedalus.NewClient( option.WithAPIKey("your-api-key"), option.WithBaseURL("https://dev.dcs.dedaluslabs.ai"), ) ctx := context.Background() dm, _ := client.Machines.New(ctx, dedalus.MachineNewParams{ CreateParams: dedalus.CreateParams{ VCPU: 1, MemoryMiB: 1024, StorageGiB: 10, }, }) for dm.Status.Phase != "running" { time.Sleep(time.Second) dm, _ = client.Machines.Get(ctx, dedalus.MachineGetParams{ MachineID: dm.MachineID, }) } exc, _ := client.Machines.Executions.New(ctx, dedalus.MachineExecutionNewParams{ MachineID: dm.MachineID, ExecutionCreateParams: dedalus.ExecutionCreateParams{ Command: []string{"/bin/bash", "-c", "whoami && uname -a"}, }, }) for exc.Status != "succeeded" && exc.Status != "failed" { time.Sleep(500 * time.Millisecond) exc, _ = client.Machines.Executions.Get(ctx, dedalus.MachineExecutionGetParams{ MachineID: dm.MachineID, ExecutionID: exc.ExecutionID, }) } output, _ := client.Machines.Executions.Output(ctx, dedalus.MachineExecutionOutputParams{ MachineID: dm.MachineID, ExecutionID: exc.ExecutionID, }) fmt.Println(output.Stdout) } ``` ## Watch machine status (SSE) Instead of polling, stream status changes via Server-Sent Events (SSE): ```bash curl -N https://dev.dcs.dedaluslabs.ai/v1/machines/dm-<id>/status/stream \ -H "Authorization: Bearer $DEDALUS_API_KEY" \ -H "Accept: text/event-stream" ``` Each event is a JSON object with the full machine state: ```text event: status data: {"machine_id":"dm-...","status":{"phase":"running",...}} ``` In code, use any SSE client. The stream stays open until the machine is destroyed or you disconnect. ```python import os, json, urllib.request machine_id = "dm-..." # from create output url = f"https://dev.dcs.dedaluslabs.ai/v1/machines/{machine_id}/status/stream" req = urllib.request.Request(url, headers={ "Authorization": f"Bearer {os.environ['DEDALUS_API_KEY']}", "Accept": "text/event-stream", }) with urllib.request.urlopen(req) as resp: for line in resp: line = line.decode().strip() if line.startswith("data: "): status = json.loads(line[6:]) print(status["status"]["phase"]) if status["status"]["phase"] == "running": break ``` ## Exec patterns Machines are stateful Linux VMs. You're root inside your own box, `$HOME` is `/root`, and everything under `~` persists. Files written in one exec are visible in the next. The machine stays running until you sleep or delete it. ```python def exec_cmd(client, machine_id, command): """Run a command and return stdout.""" exc = client.machines.executions.create( machine_id=machine_id, command=command, ) while exc.status not in ("succeeded", "failed"): time.sleep(0.5) exc = client.machines.executions.retrieve( machine_id=machine_id, execution_id=exc.execution_id, ) output = client.machines.executions.output( machine_id=machine_id, execution_id=exc.execution_id, ) return output.stdout machine_id = dm.machine_id # from create output above exec_cmd(client, machine_id, ["apt-get", "install", "-y", "python3-pip"]) exec_cmd(client, machine_id, ["/bin/bash", "-c", "cd ~ && git clone https://github.com/org/repo"]) exec_cmd(client, machine_id, ["/bin/bash", "-c", "cd ~/repo && python -m pytest -v 2>&1"]) exec_cmd(client, machine_id, ["/bin/bash", "-c", "nohup python server.py > /tmp/server.log 2>&1 &"]) exec_cmd(client, machine_id, ["cat", "/root/repo/output.json"]) exec_cmd(client, machine_id, ["/bin/bash", "-c", "echo 'hello' > ~/test.txt"]) exec_cmd(client, machine_id, ["/bin/bash", "-c", "free -h && df -h ~"]) ``` ## Machine lifecycle ```bash dedalus machines list dedalus machines retrieve --machine-id dm-<id> # Sleep (zero compute cost, storage persists) dedalus machines update --machine-id dm-<id> --desired-state sleeping # Wake dedalus machines update --machine-id dm-<id> --desired-state running # Resize (live, no restart) dedalus machines update --machine-id dm-<id> --vcpu 2 --memory-mib 2048 # Delete (grab revision from retrieve output) dedalus machines delete --machine-id dm-<id> --if-match <revision> ``` ## Examples - [openclaw-ddls](https://github.com/annyzhou/openclaw-ddls): Host OpenClaw on a Dedalus Machine!

Command Palette

Command Palette

Command Palette

Command Palette

You've been invited to Dedalus Labs

Get Started in Minutes

Claim Your Free Credits

Install the Dedalus CLI

Set your API key

Create a machine

Run a command

SSH into the machine

Paste this into your coding agent

Featured Projects & Tutorials

Featured Projects

Discer.io

SpatialMD

CourtRoom

Jiri

CADly

Messenger AI

Amelia

Medverse

GreenTrip

Tutorials & Guides

Build a CRM Agent with X API Integration

Finance Research Agent Tutorial

One-Click PDF Generator with MCP

DAuth: Secure Authentication for AI Agents

Join Our Community

Join Dedalus Discord

Star Our Repos

dedalus-cli

dedalus-python

dedalus-typescript

dedalus-go

dedalus-sdk-python

dedalus-sdk-typescript

dedalus-mcp-python

wingman

You've been invited to Dedalus Labs

Get Started in Minutes

Claim Your Free Credits

Install the Dedalus CLI

Set your API key

Create a machine

Run a command

SSH into the machine

Paste this into your coding agent

Featured Projects & Tutorials

Featured Projects

Discer.io

SpatialMD

CourtRoom

Jiri

CADly

Messenger AI

Amelia

Medverse

GreenTrip

Tutorials & Guides

Build a CRM Agent with X API Integration

Finance Research Agent Tutorial

One-Click PDF Generator with MCP

DAuth: Secure Authentication for AI Agents

Join Our Community

Join Dedalus Discord

Star Our Repos

dedalus-cli

dedalus-python

dedalus-typescript

dedalus-go

dedalus-sdk-python

dedalus-sdk-typescript

dedalus-mcp-python

wingman