Use workstations¶
Create a machine of your own inside a build environment, open its terminal in the browser, connect from your laptop over ssh or herdr, and hand a running agent session to it.
A workstation is a VM in the build environment's Google Cloud project, shared across all products there, with the toolchains, the CLI and an editor installed. It suspends itself when idle and wakes on the next visit with its processes still running. Every port on it has an address of its own.
Prerequisites¶
- Builder access to the build environment.
- For laptop access, ssh on your machine; for herdr, herdr 0.9.0 or later.
Create a workstation¶
The machine is medium (4 vCPU, 16 GB) and suspends after 30 idle minutes unless you pass --size small|medium|large or --idle-timeout <minutes>. --name labels it; --ssh-key <line-or-.pub> authorises a public key. --wait blocks until the VM is RUNNING (the terminal and ssh may still be starting) and --open opens the browser terminal. Without an argument the build environment of the current directory is used. Every call makes a new machine.
- Open Workstations in the console.
- Choose New workstation, then the build environment if you have more than one. Name it and pick a size.
- Choose Open in browser on its card, or Connect to reach it from your own tools.
What each size costs, and what is billed while it sleeps, is in Workstation costs.
Open the browser terminal and sign in once: that sign-in prepares the CLI on the machine. Enrolment alone does not.
Find and control your machines¶
alis workstation list
alis workstation get <id> --json
alis workstation start <id> --wait
alis workstation stop <id>
alis workstation restart <id> --wait
get reports the state, size, addresses and ssh details, currentImage and disk; when currentImage is false, restart moves the machine onto the image the platform publishes now. stop ends processes and terminal sessions but keeps the disk; start resumes a suspended machine with everything running or boots a stopped one. The workstation's ⋯ menu in the console offers the same (Update, Restart, Stop), plus Change size, Sleep timer, Scheduled commands, Open port…, Details, Monitor usage and Delete. Deleting removes the disk.
The disk¶
Every workstation has one disk, shared by your home directory and everything Docker holds on the machine: the images you build or pull, their containers and the build cache. It starts at 100 GB and the machine looks after it: it removes the platform's own earlier images, and when less than 10 GB is free it grows the disk, 50 GB at a time, up to 500 GB. The growth is billed to the Build Environment like the rest of the machine, and a disk never shrinks.
alis workstation get <id> --json shows disk - GB used and free, the limit, and when the machine last looked. Only when the machine cannot make room, because the disk is at its limit, does statusMessage say so. To make room by hand from the terminal: docker system df shows what Docker holds, docker image prune -a removes images nothing runs and docker builder prune -a the build cache (both come back on the next pull or build), and du -xsh ~/* | sort -h finds what is large in your home.
Connect from your laptop¶
Enrolment reuses or creates this laptop's Alis ssh key, registers it on the machine, saves an ssh alias alis-<org>-<id> and waits up to ten minutes for ssh to accept it. Add --claude to register the connection in Claude Desktop as well. The saved alias wakes a stopped machine when you connect, so ssh alis-acme-<id> works from stopped. Run it locally, not inside the workstation or WSL.
To work on it from your local herdr window:
This enrols if needed, saves the workstation as a herdr machine and attaches. --no-attach saves without attaching; --session <name> attaches to a named herdr session.
Work on the workstation¶
Inside a workstation the CLI is locked to that build environment. alis workstation status names the machine; alis workstation open <org> opens another build environment's workstations in a new tab. Clone your product there with alis clone <org>.<product>, then run alis packages install <pkg> before building or running.
A dev server on the machine is reachable from any browser at the address alis workstation url <port> prints; without a port it prints the terminal's address. Ports are addressed as https://<port>-<id>-ws.<org>.alis.dev, and every address asks for a sign-in: yours, or one of the people the port is shared with (alis run --share, or the terminal page's Ports panel). Each port sends the notes left on its pages to one agent session; see Annotate your app and let agents test it.
Hand an agent session to a workstation¶
From herdr, press CtrlB then T on a Claude or OpenCode pane to hand it off, or run:
alis workstation handoff targets --json
alis workstation handoff --session <id> --to alis-acme-<workstation-id>
alis workstation handoff status <handoff-id> --watch
The conversation and paired build and Define checkpoints move into isolated worktrees on the workstation and continue in its herdr. Keep the laptop open until the status reports it is safe to close. alis workstation handoff open <handoff-id> attaches to it; reclaim brings the continuation back to the laptop; cancel stops it. Codex and Antigravity need --mode summary --instruction "<note>". alis workstation handoff install links the herdr plugin that carries the CtrlB T and CtrlB U popups.