alis workstation¶
Workstations: your own machines inside a build environment's Google Cloud project, shared across its products, with a browser terminal, SSH from your laptop, and an address for every port.
Synopsis¶
alis workstation agent answer <agent> <key>... [flags]
alis workstation agent list [<workstation>] [flags]
alis workstation agent prompt <agent> [flags]
alis workstation agent read <agent> [flags]
alis workstation agent start [<workstation>] [flags]
alis workstation connect [<workstation>] [flags]
alis workstation create [<org>] [flags]
alis workstation enrol <workstation> [flags]
alis workstation explain [flags]
alis workstation get [<workstation>] [flags]
alis workstation handoff [flags]
alis workstation handoff cancel <handoff-id> [flags]
alis workstation handoff install [flags]
alis workstation handoff open <handoff-id> [flags]
alis workstation handoff reclaim <handoff-id> [flags]
alis workstation handoff status <handoff-id> [flags]
alis workstation handoff targets [flags]
alis workstation list [<org>] [flags]
alis workstation open [<org>] [flags]
alis workstation restart [<workstation>] [flags]
alis workstation start [<workstation>] [flags]
alis workstation status [flags]
alis workstation stop [<workstation>] [flags]
alis workstation url [<port>] [flags]
Aliases: workstation, workstations, shell.
Description¶
A workstation answers under its build environment's domain: https://ws-<id>.<org>.alis.dev is the terminal and https://<port>-<id>.<org>.alis.dev is whatever listens on <port>. Open the browser terminal and sign in once to prepare its CLI. RUNNING means the machine has started; its terminal and SSH may still be starting.
A workstation is named by its id (ten characters, the part after ws- in its address), <org>.<id>, the full organisations/<org>/workstations/<id>, or a unique display name. Inside a workstation the argument may be left out: it means this one. Inside a workstation the CLI is locked to that build environment.
Subcommands¶
alis workstation list¶
List the workstations you own: in every build environment when no argument is given, or in the one named. In a build environment you administer, naming it lists everybody's workstations there, each with its owner. Anywhere else nobody else's machines show.
No flags beyond the global flags. --json wraps workstations.
alis workstation get¶
Show one of your workstations, with its state read from the machine: state, size, addresses, ssh, currentImage, and disk (GB used and free as the machine last reported, and the size it may grow to). On a running machine statusMessage carries the machine's own warnings: an image still being pulled, or a disk that is full and could not be grown.
No flags beyond the global flags.
alis workstation create¶
Create a new workstation. The build environment defaults to the one of the current directory. The machine is MEDIUM (4 vCPU, 16 GB) and suspends itself after 30 idle minutes unless told otherwise. Every call makes a new machine. The workstation is returned CREATING; --wait blocks until the VM is RUNNING.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--idle-timeout <minutes> |
int32 | 30 |
Minutes of no traffic before the machine suspends itself. |
--name <label> |
string | the id | What to call the workstation. |
--open |
bool | false | Open the workstation's terminal in a browser afterwards. |
--size <size> |
string | medium |
small (2 vCPU/8 GB), medium (4/16) or large (8/32). |
--ssh-key <key> |
stringArray | Public key that may ssh in: a key line or the path of a .pub file (repeatable). Authorises the key; does not register this laptop. |
|
--wait |
bool | false | Block until the VM is running. |
alis workstation start¶
Start a workstation's VM. A suspended machine resumes with everything that was running; a stopped one boots. Starting one already running is not an error.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--open |
bool | false | Open the workstation's terminal in a browser afterwards. |
--wait |
bool | false | Block until the VM is running. |
alis workstation stop¶
Stop a workstation's VM now, rather than at its idle timeout. Processes and terminal sessions end; the disk stays.
No flags beyond the global flags.
alis workstation restart¶
Restart a workstation onto the current platform image. Everything running on the machine ends, detached terminal sessions included; the disk is untouched. Without --wait the machine is left stopped (STOPPING is returned) and boots on the next visit or start; with --wait it returns RUNNING. Do not follow restart --wait with start.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--open |
bool | false | With --wait, open the terminal in a browser afterwards. |
--wait |
bool | false | Wait for the machine to stop, boot it on the new image and block until it is running. |
alis workstation enrol¶
Register this laptop with one of your workstations: reuse or create its Alis SSH key, save the SSH alias, and add it to Claude Desktop with --claude. Starts the workstation if needed and waits up to ten minutes for SSH to accept this laptop. Run it locally on macOS, Linux or Windows (natively, not inside WSL), not inside the workstation. Retrying is safe.
Aliases: enrol, enroll.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--claude |
bool | false | Also register the connection in Claude Desktop on this laptop. |
--json reports url, alias, sshCommand, keyRegistered, sshConfigured, claudeRegistered, sshReady and nextSteps. The saved alias wakes a stopped machine when you connect to it.
alis workstation connect¶
Bring a workstation into the herdr window on this laptop: enrol if needed (or repair an older alias), save the workstation as a herdr machine, then attach with herdr --remote <alias>. Without an argument the workstation is the one in the current directory's build environment.
Aliases: connect, attach.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--claude |
bool | false | Also register the connection in Claude Desktop on this laptop. |
--no-attach |
bool | false | Save the connection and the herdr machine without attaching (--json implies it). |
--session <name> |
string | Attach to a named herdr session on the workstation instead of its default. |
Errors: workstation_ambiguous, herdr_missing, herdr_outdated.
alis workstation open¶
Open the console's workstations page for a build environment: your machines there, or the dialog that creates one.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--print |
bool | false | Print the URL instead of opening a browser. |
alis workstation url¶
Print the address a browser reaches this workstation at, or, given a port, the address of whatever listens on that port. Only inside a workstation.
No flags beyond the global flags.
alis workstation status¶
Say whether this CLI runs inside a workstation, and which.
No flags beyond the global flags.
alis workstation explain¶
Print an explanation of workstations: what a machine of your own on the platform is, how it is addressed, how the browser login becomes the CLI's, and the workstations you have today. Markdown, printed verbatim.
No flags beyond the global flags.
alis workstation handoff¶
Continue a local agent session in herdr on a workstation: the agent pauses at a safe point, its scoped build and Define changes are pushed as handoff/<id> commits (your branch and files stay as they are), the conversation is copied over SSH, and the agent continues in herdr on the workstation, in isolated worktrees. Native continuation supports Claude and OpenCode; Codex and Antigravity need --mode summary --instruction '<note>'. Needs enrolled SSH, Git, matching agent versions, and herdr 0.9.0 or later on the workstation.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--agent <name> |
string | claude |
Source agent: claude, opencode, codex, antigravity. |
--instruction <text> |
string | Continue where you left off. |
Continuation instruction. |
--mode <mode> |
string | native |
Native resume, or an explicitly chosen summary continuation. |
--no-progress |
bool | false | Do not open an independent progress window. |
--session <id> |
string | Source agent session id. | |
--to <alias> |
string | Enrolled SSH alias (alis-<organisation>-<workstation>). |
alis workstation handoff targets¶
List enrolled workstation SSH aliases.
alis workstation handoff status¶
Show a handoff's status.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--watch |
bool | false | Wait for remote acceptance or a recoverable error; --json streams handoff.progress lines. |
alis workstation handoff open¶
Attach to the handed-off agent on the workstation.
alis workstation handoff reclaim¶
Stop the workstation agent once it is idle, commit and push its scoped worktree changes on handoff/<id>, bring the conversation home and resume it under ~/.alis/handoffs/<id>/reclaim/alis.build/<path>. Refuses while the agent is mid-turn or waiting at a prompt. reclaim.json in the job directory records the phase; re-running continues from it.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--instruction <text> |
string | The resume prompt; summary mode's continuation note. | |
--mode <mode> |
string | native |
native or summary. |
--wait |
bool | false | Keep asking while the workstation agent is busy, for up to 30 minutes. |
alis workstation handoff cancel¶
Cancel a handoff. Cancellation confirms the destination stopped before releasing the source claim.
alis workstation handoff install¶
Link the Alis herdr plugin, which carries the handoff popups (the same link as alis herdr install).
alis workstation agent¶
Start a coding agent on one of your workstations, in a product's repository, and work with it from where you are. The agent runs in a terminal on the workstation that you can open, watch and take over: the url every command prints. It is the Antigravity CLI unless you ask for another.
An agent is named by what start prints as agent: organisations/<org>/workstations/<id>/agents/<agent>. The workstation and the agent's id as two arguments work too.
alis workstation agent start¶
Wake the workstation, sign its CLI in as you when it is not, clone the product when it is not there, start the agent in the product's repository and hand it a first prompt. One command for all of it. Without <workstation> it is your one workstation in the product's build environment; with none there, or several, the command says so and stops. It never creates a workstation. Run again for the same product, it returns the agent that is already there.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--agent <name> |
string | agy |
The coding agent: agy (the Antigravity CLI), claude or codex. You sign in to Claude Code and Codex yourself the first time. |
--name <id> |
string | The agent's id on the workstation. Made from the agent and the product when left out. | |
--no-wait |
bool | false | Return as soon as the workstation has taken the request on. |
--product <org>.<product> |
string | the current directory's | The product the agent works in. |
--prompt <text> |
string | What to hand the agent once it is up. | |
--prompt-file <path> |
string | Read the prompt from a file; - reads standard input. |
|
--timeout <duration> |
duration | 10m |
How long to wait for the workstation and the agent. |
alis workstation agent prompt¶
Hand an agent a prompt, as if you had typed it in its terminal and pressed Enter. A workstation that is asleep is woken for it. An agent that is waiting for an answer takes no prompt.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--prompt <text> |
string | The prompt. | |
--prompt-file <path> |
string | Read the prompt from a file; - reads standard input. |
|
--timeout <duration> |
duration | 10m |
How long --wait waits. |
--wait |
bool | false | Wait until the agent has finished with it, or asks something. |
alis workstation agent read¶
Show an agent's state and the last lines of its terminal as text. Reading never wakes a workstation: an agent on a machine that is asleep is reported ASLEEP.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--lines <n> |
int | 120 |
How many lines of the terminal to print, at most 500. |
--timeout <duration> |
duration | 10m |
How long --wait waits. |
--wait |
bool | false | Wait until the agent has stopped working. |
alis workstation agent answer¶
Answer an agent that has stopped to ask something, such as whether it may run a command, with the keys you would press in its terminal: enter, esc, up, down, tab, y, n, or a digit 1 to 9. Keys are pressed only for an agent that is asking. The agent is named in full here.
alis workstation agent list¶
List the agents started on a workstation with alis workstation agent start that are still there. Agents you started by hand in a terminal are not listed. A workstation that is asleep is not woken: the result says asleep.
Examples¶
alis workstation list --json
alis workstation create acme --wait --open --json
alis workstation start <id> --wait --json
alis workstation get <id> --json
alis workstation enrol acme.<id> --claude --json
alis workstation connect
alis workstation restart <id> --wait --json
alis workstation handoff targets --json
alis workstation handoff --session <id> --to alis-acme-<id> --json
alis workstation handoff status <handoff-id> --watch --json
alis workstation handoff reclaim <handoff-id> --wait --json
alis workstation agent start --product acme.shop --prompt "Add a health check to the orders service." --json
alis workstation agent read <agent> --wait --json
alis workstation agent prompt <agent> --prompt "Now add a test for it." --wait --json
alis workstation agent answer <agent> enter --json
JSON output¶
Lifecycle commands return the workstation; list wraps workstations. A running workstation that has reported carries disk (usedGb, freeGb, limitGb, observeTime) and diskSizeGb as the disk is now. Progress goes to stderr as NDJSON. Errors: workstation_failed carries the reason; waiting times out after ten minutes as workstation_wait_timeout; workstation_not_found covers missing or other people's machines; backend_outdated means the backend needs updating.
The agent commands return the agent: workstation, agent, kind, product, directory, state, message, url, and next, the commands that come next. read, prompt and answer add output, the terminal as text. state is one of PREPARING, IDLE, WORKING, BLOCKED (it asked something), FAILED, GONE or ASLEEP. Errors: missing_workstation and workstation_ambiguous when there is no workstation to use, or several; agent_failed carries the workstation's reason; agent_blocked carries what the agent asks; workstation_outdated means the workstation needs a restart to move onto the current image; agent_wait_timeout exits with code 5 when the agent is still working, which is not a failure.
Notes¶
Lifecycle --wait waits for RUNNING, not for SSH.
An agent started with alis workstation agent start works on the workstation as you. It asks before it runs a command, and it keeps its workstation awake while it works, for up to four hours after it was last given something to do.