--- title: "Use workstations" url: "https://docs.alisx.com/how-to/alis-build/use-workstations/" --- # 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 === "CLI" ```bash title="Terminal" alis workstation create acme --wait --open ``` The machine is medium (4 vCPU, 16 GB) and suspends after 30 idle minutes unless you pass `--size small|medium|large` or `--idle-timeout `. `--name` labels it; `--ssh-key ` 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. === "Console" 1. Open **Workstations** in the console. 2. Choose **New workstation**, then the build environment if you have more than one. Name it and pick a size. 3. 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](https://docs.alisx.com/reference/workstation-costs.md). 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 ```bash title="Terminal" alis workstation list alis workstation get --json alis workstation start --wait alis workstation stop alis workstation restart --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 --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 ```bash title="Terminal" alis workstation enrol ``` Enrolment reuses or creates this laptop's Alis ssh key, registers it on the machine, saves an ssh alias `alis--` 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-` works from stopped. Run it locally, not inside the workstation or WSL. To work on it from your local herdr window: ```bash title="Terminal" alis workstation connect ``` This enrols if needed, saves the workstation as a herdr machine and attaches. `--no-attach` saves without attaching; `--session ` 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 ` opens another build environment's workstations in a new tab. Clone your product there with `alis clone .`, then run `alis packages install ` before building or running. A dev server on the machine is reachable from any browser at the address `alis workstation url ` prints; without a port it prints the terminal's address. Ports are addressed as `https://--ws..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](https://docs.alisx.com/how-to/alis-build/watch-and-help-your-agents-browser.md). ## Hand an agent session to a workstation From herdr, press ++ctrl+b++ then ++t++ on a Claude or OpenCode pane to hand it off, or run: ```bash title="Terminal" alis workstation handoff targets --json alis workstation handoff --session --to alis-acme- alis workstation handoff status --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 ` attaches to it; `reclaim` brings the continuation back to the laptop; `cancel` stops it. Codex and Antigravity need `--mode summary --instruction ""`. `alis workstation handoff install` links the herdr plugin that carries the ++ctrl+b++ ++t++ and ++ctrl+b++ ++u++ popups. ## Related - [How workstations work](https://docs.alisx.com/explanation/workstations.md) - [Authorise and repair credentials](https://docs.alisx.com/how-to/alis-build/authorise-and-repair-credentials.md) - [Agents, skills and the CLI](https://docs.alisx.com/explanation/agents-skills-cli.md)