How workstations work¶
A workstation is a machine of your own in the cloud that you reach from a browser tab, your laptop's terminal or editor, or a coding agent, and that keeps working after your laptop shuts. This page explains what it is, how it is addressed, where it lives and is paid for, what ends the work running on it and what does not, and why the things that surprise people happen. For the steps, see Use workstations.
A real machine, in a tab¶
The terminal in your browser is a shell on a virtual machine. It comes with the alis CLI, Go, Node, Terraform, gcloud, Neovim and the coding agents, holds several terminals at once, and a terminal outlives the browser tab it was opened in: close the tab and the terminal, with whatever runs in it, is still there next time.
The machine has one disk, which is its whole filesystem: your home directory and everything Docker holds. It starts at 100 GB and looks after itself. It clears the platform's own earlier images, and when less than 10 GB is free it grows by 50 GB, up to 500 GB. A disk never shrinks.
There are three sizes, all with the same disk:
| Size | CPU and memory | For |
|---|---|---|
| Small | 2 vCPU, 8 GiB | An editor and the toolchains |
| Medium (default) | 4 vCPU, 16 GiB | Everyday work |
| Large | 8 vCPU, 32 GiB | Builds, containers and several agents at once |
An address for everything on it¶
A workstation answers under its build environment's own domain. The terminal has one address, and every port on the machine has another the moment something listens on it:
https://ws-<id>.<org>.alis.dev the terminal
https://<port>-<id>.<org>.alis.dev whatever listens on <port>
Start a dev server and its port appears as a chip in the terminal's top bar within a second, linking to its address. That address is HTTPS and works from any browser, including a phone, so you can hand a running app to whoever needs to see it without deploying anything. It asks for a sign-in: yours, or one of the people you shared that port with from the terminal page's Ports panel or with alis run --share. Inside the workstation, alis workstation url <port> prints the address.
Made in a build environment, billed there¶
A workstation is created inside the build environment's own Google Cloud project, not the platform's, so its compute is paid for by the build environment whose work is done on it. One workstation serves every product in that build environment, and you can have as many as you like there: one per project, one per agent, each with its own name, size and address.
Creating one takes the administrator or builder role in that build environment; being a builder on any one of its products is enough. An administrator sees, stops, restarts and deletes every workstation in the build environment and can make one for somebody else, a colleague or a candidate, and send them its address. It is then theirs to open: only a workstation's owner can open it.
Locked to its build environment¶
The CLI on a workstation knows which build environment it belongs to and works in that one only. Home still lists your other build environments, subdued, and O (or alis workstation open <org>) opens that build environment's own workstations in a new tab.
The lock is a courtesy to the build environment paying for the machine, not a permission. Your access is exactly what it is everywhere else; the lock only keeps work in the build environment that pays for it.
Already signed in¶
You reach a workstation with the same sign-in as the console. Open the browser terminal and sign in once: that hands your sign-in to the CLI on the machine, so there is no alis login to run there. Enrolling your laptop for ssh does not do this, which is why the first visit is always through the browser. Nobody else's sign-in reaches the machine; it answers its owner and the people the owner shares it with.
It sleeps; it does not stop¶
When the machine's traffic goes quiet for its Sleep timer (30 minutes unless you change it), it suspends itself, and no CPU is billed while it sleeps. Its memory is, which is what lets it wake as you left it. The next visit to any of its addresses wakes it with your processes still running and every file where you left it. That is the point of the design: you can leave an agent working and come back to it, and the machine costs little while nobody uses it.
Four things do end what is running, and each is something a person asks for:
- Update machine: when a newer image is out, updating restarts the machine onto it. Opening a workstation never updates it on the way past; you choose when.
- Stop machine and Restart machine.
- Change machine size: the machine type can only change while the machine is stopped, so resizing stops it and leaves it down at the new size until the next start or visit.
In all four the disk stays and the processes do not. Only deleting the workstation takes the disk with it; ask for one again and you get a fresh machine at a new address.
A second way in: ssh¶
alis workstation enrol <id>, run on your laptop, sets the laptop up once: it reuses or makes an Alis ssh key, registers it on the machine, saves an ssh alias (alis-<org>-<id>) with the machine's host key and, with --claude, adds the connection to Claude Desktop. It waits up to ten minutes for ssh to accept the laptop, because a machine reported as RUNNING has started but its ssh may not have yet.
The saved alias wakes a stopped machine when you connect. With no keys registered, nothing on the machine is open to the internet for ssh at all; remove your last key and that door closes again.
Work on a clock, or work you can watch¶
There are two ways to start work on a workstation without typing it yourself, and they are for different situations.
A scheduled command is an ordinary shell line on a cron schedule, in a time zone you choose. The schedule lives in the build environment's project, not on the machine, so it can wake a sleeping machine before handing the command over. The command runs unattended from your home directory in a login shell and writes one log per run under ~/scheduled_commands/<command_id>. You can pause it, run it now, and see when it last fired and when it fires next.
Run command is for work started by a page, an agent or the CLI while a person waits. It wakes the machine, types the command into a real terminal and returns that terminal's address, so you can open it to watch the output, answer a prompt or interrupt it. The terminal stays after the tab closes.
Sharing a terminal or the whole machine¶
The workstation page's Share control gives a named teammate browser access to the terminals you pick, or to every terminal. They sign in as themselves; they cannot create terminals, manage ssh or change the machine. A terminal can still reach the machine's whole filesystem, so share only with somebody you would hand your keyboard to. Removing the share closes their open connections.
Visible in monitoring and billing¶
Each workstation links to its machine's metrics in Google Cloud (Monitor usage). Its machine, disk and address carry labels naming the workstation and its owner, so the build environment's billing export can group workstation spend instead of showing anonymous machines.
When it surprises you¶
The process I left running has ended. An Update, Stop, Restart or resize ended it; the disk is untouched, so resume from the files. A machine that only went to sleep keeps its processes. Push your branches before any of the four.
Resizing ended my terminals. That is the resize boundary: the machine type changes only while it is stopped. Open the workstation to start it at its new size.
The terminal takes ten seconds or more to appear. The machine went to sleep and is waking. Your terminals and processes come back with it.
A port's address shows nothing, or no chip appeared. Nothing is listening on that port yet, or the server has not finished starting. The terminal and ssh are the machine's own doors and never show as ports. If the address asks the person you sent it to for a sign-in they cannot pass, share the port with them.
ssh is refused. A hand-written ssh command or ~/.ssh/config block does not go through the enrolled alias, so it does not wake a sleeping machine. Start it with alis workstation start <id> --wait, or open its address in a browser, or run alis workstation enrol <id> again and connect through the alias.
I cannot create a workstation in this build environment. A workstation is compute in the build environment's project, so it takes the administrator or builder role there; a viewer cannot create one. A build environment that has never been deployed has no workstation address yet. An administrator can deploy it, give you access, or create the workstation for you.
A command says the workstation is locked to another build environment. It is: open that build environment's own workstations with O on Home or alis workstation open <org>.
A scheduled command left no terminal. Scheduled work is unattended. Delivery only means the machine accepted the command; read the newest log under ~/scheduled_commands/<command_id> for what happened. Use run command when you want to watch.
A long, quiet scheduled command paused. Output counts as activity; a silent process does not, so the machine went to sleep around it. The process is preserved and continues when the machine wakes. Have long work print progress, or lengthen the sleep timer.
Opening the console from the TUI did nothing. The machine has no browser of its own: it asks your terminal page to open the tab, and a popup blocker may refuse. The page then shows an open link in its bar.