Apps in your machine

Copy page

Copy pageView as MarkdownOpen in ClaudeOpen in ChatGPT

Every new machine carries a desktop, a code editor, agents and a model server. All are on from the start except two: the desktop turns on when you open its screen or ask for a picture of it, and Gemini CLI when you turn it on. The code editor is always on.

$ wm apps ls box
NAME      APP          KIND      STATE  WHERE
desktop   Desktop      web       on     https://6901-01jb2xk3n4p5q6r7s8t9v0w1x2.run.wheelmachine.ai
editor    Code editor  web       on     https://13337-01jb2xk3n4p5q6r7s8t9v0w1x2.run.wheelmachine.ai
ollama    Ollama       service   on     inside the machine
codex     Codex        agent     on     a session of its own in the machine
$ wm apps open box editor
https://13337-01jb2xk3n4p5q6r7s8t9v0w1x2.run.wheelmachine.ai/.wheelmachine/link/...

for app in client.apps.list(machine.id):
    print(app.name, app.kind, app.on)
editor = client.apps.link(machine.id, "editor")
print(editor.link)  # opens once, within five minutes

for (const app of await client.apps.list(machine.id)) console.log(app.name, app.kind, app.on);
const editor = await client.apps.link(machine.id, "editor");
console.log(editor.link); // opens once, within five minutes

curl https://api.wheelmachine.ai/v1/machines/m_01jb2xk3n4p5q6r7s8t9v0w1x2/apps \
  -H "Authorization: Bearer $WHEELMACHINE_API_KEY"
curl -X POST https://api.wheelmachine.ai/v1/machines/m_01jb2xk3n4p5q6r7s8t9v0w1x2/apps/editor/link \
  -H "Authorization: Bearer $WHEELMACHINE_API_KEY"

The apps#

An app is one of three kinds. A web app opens in a browser. A service is reached from inside the machine alone. An agent keeps a session of its own in the machine's terminal, which is there, as you left it, when you come back to it.

wm apps ls lists what a machine carries, and how each stands now. A machine too old to have apps says so (no_apps): make a new one.

On by default, off when you like#

Turn off what you do not use: it frees the machine's memory, and the app stays off when the machine starts again. wm apps off box ollama turns one off, and wm apps on box ollama turns it on again. Starting can take up to a minute. A web app's address closes when it is turned off, and an agent's session ends. Asking about a paused machine's apps wakes it.

The code editor is always on: turning it off is refused (409).

The dashboard has the same switches, on the machine's page under Apps. Open shows the code editor or an agent in a panel, and OpenClaw on the machine's own screen. Closing an agent's panel leaves it working.

Show an app on the machine's screen#

wm apps show box openclaw opens an app on the machine's own desktop, signed in: no address, link or token. Whoever watches the screen sees it. It needs cloud:machines:exec and can take up to two minutes. A service, such as Ollama, has no window to show.

Your machine's screen#

The machine's page in the dashboard has a Screen tab: the machine's own desktop, inside the dashboard, with its keyboard, mouse and clipboard. It is private to you: it opens with your sign-in alone, on the dashboard's own address, never at a web address of the machine's. Full screen fills your screen, and Esc leaves it; on a phone or a tablet, the keyboard button brings up the keyboard. The machine wakes for it, and its desktop is turned on when it is off. A machine made before apps came has no desktop to show.

A program opens the same screen with a key that holds cloud:machines:exec: a WebSocket at /v1/machines/{machine_id}/screen that carries what VNC viewers speak (see the reference).

See and work its desktop from a program#

A program or an agent needs no viewer: it can see the desktop as a picture, and click, drag, scroll, press keys and type on it. Machines have Linux desktops.

$ wm machines create --name box --desktop
$ wm machines screenshot box screen.png
screen.png: 1440 x 900 at scale 0.5
$ wm machines click box 720 450
$ wm machines type box "hello"
$ wm machines keys box ctrl+s

The desktop is off until something asks for it, and its first start can take up to a minute. --desktop (or desktop in the API) turns it on behind the answer when you make the machine, so that the first picture finds it ready. A paused machine is woken for a picture or a click, and runs and is charged as for a command.

• Scale. The desktop is 2880 x 1800 pixels, and has that one size. A picture is drawn down by scale: 1, or one over a whole number up to 8. The default, 0.5, is exactly 1440 x 900. A model that draws a picture down further reads places wrongly, so ask for a scale that fits what your model takes.
• Places. x and y are pixels of a picture of the whole screen at the same scale, so a place read off a picture is the place to click: at scale 1 that very pixel, at 0.5 within one pixel of it.
• Typing. Letters of every language and emoji can be typed, one key after another. Characters that aren't on an English keyboard, such as accents, Russian, Chinese or emoji, go about 60 a second and can come out wrong. Take a picture after typing them to check; a password box can't be checked this way.
• Who. It needs cloud:machines:exec. In an organisation, only the person who holds a machine works it. Someone who watches it gets pictures of the screen they watch, with nothing woken or turned on, and never its pointer or keys.
• Limits. A call has 30 seconds with the desktop, once it is up, and at most 64 actions. A key and a person's own account have at most 4 calls on screens going at once, an organisation 16 and a person 8 across all of theirs: over that, or when many pictures are being taken at once, a call is answered 429 with retry_after_s, and nothing was done. Once any of its actions has begun, an answer never asks you to try again. It says how many were done in full, and the one after them may have been begun, so look at the screen before you send them again. Nothing of ours sends them again by itself.

A screenshot shows whatever is on the screen, and it goes wherever your program sends it: an agent passes it on to whichever model provider it uses. Close what it should not see first. We never log or keep a picture, or what is typed: the audit says that a picture was taken and how many actions of each kind were done, and nothing of what they held or showed.

See the picture and the actions in the reference, the MCP tools, and the libraries.

A private address only you can reach#

A web app is reached at the machine's web address for its port, such as https://13337-01jb2xk3n4p5q6r7s8t9v0w1x2.run.wheelmachine.ai for the code editor. Turning the app on, or asking for a link into it, opens that address private, if it is not open already. A private address answers only a call that carries an API key that can see the machine, and a browser that opened a link made for it. Anyone else is answered 401.

Turning a web app on answers such a link, and wm apps open makes a fresh one whenever you want it. A link opens once, within five minutes, takes that browser to the app's own page, and lets it in for half an hour (--for says otherwise, up to an hour). Each is shown once: send it to no one else. A private address's pages show in the dashboard's own panel, and in no other site's frame.

$ wm apps open box editor --browser

Turning a web app off closes its address again, when turning it on opened it and it is still private. An address you opened yourself, or made public, stays as you left it (see Ports). While a machine's internet is closed, a public address answers only as a private one does, and everyone again once it is opened.

Agents use your own keys#

Agents use your own AI keys: see Your own AI keys.

$ wm secrets set OPENAI_API_KEY
$ wm exec box -- codex exec "make the tests pass"

An AI key reaches everything run in the machine: commands, terminals, SSH sessions and the agents' own pages. Any other secret is given to machines by name and reaches commands, terminals and SSH sessions, never an app the machine starts: put such a key in the app's own settings.

An agent's session keeps the keys it began with. When you add, change or remove a key while one runs, the dashboard says so beside it, with Restart: that turns it off and on again, and its new session has your keys. wm apps off and then wm apps on do the same.

An agent's tile also has its Model: the one it starts on, chosen from your keys' own lists (see Choosing models). A session keeps the model it began with too; one begun before you chose another says Restart to use it. In the API, an agent says the providers it can use (suppliers), what it last started on (model, model_by) and whether it runs on another model than the one chosen now (model_changed).

A model inside the machine#

Ollama runs open models in the machine itself, on its own CPUs and memory. Turn it on, pull a model, and point an agent at http://127.0.0.1:11434: it has no web address, so only programs in the machine reach it.

$ wm apps on box ollama
$ wm exec box -- ollama pull <model>
$ wm exec box -- ollama run <model> "Say hello"

Agents that speak to an OpenAI-style endpoint take http://127.0.0.1:11434/v1 as its address. Choose a model the machine's memory can hold: a machine without a GPU has 2 GB of memory for each of its CPUs.