OPERATIONS · ROOTLESS

Run Astra for one Unix user.

Rootless mode fits personal servers, development machines, and single-user environments. It needs no root privilege and does not switch between users.

When to use it

If only one system user needs Astra access, Rootless mode provides a smaller audit boundary. The daemon directly owns that user's Workspace, Terminals, and file operations.

Obtain and build

Sign in to the Linux host as the ordinary Unix user who will run the daemon. After installing Git and a stable Rust/Cargo toolchain, build from the public repository:

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

The remaining commands assume you are still inside this astra-shell repository.

Initialize and authorize

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

Generate or import a key in the client's Key Management, copy its public key, and add the complete key as one line in this file:

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

Rootless reads only the authorized_keys inside this state directory, not ~/.ssh/authorized_keys. Back up the entire state directory and protect its host private key; reinitializing it makes connected devices report a changed host identity.

Keep it running

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

The foreground command is suitable for initial verification. For continuous operation, use a systemd user service or similar process manager owned by the same ordinary user, restart after failures, and send logs to a controlled logging facility. The repository's contrib/systemd/astrad.service is a Managed root-gateway template and must not be reused unchanged for Rootless mode.

Deployment checklist

Allow only the UDP port you actually use in security groups, firewalls, and NAT
Confirm the daemon's Unix user, the Host username, and --session-root all match your intent
Keep the state directory at 0700, and authorized_keys and the host private key at 0600
Verify the first certificate fingerprint from a trusted server terminal
Set resource quotas, monitor rejection logs, and document upgrade and rollback steps