Set up your machine

Awayline requires SSH access to a Mac or Linux machine and a network route from your device to it. It can install herdr and start the default session automatically. Your coding agents continue running on the machine.

1. Enable SSH

On a Mac, open System Settings → General → Sharing → Remote Login. Allow your user account. On Linux, install and enable your distribution's OpenSSH server, then confirm that your account can sign in.

Test from another computer with ssh your-user@your-machine. If this fails, resolve SSH access before adding the machine to Awayline. On the same Wi-Fi network, use the machine's local address. Away from home, a private network such as Tailscale is a convenient way to reach it. Awayline itself does not expose SSH to the internet or configure your router.

2. Create a dedicated key

Run this on a trusted computer. Choose a unique filename if one already exists, and set a passphrase when prompted.

ssh-keygen -t ed25519 -f ~/.ssh/shepherd

Authorize the contents of ~/.ssh/shepherd.pub for the account on the target machine. If the key was created on that same machine, run:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat ~/.ssh/shepherd.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

If you created the key elsewhere, copy only the public .pub file to the target's ~/.ssh/authorized_keys. Keep the private file secret. Transfer the private file to your device through a trusted method, then choose Import private key… in Awayline. Delete temporary transfer copies when finished. Enter the key passphrase if you set one.

3. Add the machine

Add the machine's address, SSH port, username, and authentication method in Awayline. Allow Local Network access if prompted. After you verify its host key, Set up herdr automatically checks for an existing installation, installs herdr if needed, and starts the default session. Turn this option off in the machine's settings if you manage herdr yourself.

Automatic installation supports Apple silicon and Intel Macs, and ARM64 and x86-64 Linux machines. It downloads the pinned herdr 0.8.0 release from the official GitHub repository over HTTPS, verifies its SHA-256 checksum, and installs it at ~/.local/bin/herdr. No administrator privileges are needed, no shell startup files are changed, and existing binaries are never replaced. The machine needs internet access plus curl or wget and one of shasum, sha256sum, or openssl. It keeps the session running after the app disconnects; it does not install a boot service or update herdr automatically.

If startup fails, run ~/.local/bin/herdr on the machine to inspect its setup. Startup logs are saved under ~/.config/herdr/mobile-startup.*. You can also install herdr manually using the instructions at herdr.dev.

For a named herdr session, enter its name under herdr settings. For a custom socket, enter its absolute socket path. The native herd and console use the same resolved socket. Automatic setup does not create or replace explicitly selected sessions; a missing named session or custom socket produces an error. A custom remote herdr configuration also needs manual startup and its explicit socket path.

4. Verify the machine's identity

On the machine, read its host-key fingerprint:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Compare it with the fingerprint Awayline shows before choosing Trust. A future key change needs your attention; check whether the machine was rebuilt before replacing trust.

Jump hosts and prerequisites

If a machine is reachable only through another SSH machine, save the reachable machine first, then select it under Connect through on the target. Both host keys are verified separately. Awayline currently supports one jump.

The API relay needs one of nc, socat, or python3. File browsing additionally needs python3; diffs need Git. Install these on the target if a feature reports that a helper is unavailable.