Open your first remote shell.

Before you start

Run every command below on the remote Linux host as the ordinary Unix user who will use Astra. First sign in through an existing SSH connection, your cloud provider's console, or a local terminal, then confirm that git --version and cargo --version both work. Rootless mode does not require root access.

Clone and initialize the server

The server source is in the public github.com/astra-sec/astra-shell repository. Run these commands from the remote user's home directory:

git clone https://github.com/astra-sec/astra-shell.git
cd astra-shell
cargo build --locked --bins

After a successful build, you should be inside the cloned astra-shell directory and have target/debug/astrad. Initialize state owned only by this user:

./target/debug/astrad init --state-dir "$HOME/.local/share/astra-shell"

This creates the host certificate, host private key, instance ID, and Rootless-specific authorized_keys. Do not delete or reinitialize this directory: clients will otherwise report that the host identity changed.

Authorize the client key

1. Open Key Management in the Astra Shell client.
2. Choose Generate to create the recommended Ed25519 key, or Import if you already have an OpenSSH private key.
3. Open that key's menu and choose Copy Public Key.
4. Return to the remote Linux terminal, open the file below in a text editor, paste the complete public key on its own line, and save it.

nano "$HOME/.local/share/astra-shell/authorized_keys"
chmod 600 "$HOME/.local/share/astra-shell/authorized_keys"

If nano is unavailable, use another text editor already installed on the host. A public key may be shared with the server for authentication; never copy the private key to the server. It remains in the client Keychain.

Start and expose UDP

Still inside the remote astra-shell source directory, start the daemon:

./target/debug/astrad serve \
  --listen 0.0.0.0:4433 \
  --state-dir "$HOME/.local/share/astra-shell" \
  --session-root "$HOME"

The command above sets --session-root to $HOME, restricting new Shells and Files to the home directory of the user running the daemon. This command runs in the foreground, so closing the terminal stops the service. After the first connection works, use a systemd user service or another process manager owned by the same user.

Print the host certificate fingerprint in the same trusted remote terminal:

printf 'SHA256:'
openssl dgst -sha256 -binary "$HOME/.local/share/astra-shell/host-cert.der" | base64 | tr -d '\n'
printf '\n'

Keep the resulting SHA256:... line and compare it exactly during the first connection.

Create the connection

1. Choose Add Host in Astra Shell and set the connection type to Astra, not SSH.
2. Enter a hostname or IP reachable from this device without an https:// prefix; enter 4433 as the port.
3. Use the Unix username that is running astrad; run whoami on the remote host to confirm it.
4. Select the key you generated or imported.
5. On first connection, compare the client's SHA-256 fingerprint with the remote command output character by character before trusting it.

Verify continuity

Open a shell and run whoami and pwd first to confirm the user and directory. Then run a harmless command that lasts a few minutes, briefly disconnect the client, and reconnect. You should return to the same Terminal instead of creating a new PTY.