Remote And Mobile
Remote Hosts
Run workspaces on another macOS, Linux, or Windows machine over SSH, with terminals, files, Git, and agents served by that host.
On This Page
A workspace can live on another machine, such as a build server or a Windows box. Your desktop keeps the projects, workspaces, and settings, and each host runs its own copy of the Alera runtime next to the code. Alera installs and updates that runtime for you over SSH.
Before You Start#
- The host runs an OpenSSH server that this computer reaches with key or agent authentication. Alera runs your system
sshandsftpin batch mode, so nothing answers a password prompt: load passphrase-protected keys into your SSH agent. Password login is not supported. - macOS, Linux, and Windows hosts are supported, on x64 or arm64. macOS and Linux need
tar. Windows needs Windows PowerShell andtar.exe, and its OpenSSH default shell must staycmd.exe, or Alera cannot connect to the runtime there. - Git, your forge CLI (
gh,glab, oraz), and your agent CLIs are installed and signed in on the host.
Add A Host#
Open Settings → Remote Hosts (Mod+Comma opens Settings; Mod is ⌘ on macOS and Ctrl on Windows and Linux) and click Add Host. The dialog walks through three steps: Connection, Install Runtime, and Done.
- Connection. Type the SSH Address the way you would give it to
ssh:user@host, oruser@host:portwhen the port is not 22 (an IPv6 address goes in brackets before a port, as inuser@[::1]:2222). Alias is the display name and follows the host you typed until you change it. Under Authentication, SSH Agent uses your agent and~/.ssh/config; Key File adds an Identity File such as~/.ssh/id_ed25519. Continue saves the host. - Install Runtime. Alera checks the connection and shows who it reached and whether an Alera runtime is already installed, next to What Will Be Installed: the install directory, platform, version, and source. The button then reads Install Runtime when none is installed, Update Runtime when the connected host runs an older runtime than This Device, and Connect otherwise. Progress shows each stage, and Cancel Install stops it.
- Done. The dialog confirms the host is ready, with Add a Project to This Host or Done.
Closing the dialog never cancels an install that is already running. The host keeps showing Installing…, and a toast says Alera runtime installed on the host when it finishes.
The first connection records the host’s key; a key that later changes is refused.
Use A Specific Key#
With Key File, Alera passes the Identity File to ssh and sftp with -i and offers only that key, so a server with a low MaxAuthTries does not refuse you after trying every key in your agent. A passphrase-protected key still has to be loaded into your agent. Leaving the field empty goes back to your agent and ~/.ssh/config.
What The Install Does#
- Check SSH authentication and detect the platform and architecture.
- Download the latest stable signed runtime archive from GitHub Releases, verify its Ed25519 signature, and check the tarball’s SHA-256 and size.
- Upload the tarball over SFTP, so the host never has to reach GitHub.
- Extract it under
versions/, pointcurrentat it, and write thebin/alerawrapper (bin\alera.cmdon Windows). If this fails, the previous version stays current. - Validate the installed runtime.
The install creates no system service and no workspace.
Host States#
Each host shows one state, in Settings, in the status bar, and in host pickers.
| State | What it means |
|---|---|
| Needs Setup | The Alera runtime is not installed there yet. Install Runtime fixes it. |
| Installing… | An install or update is running. |
| Not Connected | The runtime is installed and the host is idle. Alera connects when something needs it. |
| Offline | The machine or its SSH server could not be reached. |
| Connecting… | Alera is opening the connection, or retrying after a drop. |
| Connected | The host is linked and ready. |
| Update Available | Connected, but the host runs an older Alera runtime than This Device. |
| Error | The install failed, or SSH reached the host but the connection did not work, for example a refused key or a broken runtime. The detail and Retry appear under the header. |
Manage A Host#
Select a host in Settings → Remote Hosts. The header shows its SSH address, platform, runtime version, how many projects and workspaces it holds, and when it was last checked, with the one action its state calls for: Install Runtime, Connect, Disconnect, or Update Runtime.
- Check Connection probes SSH and the installed runtime now and records the result.
- More Actions has Edit Connection, Copy SSH Command, and Remove Host.
- Projects on This Host lists the projects there and adds more.
- Advanced holds Install Directory (empty uses a folder under
~/.aleraon macOS and Linux, or%LOCALAPPDATA%\Alera\runtimeon Windows), Projects Folder, Platform and Architecture (both Auto by default, which asks the host), and Identity File. - Diagnostics shows the last check and the last error, and Open Logs Folder opens the logs of the Alera runtime on This Device, which records every connection and install.
Connect And Disconnect#
The connection to a host carries its file, Git, and search requests; each terminal gets its own SSH session. A host with an active workspace, or one you connected with Connect, stays connected, and Alera reconnects it after a drop, waiting longer after each failure, from 2 seconds up to 5 minutes. Any other host connects when something needs it and closes after 10 minutes without requests, which leaves it Not Connected.
Disconnect closes the connection and stops Alera from reconnecting on its own. Connect, Check Connection, or opening a terminal on that host lifts it.
Update The Runtime#
When a host reads Update Available, Update Runtime installs the latest stable runtime and then restarts the host’s runtime onto it, adding the stages Restart runtime and Remove old versions. The version the host is running stays on disk until the new one is running. A toast says Alera runtime updated on the host when it finishes.
Restarting closes the terminals open on that host. When there are any, Alera asks first with Close Terminals?, naming how many, and the confirmation reads like Close 2 Terminals and Update. Agents running in those terminals stop.
Remove A Host#
Remove Host forgets the host. It is unavailable while the host still has projects or workspaces: remove its workspaces and take its projects off it first. Removing a host does not uninstall the Alera runtime or delete files on the host.
Put A Project On The Host#
A Git project is registered once, then added to hosts. In a host’s Projects on This Host, use Add Project to This Host:
- Add Existing Project… picks a registered project. Enter an Existing Path on the host, or leave it empty and the host clones the project’s
originremote into its projects folder with its own Git credentials. - New Remote Project… registers a folder already on the host or clones a repository there, and copies nothing to this computer.
You can do the same from the sidebar: right-click a project, choose Hosts, and use Add to Another Host. Add Project also offers Add Remote Project. Removing a project from a host never deletes files. Folder projects stay on one host.
Create A Workspace There#
In New Workspace (Mod+Shift+N), pick the machine under Host. A host that cannot take a workspace yet stays in the list but cannot be picked, with its state in parentheses, such as Build Mac (Needs Setup). Offline and Not Connected hosts can be picked, because Alera connects when the workspace needs it. A project not yet on that host shows Add to Host in place.
- New Worktree creates a Git worktree under
~/.alera/workspaceson the host (%USERPROFILE%\.alera\workspaceson Windows), from branches already in the host’s repository. Alera does not fetch first. - Project Folder shares the host checkout’s current branch and files.
Status Bar And Notifications#
Once a host is registered, the status bar shows a Hosts chip such as Hosts 2/3, connected over registered, with Installing… while an install runs. Its color follows the host that needs the most attention. Hover or click it for one row per host with a quick fix (Connect, Retry, or Update), plus Add Host and Open Remote Hosts.
When a connected host drops, a toast says it disconnected, or that it is reconnecting, with Open Host. A later reconnected note follows only for a drop that was announced. Your own Disconnect and the host open in Settings stay quiet.
From The CLI#
alera ssh-target add --id build --alias "Build Box" --host build.example.com --username me
alera ssh-target bootstrap --id build
alera project hosts add --project-id <project-id> --host-id build
alera workspace add --project-id <project-id> --host-id build --worktree --branch feature/login --source-branch mainadd --auth key --identity-file ~/.ssh/id_ed25519uses a specific key, andupdate --id build --identity-file ""goes back to the agent.statusprobes SSH and the installed runtime.link --id build --connectand--disconnectmatch Connect and Disconnect.update-runtime --id buildinstalls the latest stable runtime and restarts the host onto it.restart-runtime --id buildrestarts the runtime already installed. Both refuse while terminals are open on the host unless you pass--force, which closes them.remove --id buildrefuses while the host still has projects or workspaces.
With Alera running, bootstrap and update-runtime return as soon as the job starts, and Settings → Remote Hosts shows its progress.
What Runs On The Host#
- Terminals and their agents. The status hooks you enabled are installed on the host, and agent states flow back to your sidebar.
- Explorer with edits, Search and replace, and Quick Open.
- Source Control, from staging to push.
- Pull requests and checks, through the host’s forge CLI and credentials. Your desktop’s environment and tokens are never sent.
- AI Assist, using the agent CLI on the host.
- Agent quotas while a workspace there is active, and per-terminal CPU and memory in the Resource Manager while the host is connected.
In a terminal on the host, project and workspace commands such as alera workspace list reach your desktop, and a new workspace defaults to that host. Without a connected desktop they fail. Terminal, host, account, and settings commands never reach the desktop from a host.
What Stays On The Desktop#
Projects, workspaces, tabs, and settings live on your desktop; the host keeps disposable copies of the workspaces it serves. Notifications, mobile push, and the Watch and Fix schedule run here, and Open → In Browser in the workspace menu opens your own browser. The sidebar and the phone mark remote workspaces with the host’s operating system icon.
Limits Today#
- Worktree setup does not run for a workspace created on a remote host: no copy rules, no
.worktreeinclude, no setup commands, no Setup terminal. See alera.toml. - Explorer and Source Control do not watch a remote checkout. Use Refresh after an agent changes files.
- A pasted image becomes a path to a temporary file on this computer, which the host cannot open.
- Workspaces do not move between hosts, and checkouts on different hosts are never synced: Git is the only link.