Opening the remote KISS Sorcar IDE from any machine with SSH keys

The remote editor used to be reachable only from the laptop that deployed it, and only during that deploy. It is now a permanently-running service that any machine with SSH access can discover and open with a single 300-line file — sorcar-connect.

1. What was wrong

sorcar-cloud pushes your working directory to a Linux host, installs KISS Sorcar there and starts code-server — VS Code running as a web app. The editor binds 127.0.0.1 only (it runs with --auth none, so it must never face the internet), and an SSH tunnel is the way in. That part was fine. Two things were not.

setsid bash -c "... exec code-server --bind-addr 127.0.0.1:$PORT --auth none ... '$WORKSPACE'" \
    > "$LOG_DIR/code-server.log" 2>&1 < /dev/null &

2. The fix, in two halves

Half one — the IDE becomes a supervised, boot-started service

Step 7 of the deploy now writes a systemd user unit (no sudo anywhere) and enables lingering for the remote user:

# ~/.config/systemd/user/kiss-code-server.service
[Unit]
Description=KISS Sorcar IDE (code-server) on 127.0.0.1:8080
After=network-online.target

[Service]
Type=exec
EnvironmentFile=-%h/.kiss/api_keys.systemd.env
Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment="KISS_PROJECT_PATH=/home/ksen/kiss"
WorkingDirectory=/home/ksen/kiss
ExecStart=/home/ksen/.local/bin/code-server --bind-addr 127.0.0.1:8080 --auth none \
    --disable-workspace-trust --enable-proposed-api ksenxx.kiss-sorcar "/home/ksen/kiss"
Restart=always
RestartSec=3
StandardOutput=append:%h/.kiss/code-server.log
StandardError=append:%h/.kiss/code-server.log

[Install]
WantedBy=default.target

Why each line is there:

• Restart=always — a crashed or OOM-killed editor comes back in 3 seconds.
• WantedBy=default.target + loginctl enable-linger — the pair is what makes the editor start at boot. Lingering, in systemd's own words, means a user manager is spawned for the user at boot and kept around after logouts; without it the whole user manager (and kiss-web with it) is killed the moment the deploying SSH session closes.
• EnvironmentFile=-…api_keys.systemd.env — the API keys, from the very file the kiss-web unit already uses. A systemd service inherits nothing from a login shell, so this (and the explicit PATH) replaces the environment the old setsid launch inherited by accident. The leading - keeps a missing file non-fatal.
• append: — output goes to ~/.kiss/code-server.log, the file every error message already points at. The deploy truncates it first so it cannot grow forever across restarts.
• The unit is called kiss-code-server, not code-server, so it can never collide with a unit a distro package owns.

Two ordering details matter. Lingering is enabled before systemctl --user enable, because without a lingering user manager "enabled at boot" is an empty promise. And the deploy's wipe step now stops the unit before its pkill: with Restart=always, killing the process would just make systemd start a new editor on the directory about to be deleted.

Half two — the host publishes how to reach it, and one file consumes that

The deploy writes the facts a client needs into the remote home directory:

# ~/.kiss/sorcar-cloud.env  (chmod 600, no secrets)
SORCAR_IDE_PORT=8080
SORCAR_WEB_PORT=8787
SORCAR_WORKSPACE=/home/ksen/kiss
SORCAR_IDE_SERVICE=kiss-code-server

It is excluded from the ~/.kiss mirror (which runs with --delete), so a later deploy from a laptop that has no such file cannot wipe the host's record of itself.

The new sorcar-connect is the client. It is deliberately one self-contained file that needs nothing but bash and ssh:

scp user@host:kiss/sorcar-connect .    # once, on the new machine
./sorcar-connect user@host             # every time after that

What it does, in order:

1. Asks the host, in a single SSH round trip, for its sorcar-cloud.env facts.
2. Checks the editor with code-server's own unauthenticated /healthz route — which proves the editor is serving, not merely that something holds the port — and systemctl --user starts the unit if it is silent. So even a host where someone stopped the service is repaired by connecting to it.
3. Picks free local ports (preferring the familiar 8080/8787, falling back to +10000) and forwards both the IDE and the kiss-web webapp with ssh -N -n -o ExitOnForwardFailure=yes -o ServerAliveInterval=30.
4. Opens your browser, waits for the webapp, and holds the tunnel until Ctrl+C — which closes the forward and leaves the remote editor running for the next machine.

--print skips all of that and just prints the two commands the host supports, for a machine where you would rather not run a script at all:

$ ./sorcar-connect --print ksen@34.42.88.157
[STEP]  Asking ksen@34.42.88.157 about its KISS Sorcar deployment ...
[ksen-vm-32] IDE is answering on 127.0.0.1:8080 (workspace: /home/ksen/kiss).

  Forward the ports yourself, then open http://localhost:8080 :
    ssh -N -n -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
        -L 8080:127.0.0.1:8080 -L 18787:127.0.0.1:8787 ksen@34.42.88.157

  Or, with desktop VS Code + the Remote-SSH extension, skip the tunnel:
    code --remote ssh-remote+ksen@34.42.88.157 /home/ksen/kiss

The deploy itself now ends with exec ./sorcar-connect … — about 110 lines of tunnel, browser and hold logic were deleted from sorcar-cloud rather than duplicated. That is not just tidiness: the path your other machines take is therefore exercised on every single deploy, so it cannot quietly rot. ./sorcar-cloud --connect user@host is a shortcut to the same script for people who only remember one command.

3. Why SSH tunnelling, and not something flashier

One more research finding that made this safe: a single code-server instance is happy with several concurrent browsers and tunnels (unlike Microsoft's VS Code Server, which documents an instance of the server is designed to be accessed by one user or client at a time). Your desktop and your laptop can be connected at once.

4. Evidence — eight live tests on the real VM

Test 7 is the one that closes the loop on the riskiest part of the change. Moving off the setsid launch meant the editor no longer inherits a login shell's environment, so the agent could have lost its API keys. A successful claude-opus-5 call — recorded in the VM's own database, reporting the VM's own GCP-internal hostname — proves the EnvironmentFile path works. Test 3 also confirmed the tunnel hygiene from the earlier review still holds: SIGTERM to the client prints Closing the SSH tunnels…, frees the local port and leaves the remote editor untouched.

5. A bug found by accident, and fixed

COPYFILE_DISABLE=1 tar --no-xattrs --exclude='.venv' --exclude='.kiss-worktrees' \
    -C "$src" -czpf - . | ssh "$TARGET" "mkdir -p -- '$dst' && tar -C '$dst' -xzpf -" || true
local tar_rc="${PIPESTATUS[0]}" ssh_rc="${PIPESTATUS[1]}"
((ssh_rc == 0)) || die "The remote refused the copy (ssh/tar exit $ssh_rc)."
((tar_rc <= 1)) || die "Local tar failed with exit $tar_rc — the copy is incomplete."
((tar_rc == 0)) || warn "tar reported warnings (exit 1) — usually a file that changed while being read."

6. What changed, file by file

Both files pass bash -n and shellcheck (only the pre-existing intentional informational notes remain: client-side expansion in ssh "VAR='$X' bash -s", and tildes inside message strings).

7. How to use it

# From the machine with the checkout — deploy, then it opens the IDE for you:
./sorcar-cloud ksen@34.42.88.157

# From that same machine later, without redeploying:
./sorcar-cloud --connect ksen@34.42.88.157

# From ANY machine that can ssh into the host:
scp ksen@34.42.88.157:kiss/sorcar-connect .
./sorcar-connect ksen@34.42.88.157

# Or with no script at all:
./sorcar-connect --print ksen@34.42.88.157   # copy the ssh -L line it prints

If the host is ever truly stuck, the two commands that tell you everything are systemctl --user status kiss-code-server and tail ~/.kiss/code-server.log.