# Machines

## Instant or Full VM

**Instant** machines are ready in seconds on our tuned Linux (see Benchmarks). A **Full VM** runs a distro's own
cloud image with its own kernel (Ubuntu, Debian, Fedora, Rocky, AlmaLinux, CentOS Stream, Arch,
openSUSE): pick FULL VM when you create a machine. Same sizes, same prices; its first boot
takes about 15 seconds. To boot your own cloud image, pick **Your own image…** and paste its https
URL (qcow2 or raw with cloud-init, not compressed, no bigger than the machine's disk). If a Full VM
doesn't come up, its page has **Boot log…** (its console; `c` copies it), and agents read the same
log with `boot_log` over MCP or `GET /v1/machines/{name}/bootlog`.

To type into a Full VM before it has networking (a broken network config, a firewall that locked
you out), join its **serial console**: `ssh -t console-web-1@shell.639cloud.com` (put your machine's
name after `console-`). Press Enter for a login prompt. To leave, press Enter, then `~.`. One person
at a time; viewers can't. Every Full VM can also run its own VMs (KVM is available inside), and
Docker works on all of them.

**Proxmox VE 9** (Full VM, 4 GiB RAM or more) comes ready to sign in to: the machine's "ready"
screen (and `create_machine`'s or the API's create reply) has its web UI link and a `root` password
made for that machine alone. The password is shown only then: save it (lost it? `ssh` in and run
`sudo passwd root`). The link is private: its URL is a one-time sign-in (use it within 15 minutes;
the browser then stays signed in for 30 days), and the machine's **Links** makes new ones. VM 9000 `debian-13-template` is ready to
clone (set a password or SSH key under Cloud-Init), a Debian 13 container template is in **Create
CT**, and guests on bridge `vmbr1` get DHCP and internet through the machine.

## Sandboxes

For code you don't trust yet, make the machine a **sandbox**: an Instant machine with no public
address and no VPC, deleted when its lifetime ends (an hour unless you change it). Pick SANDBOX
when you create a machine, or see the Sandboxes page.

## Lifetimes

Any machine can have a lifetime: it is deleted, with everything in it, when the lifetime ends. Use
it for work that should clean up after itself (a batch job, a review environment). On its page:
**Lifetime…**; from code: `lifetime_seconds` on create or `PATCH`; agents use `set_lifetime`.
Delete protection wins over a lifetime. A sandbox always has one unless you keep it.

## Sleep and wake

A new machine stays on. Turn on **auto-sleep** (machine page → **Sleep after**, or
`set_auto_sleep` / `"auto_sleep": true` in the API) and it goes to sleep on its own when it's idle:
nobody attached, no command running, and next to no CPU in use. Sleeping keeps its memory and
disk exactly as they were, and you pay only for its disk. The next shell, command, file transfer or
API call wakes it, right where it left off.

Everything inside a sleeping machine is frozen. Traffic arriving at its public address does not
wake it.

## Keep a job running: keepawake

Start long background jobs with `keepawake`, and auto-sleep waits until the job exits:

```sh
nohup keepawake ./build.sh > build.log 2>&1 &
```

Or turn auto-sleep off for the machine instead.

## Sizes

| Size | CPU | RAM | Disk |
|---|---|---|---|
| s1 | 1 core | 1 GiB | 20 GB |
| s2 | 1 core | 2 GiB | 25 GB |
| s4 | 2 cores | 4 GiB | 50 GB |
| s8 | 4 cores | 8 GiB | 100 GB |
| s16 | 8 cores | 16 GiB | 200 GB |
| s32 | 16 cores | 32 GiB | 400 GB |
| s64 | 32 cores | 64 GiB | 800 GB |

Cores are shared between machines: a machine gets its CPU when it needs it. Usable RAM is a
little under the size, because the kernel keeps some for itself.

## Resize live

Machine page → **Resize…**: sliders for RAM, CPU and disk, with the live price. RAM and CPU change
with no reboot up to the machine's ceiling; past it, the app offers a restart (about 10 seconds).
The disk grows live and never shrinks.

From the command line:

```
:resize ubuntu-1 ram 2G cpu 1
:resize! ubuntu-1 ram 8G        # ! allows a restart past the ceiling
```

## Restart and recovery

**Restart** cold-boots the machine from its disk in about 10 seconds. If a machine crashes, the
app shows the error and offers a one-key restart.

## Labels

Tag machines with `key=value` labels (a project, a customer, an environment) to find them and see
what each costs. On a machine's page they show under the cost; `/` in My machines finds them
(`acme`, or `label:project=acme`). From code: `labels` when you create a machine, `PATCH` to change
them, `GET /v1/machines?label=project=acme`, and `GET /v1/usage?…&group_by=label:project` for the
cost per project. Agents use `set_labels`.

## Secrets

Give a machine its Git token or API keys as it's made: `secrets` on create or fork, from the API or
an agent (`create_machine`, `fork_machine`, `fork_template`). Each one is a root-only file in
`/etc/639/secrets/` and an environment variable in shells and commands. We keep no copy; they live
on the machine's disk, so its snapshots and forks have them too.

## Many machines at once

On **My machines**, `space` marks a machine, `a` marks everything shown, and `enter` opens the
actions for the marked set: sleep, wake, restart, auto-sleep on/off, delete. Search picks the set:
`state:running`, `size:s1`, `vpc:NAME`, `image:ubuntu`, and wildcards like `web-*`. The command
line takes the same selectors:

```
:sleep state:running
:delete web-*          # always asks first
```

## Notes

Each machine keeps a running log that everyone in your account sees: who wrote what, and when.
Use it for the things the next person (or agent) needs to know: "migrated the db, don't restart
before 5pm", "port 8080 is the staging API", "ask Ana before upgrading".

- **In the app:** the machine page shows the latest two; **Notes…** lists them all. `n` adds one
  (several lines are fine; `ctrl+s` saves), `e` edits your own, `d` deletes.
- **From a terminal:**

  ```sh
  ssh note@shell.639cloud.com ls web-1
  ssh note@shell.639cloud.com add web-1 "migrated the db, don't restart before 5pm"
  ssh note@shell.639cloud.com add web-1 < handover.txt
  ssh note@shell.639cloud.com edit n_k7f2q9xm3a "fine to restart now"
  ssh note@shell.639cloud.com rm n_k7f2q9xm3a --yes
  ```

- **Agents** read and write them with `list_notes` and `add_note`, and `list_machines` shows how
  many each machine has. An agent's note is labelled with the agent and the person it works for,
  e.g. "Claude Code via MCP · Ana Ruiz".
- **The API and SDKs:** `GET/POST /v1/machines/{name}/notes`; `machine.notes()`,
  `machine.add_note("…")`.

You edit and delete your own notes; your account's owners and admins can delete anyone's, and
viewers can read them but not write. A note
is plain text, up to 4 KB; a machine keeps up to 200. Deleting a machine deletes its notes.

For instructions agents should *follow* rather than just read, use **Rules** (see Rules for agents).

## Inside a machine

You are root. There are no loadable kernel modules (`modprobe` fails; drivers are built in).