Skip to content

Continue work on a workstation

Hand a running coding-agent session off from your laptop to an Alis workstation so it carries on after you close the lid, then bring it back.

Prerequisites

  • A workstation of your own in the build environment (alis workstation list --json; create one with alis workstation create <org> --wait --json).
  • This laptop enrolled with it: alis workstation enrol <id> --json, or alis workstation connect <id>, which also saves it as a herdr machine.
  • herdr 0.9.0 or later on the workstation, Git, matching agent versions on both machines, and the agent signed in on the workstation. herdr on the laptop is optional; its prefix+t and prefix+u shortcuts come from the Alis plugin (alis herdr install).
  • A Claude Code or OpenCode session (native continuation). Codex and Antigravity need an explicit summary mode.

Hand off

  1. Check the targets:

    alis workstation handoff targets --json

    The enrolled aliases have the form alis-<organisation>-<workstation>.

  2. Hand off the session. In herdr, press prefix+t on the agent's pane; the pane then shows the workstation session. From the command line:

    alis workstation handoff --session <agent-session-id> --to alis-<org>-<id> --json

    For Codex or Antigravity, add --mode summary --instruction '<note>'; this starts a new session there with continuation context rather than resuming the old one.

    The source pauses at a recoverable boundary. Scoped service and define changes are pushed as handoff/<id> commits; your branch, index and files stay intact. On the destination, isolated worktrees under ~/.alis/handoffs/<id>/alis.build hold the work. Nothing is defined, built or deployed by the handoff itself.

  3. Wait for the destination to acknowledge before closing the laptop:

    alis workstation handoff status <handoff-id> --watch --json

    It streams handoff.progress lines and reports safe_to_close once the agent on the workstation has taken over. waiting_for_input after a trust prompt has been accepted is safe.

  4. Open it later in the browser:

    alis workstation handoff open <handoff-id>

Bring it back

  1. Reclaim. The workstation agent is stopped once idle, its scoped worktree changes are committed and pushed on handoff/<id>, and the conversation resumes on your laptop under ~/.alis/handoffs/<id>/reclaim/alis.build/<path>, in a new tab of the product's herdr space or in this terminal:

    alis workstation handoff reclaim <handoff-id> --wait --json

    --wait keeps asking for up to 30 minutes while the agent is mid-turn. If the agent is waiting at a prompt, attach and answer it instead. In herdr, prefix+u lists this laptop's handoffs; the row number brings one back.

  2. Cancel a handoff you no longer want. The destination is confirmed stopped before the source is released:

    alis workstation handoff cancel <handoff-id> --json

Live processes, credentials, ignored dependencies and global agent configuration are not transferred. Unknown local background work blocks a transfer.

Related: alis workstation, alis herdr.