Introduction

Lifecycle

A Dedalus Machine moves through four states: running, sleeping, starting, and destroyed. Dedalus Machines are persistent, which means that the filesystem and identity survive sleep and wake.

The lifecycle can either be managed by Dedalus, with autosleep and wake, or manually using the lifecycle commands. Either way, you only pay for the compute you use while the machine is running.

This means you don't have to manage your machine's lifecycle to benefit from fast, cheap persistence, but you can if you want to.

Machines sleep after five minutes of inactivity by default. Change the autosleep idle window when your workload needs a shorter or longer interval. Use the watch API when your application needs to wait for a state change instead of polling.

Create, sleep, wake, and delete machines ->

List, inspect, update, and watch machines ->

Filesystem

Each machine has a persistent root filesystem. Files under /home, /root, /etc, /usr/local, and /var survive sleep and wake, including installed packages, source code, build caches, and configuration. This lets an agent resume work without reinstalling its tools or reconstructing its workspace.

Only the root filesystem survives sleep and wake. The following are lost on every sleep:

• RAM, running processes, vCPU state
• Guest IP and MAC address (re-derived from a reassigned slot, so not stable)
• Open SSH sessions and port forwards
• Ephemeral mounts (/proc, /sys, /dev, /run, /dev/shm, /tmp)

Learn how sleep and wake affect files ->

Isolation

Every Dedalus Machine is a virtual machine (VM) with its own Linux kernel. The VM boundary separates the workload from the host and from other machines. This matters when agents install dependencies, compile projects, or run code that has not been reviewed.

This also matters when agents receive non-deterministic user input, preventing adversarial requests from affecting other users or the host.

Whatever the workload, the VM boundary provides stronger isolation than a container, which shares the host kernel with other workloads.

Run commands with executions ->

Agent Native Controls

Agents and backend services can control Dedalus Machines through the HTTP API, command-line interface (CLI), or Python, TypeScript, and Go software development kits (SDKs). Each surface exposes the same machine identifier, lifecycle operations, and resources. Dedalus Machines are designed to be controlled programmatically, without needing a dashboard to manage them.

Use executions for independent commands, terminals for an interactive shell streamed over a WebSocket, and SSH for OpenSSH access. Start with the CLI guide, an SDK, or the Machines API.

Delete

Delete a machine when its filesystem and identity are no longer needed. Deletion removes the machine from use immediately, alongside its filesystem. Deleted machines will no longer count against your machine quota, which depends on your plan.

Storage may be retained for up to 30 days. Contact support for recovery.

Delete a machine ->

Common use cases

Throwaway execution

Coding agents, test harnesses, and automation systems often need a clean computer for one task. They create a machine, run unreviewed code, collect the useful output, and discard the machine. Quick cold-start speed keeps the agent loop responsive, while VM isolation allows you to run code and commands that have not been reviewed.

For this workload, create one machine per task, use executions to run commands, download outputs through artifacts, then delete the machine.

Burst compute

Development environments and reinforcement-learning systems may create many copies of the same environment for a burst of work. The machines are disposable, but project files, installed tools, caches, and training checkpoints may need to survive between bursts.

For this workload, keep durable data on the persistent filesystem, use sleep and wake to separate storage from active compute, and let your controller create and monitor machines through the Machines API. Each machine is a full Linux environment, so workloads can install packages, manage users and permissions, run background services, and debug processes through SSH.

Persistent workspaces

Project-based agents and hosted development products attach a machine to work that lasts across sessions. Builds may continue after a user disconnects, and development servers may need to remain reachable while the project is active. The important features are a durable filesystem, an explicit lifecycle, and access methods that work for both people and programs.

For this workload, keep autosleep disabled while continuous work is running, use lifecycle events to track the machine, connect through SSH for debugging, and expose development services with previews.

Agent accessibility

Automation works best when every machine operation is available programmatically. After an API key is configured, an agent can create a machine, inspect its state, run commands, retrieve output, sleep or wake it, and delete it through the same API.

Follow the Quickstart guide to get started with an example workflow, then learn how to control machines through the CLI, SDK, or API.