Lifecycle

Use lifecycle operations to create, sleep, wake, reboot, or delete a machine. For most workloads, you can set autosleep and let Dedalus manage idle sleep and wake transitions. Use the manual lifecycle operations when you want more control over how your machine behaves.

Create

Create provisions a persistent Linux machine with the CPU, memory, storage, and autosleep policy you choose. The response includes a machine_id as soon as Dedalus accepts the request. If your application needs to wait until the machine is running, watch it instead of polling.

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

machine = client.machines.create(
    vcpu=1,
    memory_mib=4096,
    storage_gib=10,
    autosleep="15m",
)

const machine = await client.machines.create({
  vcpu: 1,
  memory_mib: 4096,
  storage_gib: 10,
  autosleep: "15m",
});

machine, _ := client.Machines.New(ctx, dedalus.MachineNewParams{
    CreateParams: dedalus.CreateParams{
        VCPU: dedalus.Float(1), MemoryMiB: dedalus.Int(4096), StorageGiB: dedalus.Int(10),
        Autosleep: dedalus.String("15m"),
    },
})

Machines sleep after five minutes of inactivity by default. Set autosleep to a different duration, or use 0 or never to disable autosleep explicitly.

Sleep

Sleep stops the machine's running processes and compute billing. Persistent storage remains available for the next wake and counts against your plan's storage allowance. Storage beyond the included allowance remains billable while the machine sleeps.

Use manual sleep when you want more explicit control over when the machine should be idle. Otherwise, you can let autosleep handle it.

An explicit sleep request closes SSH and terminal sessions and cancels active executions before sleeping. New access waits for sleep to finish, then wakes the machine. Auto-sleep waits until all activity is idle.

dedalus machines sleep --machine-id <machine_id>

client.machines.sleep(machine_id="<machine_id>")

await client.machines.sleep({ machine_id: "<machine_id>" });

client.Machines.Sleep(ctx, dedalus.MachineSleepParams{
    MachineID: machineID,
})

Wake

Wake starts a sleeping machine. The machine keeps the same ID and files, but processes that stopped during sleep do not resume. Start those processes again after the machine is running.

If autosleep is enabled, you normally do not need to call wake yourself. Operations that need the machine, such as an execution or SSH session, wake it as part of the request. Call wake directly when you need the machine running before you submit work.

dedalus machines wake --machine-id <machine_id>

client.machines.wake(machine_id="<machine_id>")

await client.machines.wake({ machine_id: "<machine_id>" });

client.Machines.Wake(ctx, dedalus.MachineWakeParams{
    MachineID: machineID,
})

Reboot

Use reboot when a build is stuck or a machine stops responding. The machine keeps its ID and saved files, and you start your programs again after it restarts.

Dedalus first saves the machine's files in a checkpoint, a saved version of the filesystem. It then stops the programs, closes SSH and terminal sessions, and starts the machine with fresh memory. Files held in RAM, such as those in /dev/shm, are lost.

To reboot through the HTTP API, set DEDALUS_BASE_URL to your API URL, MACHINE_ID to the machine's ID, and DEDALUS_API_KEY to your API key. Then run:

REBOOT_KEY="reboot-$(uuidgen)"
curl --fail-with-body -X POST \
  "${DEDALUS_BASE_URL}/v1/machines/${MACHINE_ID}/reboot" \
  -H "Authorization: Bearer ${DEDALUS_API_KEY}" \
  -H "Idempotency-Key: ${REBOOT_KEY}"

Idempotency-Key is optional. If omitted, the server returns a generated key in the response header. Supplying it yourself lets you retry even if the first response is lost.

202 Accepted means the reboot request was accepted. Watch the machine until its phase returns to running, then open a new SSH session or execution. Allow extra time for SSH if the machine's startup services are still loading.

Reboot works after a machine has started and while its desired_state is running. Requesting reboot with any other desired state returns 409 Conflict. Use wake for a sleeping machine. Another lifecycle operation in progress can also cause a 409 Conflict.

Force a reboot

A normal reboot needs the machine to save its files first. If that step is stuck, use force=true to stop the machine and restart from its last completed checkpoint. This also works when a normal reboot is already in progress.

Use a new request key when switching to force:

REBOOT_KEY="reboot-$(uuidgen)"
curl --fail-with-body -X POST \
  "${DEDALUS_BASE_URL}/v1/machines/${MACHINE_ID}/reboot?force=true" \
  -H "Authorization: Bearer ${DEDALUS_API_KEY}" \
  -H "Idempotency-Key: ${REBOOT_KEY}"

If the machine still cannot recover, contact support with its machine ID, request ID, last reported status, and reboot key.

Recover from memory pressure

Suppose a build uses all the machine's RAM. Linux may stop a program to free memory. This is an out-of-memory (OOM) kill, and the stopped program loses work it had only kept in RAM.

Linux skips the services that let you connect with SSH and run commands when choosing a program to stop. Keeping those services alive gives you a way back in to find the problem. Your programs, including SSH commands, executions, and terminal commands, can still be stopped to free memory.

Only the RAM these services actually use comes out of your allocation. OOM protection reserves no extra RAM. Connections can be slow while Linux frees memory, and a Linux crash or changes that stop these services can still leave the machine unreachable.

Find the cause

Open a new SSH session or execution. Run the following commands inside the machine.

Check how much RAM is available:

free -h

List the programs using the most RAM. PID is the process ID used to identify a running program. RSS is the amount of RAM it uses, shown in KiB:

ps -eo pid,comm,rss --sort=-rss | head

Check whether Linux stopped a program because it ran out of memory:

journalctl -k -b --no-pager | grep -E 'Out of memory|Killed process'

Look for an Out of memory message with the name and PID of the stopped program. Copy useful logs off the machine before restarting it, since some logs are kept in RAM.

Reduce memory use

Stop the program causing the problem. If it restarts automatically, pause that restart behavior too. Then run fewer jobs at once or adjust the program to use less memory. A program that keeps allocating too much RAM can cause repeated OOM kills.

If the machine stays unresponsive, follow the reboot instructions. After it restarts, reduce the program's memory use before running it again.

Delete

Delete the machine. Active SSH sessions close before runtime teardown. A destroyed machine cannot be used and its filesystem is discarded.

dedalus machines delete --machine-id <machine_id>

client.machines.delete(machine_id="<machine_id>")

await client.machines.delete({ machine_id: "<machine_id>" });

client.Machines.Delete(ctx, dedalus.MachineDeleteParams{
    MachineID: machineID,
})

Autosleep

Machines sleep after five minutes of inactivity by default. Set autosleep to a different idle duration when you want Dedalus to stop compute sooner or later. For most intermittent workloads, this means you do not need to call sleep or wake yourself. Use the manual lifecycle operations only when your application needs to control the transition at a specific time.

Activity includes executions, terminal and SSH traffic, port traffic, and CPU work from processes inside the machine. The idle window accepts durations such as 30s, 15m, 2h, or 1w3d, raw seconds such as 1800, or never to disable autosleep.

dedalus machines update --machine-id <machine_id> --autosleep 15m

client.machines.update(machine_id="<machine_id>", autosleep="15m")

await client.machines.update({ machine_id: "<machine_id>", autosleep: "15m" });

client.Machines.Update(ctx, dedalus.MachineUpdateParams{
    MachineID: machineID,
    UpdateParams: dedalus.UpdateParams{
        Autosleep: dedalus.String("15m"),
    },
})

Persistent File System

Your machine's root filesystem is persistent across sleep and wake cycles.

What persists

• Files on the root filesystem, including /etc, /home, /root, /usr/local, and /var.
• Installed packages, source code, build caches, and configuration stored in those paths.

What resets on wake

• Memory and CPU execution state start fresh.
• Processes that were running before sleep remain stopped. Restart the processes you still need.
• Network addresses and open connections, including SSH sessions and port forwards.
• Runtime filesystems such as /proc, /sys, /dev, /run, and /dev/shm.
• Files in /tmp. Store temporary files that must survive sleep in /var/tmp instead.