Automation

SSH remote workspaces

Add a remote host and work in a remote directory from the same UI, with a matching vortex-server deployed to the host over SSH.

A workspace does not have to live on your Mac. Add a remote host and open a directory on it, and the same UI, modes, plan files, and Changes panel work against the remote tree.

Adding a host

Point Vortex at a host you can already reach with SSH. Key-based auth and your SSH agent are used as they are; Vortex does not ask for your private key and does not store it.

Add the host to ~/.ssh/config first if it needs a specific key, port, or jump host. Vortex connects with key-based auth and your SSH agent rather than prompting for a password.

The remote needs the server binary available in one of two places:

vortex on PATH.
~/.vortex-server/vortex.

Add a remote workspace

Open the workspace picker from the command palette (⌘K) and choose to add a host.
Enter a host you can already reach with ssh and confirm the connection.
Pick the directory on the remote to work in.
Let Vortex probe the remote and deploy vortex-server if it is missing.

After that, the workspace behaves like a local one: choose a mode, describe the job, and review the result.

What Vortex deploys

Before the first run, Vortex probes the remote's libc and deploys a matching vortex-server build:

Remote libc	Binary deployed
glibc	glibc-linked `vortex-server`
musl	musl-linked `vortex-server`

That is why an Alpine container or a Home Assistant box gets a binary it can actually execute, instead of a glibc binary that fails to load.

What runs where

The split is deliberate:

Runs on your Mac	Runs on the remote
The agent loop	File reads and edits
Model calls	Terminal commands
Plan and review state	Command output captured back into the run

Your model keys stay on your Mac; the remote process does the file and shell work. No GitHub token or API key is written into the repo or into app preferences.

Because model calls stay local, the remote does not need a provider key, and provider traffic never leaves your Mac. The remote process only reads files, applies edits, and runs the commands the agent asks for.

Working in a remote workspace

The modes work the same way on a remote tree. Plan mode writes an editable plan file in the remote workspace's .vortex/plans/. Review mode stages agent edits as pending patches in the Changes panel, and nothing lands on the remote until you approve it. A verification check runs its command on the remote and reads the exit code and output phrase there.

The transcript streams file edits and terminal commands with the paths they touch. The Go menu in the tab bar jumps to a file, a view, a URL, or a job.

Detached jobs on the remote

A job started over SSH with nohup on the remote keeps running when you close your laptop, and writes its status and traces under ~/.vortex/detached/<id>/ on the remote. That is the only case where a closed laptop does not stop the work — a job on a sleeping local machine still stops with the machine. See Headless CLI for --detach and --list.

Troubleshooting

Connection refused. Confirm the host and port answer from a plain terminal first with ssh <host>. If that fails, the problem is the network, the SSH config, or the key, not Vortex.

Unsupported architecture. The probe selects between glibc and musl; it does not translate instruction sets. A CPU architecture with no matching build cannot host the server.

The binary will not execute. Check the mode on the deployed file. chmod +x ~/.vortex-server/vortex fixes a binary that was copied without the execute bit.

A command cannot find a tool. Commands run on the remote, so they use the remote's PATH. A binary installed only on your Mac is not available to a remote run.

The host needs a jump host. Reach the target through your own SSH config so the connection resolves the same way it does in a terminal.

Reading the remote log. The server writes its own log on the host; read it there over SSH rather than in the local app log. Local app events are still in ~/.vortex/logs/vortex.log.

Security notes

The remote server is a local process on your host. It listens for the app's connection, so keep it off the public internet and reach it only through SSH. Do not expose its port to the network, and do not copy your private key or API keys onto the remote.

The server runs as the SSH user, so it can read everything that user can read. Use an account scoped to the directories you actually want the agent to touch.

Headless CLI — start detached jobs against the same host.
MCP integrations — servers the agent can call from a remote workspace.
Models and keys — why provider keys stay on your Mac.
Install and updates — the beta channel and update details.

Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite.