Use Gardn over SSH

Use this how-to when the workspaces and panes should run on another Unix host. A plain SSH shell and a Gardn remote client are different paths:

• ssh workbox gives you the host's ordinary shell.
• gardn --remote workbox runs a local client whose terminal session is bridged to Gardn on workbox.

Remote attach supports Unix local clients (Linux and macOS) and Windows local clients. Supported remote hosts are Linux and macOS on x86_64 or aarch64; Windows is not a supported remote host for this path. See platforms for the support boundary.

Prepare SSH access

1. Add a host alias to ~/.ssh/config if you want stable target settings:

   Host workbox
       HostName workbox.example.com
       User alice
       IdentityFile ~/.ssh/id_ed25519

2. Verify the shell path first:

   ssh workbox

3. If the key has a passphrase, load it into your SSH agent before starting the bridge:

   ssh-add ~/.ssh/id_ed25519

The first connection may ask you to verify the host key. Confirm it only when the host identity is expected and trusted.

Run selected resources on SSH hosts

Use mixed-host placement when one Gardn session must contain both local and remote panes. This is separate from gardn --remote, which moves the whole session server to the SSH host.

Save a connection before creating remote resources:

1. Open Settings > Connections, or use the CLI, and save a profile with a display name, OpenSSH target, and optional suggested directory. Saving authorizes Gardn to manage its versioned worker on that host.
2. Select Test connection if you want a read-only connectivity check. Resolve authentication or host-key failures before continuing.
3. Select Connect. Gardn installs or updates the worker automatically. A compatible worker with live runtimes remains active until it is unused, then the current worker activates.
4. In Group settings, set Default location to the connection and a host-native directory, or create the group with that default. This affects only future workspaces.
5. Create a workspace. Keep the inherited location or select another execution host and directory.

The suggested directory initializes the location picker when you select that profile. It is not an ambient default and does not override a Group, Workspace, or focused-terminal location.

A new workspace uses an explicit location, then its target Group default, then Local. A new tab or agent uses an explicit location, then the invoking client's focused terminal location, then the Workspace default. A split uses an explicit location or the source terminal location. Host and path always move together.

Changing a Group or Workspace default does not move or restart existing terminals. One workspace can contain terminals on different hosts. Such a workspace shows Mixed, and pane badges identify terminals whose host differs from the workspace default. An unavailable remote host does not stop local terminals.

When the local coordinator restarts, each restored remote pane reconnects its saved SSH profile and re-adopts the live worker runtime automatically. If SSH authentication or worker compatibility blocks the connection, the pane remains unavailable until you resolve the connection status in Settings > Connections.

The CLI exposes profile setup and placement:

gardn connection save workbox --name "Work box" --target workbox --directory /srv/project
gardn connection test workbox
gardn connection connect workbox
gardn connection list
gardn group create remote-side --host ssh:workbox:1 --cwd /srv/project
gardn workspace create --focus

connection.list returns the profile's execution_host_id, for example ssh:workbox:1. Use that id for explicit resource placement:

gardn workspace create --host ssh:workbox:1 --cwd /srv/project --focus
gardn tab create --workspace w1943cd2b11a1 --host ssh:workbox:1 --cwd /srv/project
gardn pane split --direction right --host ssh:workbox:1 --cwd /srv/project
gardn agent start reviewer --host ssh:workbox:1 --cwd /srv/project -- codex

--host requires --cwd. The corresponding Local API methods accept a location object with execution_host_id and path. Do not send both cwd and location. group.create accepts optional default_location with the same shape; invalid placement fails without creating the group.

Install agent integrations on an SSH host

Use the managed connection when an agent running on that Execution Host needs a Gardn integration:

1. Connect the profile in Settings > Connections.
2. Open Settings > Integrations.
3. Set Integration host to the saved connection.
4. Wait for the host status to load, then install or update the target integration.
5. Restart the affected remote agent pane.

The selected execution worker performs the inspection and mutation on that host. Integration operations for one host run in order. Disconnecting the host fails pending operations instead of applying them to Local. The gardn integration CLI and Local API integration methods manage only the Coordinator Host.

Remove a managed connection

Remove a saved connection from Settings > Connections:

1. Open the connection and select Remove connection.
2. Wait while Gardn inventories every named session and owned worker binding. No resource changes during inventory.
3. Review the listed Group defaults, Workspace defaults, panes, pending terminations, and worker processes.
4. Confirm the removal. Gardn blocks new work on the host, closes remote panes, moves affected Workspace defaults to the displayed Local directory, removes owned worker bindings, and deletes the profile only after every session is clear.

Removal progress is journaled. If the app stops, the next server start resumes the approved removal before it accepts new work for that host. Unrelated remote processes and standalone Gardn sessions are not removed.

If full cleanup is unavailable, the failure screen warns that remote processes or worker files might remain. Select Remove saved connection to delete the local profile and placement state without claiming remote cleanup. Select Try again to retry full cleanup, or Cancel to leave the connection unchanged.

The Local API exposes per-session retirement primitives for automation. See connection.retire.start and connection.retire.status. The CLI connection delete command removes only an unreferenced profile; it does not perform the cross-session retirement workflow.

Attach through the bridge

Run the bridge from the local machine:

gardn --remote workbox

You can combine it with a named session:

gardn --remote workbox --session project

By default, Gardn manages the SSH configuration used by the bridge. It starts with your ~/.ssh/config and adds a fallback Host * block with ServerAliveInterval 15 and ServerAliveCountMax 4, so explicit keepalive values in your SSH configuration win. To use your SSH configuration unchanged, set:

[remote]
manage_ssh_config = false

This setting changes only bridge SSH setup; it does not grant access to the host or bypass SSH authentication.

Install or build the remote binary

The remote host needs a matching Gardn version. The bridge can use a matching binary already installed in the remote user's ~/.local/bin/gardn; when an install is needed it asks before writing there. Treat that prompt as a trust boundary and approve it only for a host you control.

Verified public gardn-* release downloads are not currently available, so do not rely on the automatic release-download path for a new remote host. Build from the source checkout instead:

cargo build --release --package gardn

The resulting target/release/gardn must be built for the remote host's operating system and architecture. A Nix source build is also available from the repository root:

nix build .#gardn

To have the bridge install a matching source-built binary, set GARDN_REMOTE_BINARY to that file:

GARDN_REMOTE_BINARY="$PWD/target/release/gardn" gardn --remote workbox

For a Nix build, use GARDN_REMOTE_BINARY="$PWD/result/bin/gardn" instead. The override file must be a binary built for the remote host.

Use the resulting result/bin/gardn (or a matching target build) as the remote binary source when building or installing on the remote host. Do not copy a macOS binary to Linux, or an x86_64 binary to aarch64.

Choose where keybindings run

Remote app attach uses local keybindings by default. To run the app keybindings from the remote configuration instead, use:

gardn --remote workbox --remote-keybindings server

--remote-keybindings accepts only local or server. This choice affects app key dispatch; the local terminal still has to deliver the key events to the client.

When the remote client is active, the default keys.remote_image_paste = "ctrl+v" binding can forward an image from the local clipboard. Set it to an empty value to disable raw-key image paste. Image forwarding requires a supported local clipboard helper and sends the image to the focused remote pane; treat clipboard contents as data leaving the local machine.

Update or take over a running server

If the remote server version differs, a normal attach may require a remote server restart. Restarting can interrupt the running panes. Use the explicit handoff opt-in when the server and client support live handoff:

gardn --remote workbox --handoff

Read the prompt and status carefully. A successful handoff keeps eligible live processes; unsupported or failed handoff falls back to the safer restart path and reports the failure. Never approve a restart or fallback when preserving the remote processes is required; cancel and resolve the version or capability mismatch first.

For direct access to a detached local server, use gardn session attach <name>. To attach directly to an agent or terminal on that server, use gardn agent attach <target> [--takeover] or gardn terminal attach <terminal-id> [--takeover]. --takeover transfers terminal ownership and can disconnect the current client, so use it only when you intentionally want to take control.