OPERATIONS · MANAGED

Serve multiple system users through a gateway.

Managed mode limits the root gateway to ingress and identity routing. A long-lived, unprivileged worker for each Unix UID owns that user's terminals and files.

Prerequisites

Managed mode is for administrators who need multiple existing Linux system accounts behind one entry point. Installing and running the gateway requires root. Prefer Rootless mode if only your own account needs access. First follow Obtain and build on the Rootless page and keep the current directory at the cloned astra-shell repository.

Process topology

root gateway→UID worker→Workspace / Terminal

The gateway does not retain user PTYs. After authentication, it routes the connection to the unprivileged worker for that UID.

Install the systemd service

These commands install the Release binary and Managed service template into system paths, then start the UDP 4433 gateway immediately:

cargo build --release --locked --bins
sudo install -o root -g root -m 0755 target/release/astrad /usr/local/sbin/astrad
sudo install -d -o root -g root -m 0700 /srv/astra
sudo /usr/local/sbin/astrad init --state-dir /srv/astra
sudo install -o root -g root -m 0644 contrib/systemd/astrad.service /etc/systemd/system/astrad.service
sudo systemctl daemon-reload
sudo systemctl enable --now astrad.service
sudo systemctl status astrad.service

Allow UDP 4433 in the cloud security group and host firewall. To change the port, copy and edit the unit's --listen value, then run systemctl daemon-reload and restart it. Opening only the TCP port will not make Astra reachable.

Account authentication

The server resolves the Host username through the system passwd database and reads that account's ~/.ssh/authorized_keys. Every target user must add the complete one-line output of Copy Public Key to their own file. The home directory and .ssh must belong to that user, with .ssh at 0700 and authorized_keys at 0600. Managed mode does not read the Rootless state directory's authorized_keys.

Worker lifecycle

At most one long-lived worker serves each UID.
An existing worker can keep PTYs through a gateway restart.
An idle worker with no Terminals is reclaimed after 600 seconds by default.
A worker or full-server restart does not restore running Terminals from disk.

Operational boundary

Before upgrading the gateway, keep the previous binary and a backup of /srv/astra, and verify worker compatibility with the target version. Do not terminate a user worker that still owns Terminals: doing so ends every running Shell for that Unix user. Worker discovery, cross-version upgrades, long soak tests, and failure injection still need validation in each production environment. Plan maintenance windows and rollback using “Current boundaries.”