WheelmachineDocs
PagesQuickstart

Quickstart

From a key to a machine you have used and put away, in about five minutes. You need a terminal and an API key.

Get a key#

For now, keys are made in Wheelmachine's console by your account's owner: ask for one that holds cloud:* to follow this page. A key looks like ak_live_ and 40 letters and digits. Keep it like a password: anyone who has it can use your machines.

Coming A page where you make your own keys.

Get wm#

wm is the command line. For now it is built from its source, with Go 1.27 or later, which writes wm and wm-mcp (the server for agents):

Terminal
$ cd frontend/cli
$ go build -o bin/ ./cmd/...
$ export PATH="$PWD/bin:$PATH"

Log in#

Terminal
$ wm login
To sign in, open https://app.wheelmachine.ai/device and enter this code:

    BCDF-GHJK

Your browser is opening it. Sign in, type the code, then approve.
Waiting for you to approve (the code works until 09:10; Ctrl-C to stop)...
Logged in to account you@example.com.
Signed in. A key of your own, "wm on laptop" (key_3f9a1c2b4d5e6f70), is kept in /home/you/.config/wheelmachine/config.json, readable by you only.

You sign in on the page with GitHub or Google, and wm checks the key it is given with the API before it keeps it. On a computer with no browser, open the address on any other device; to keep a key you already have, use wm login --key. To use a key without keeping it, put it in WHEELMACHINE_API_KEY instead.

Make a machine#

Terminal
$ wm machines create --name box
ID                            NAME  STATE    SIZE         LOCATION      AGE
m_01jb2xk3n4p5q6r7s8t9v0w1x2  box   running  2 CPU, 4 GB  Helsinki, FI  0s

It answers once the machine runs, usually in well under a second. This one has 2 CPUs and 4 GB of memory; --cpus 4, 8 or 16 give it more. From here on, the machine is named by its id or by its name.

Run a command#

Terminal
$ wm exec box -- uname -s
Linux
$ wm sh box 'echo hello > note.txt && ls -la | wc -l'
4

wm exec runs a program with its words, without a shell; wm sh runs a line of shell, with pipes and redirections. Both print what the command wrote, and exit with its exit code. Commands start in the machine's work folder.

Copy a file in and out#

Terminal
$ wm cp ./data.csv box:work/
$ wm exec box -- wc -l data.csv
1201 data.csv
$ wm cp box:work/note.txt .

In a machine, a path begins work/ (the work folder, where commands start) or home/ (its home). A path that ends in / is a folder, and the file keeps its name in it.

Pause it#

Terminal
$ wm machines pause box
ID                            NAME  STATE   SIZE         LOCATION      AGE
m_01jb2xk3n4p5q6r7s8t9v0w1x2  box   paused  2 CPU, 4 GB  Helsinki, FI  3m

Paused, it keeps its memory and no running time is charged. A command wakes it, and so does wm machines start box; it carries on where it was. A machine also pauses by itself once it has been idle for five minutes: see Sleep when idle.

Delete it#

Terminal
$ wm machines rm box
Delete m_01jb2xk3n4p5q6r7s8t9v0w1x2 and all its files? [y/N] y
m_01jb2xk3n4p5q6r7s8t9v0w1x2

Deleting takes its files with it, for good. In a script, add --yes.

The same, in code#

The libraries and the API do the same steps. Each reads the key from WHEELMACHINE_API_KEY.

Python

from pathlib import Path
from wheelmachine import Wheelmachine

client = Wheelmachine()  # reads WHEELMACHINE_API_KEY
machine = client.machines.create(name="box")
machine = client.machines.wait(machine.id, "running")  # at once when it already runs

result = client.machines.exec(machine.id, ["uname", "-s"])
print(result.exit_code, result.stdout)

client.machines.write_file(machine.id, "work/data.csv", Path("data.csv"))
client.machines.read_file(machine.id, "work/data.csv", to="data-back.csv")

client.machines.pause(machine.id)
client.machines.delete(machine.id)

Next#