Linux runners

On Linux, ax deploy ssh registers ax as a systemd service and runs each job under systemd with cgroup v2. It installs for the SSH user by default, or machine-wide with --system. Each mode keeps its files in different places, and in either mode the owner can let jobs use sudo. For the deployment command, upgrades and removal, see Install ax over SSH.

Service units

Both modes register ax.service, which runs ax serve --config <FILE>. This unit is the execution host. It is separate from the connection broker that a caller runs. Its API, privileged helper and job-supervisor roles share the ax executable. Each job gets a transient unit with the ax-job- prefix.

User mode

Starting at boot needs a working user systemd manager and lingering. The installer enables lingering where existing local policy allows it, and never uses sudo implicitly. If an administrator has to act, the result names that action and reports boot_enabled: false.

Jobs run as separate transient user services, so restarting the API does not stop them.

User mode trusts every other process running as that account. It does not protect user-owned credentials or state from them. Private configuration is in ~/.config/ax, state in ~/.local/state/ax, and the supervisor launcher in ~/.local/share/ax/supervisor.

System mode

System mode also registers ax-helper.service and a fixed ax-supervisor role launcher. Its paths are /etc/ax/helper.json, /run/ax and /var/lib/ax-helper, and the API state is in /var/lib/ax.

The API unit runs as ax-service-user, which provisioning creates. That account must have its expected home, a noninteractive shell and no extra groups. Jobs run as the SSH user or the account named with --run-as. ax does not create the job account.

On a repeat run, ax checks the helper binding, the configuration, state ownership and the node key. It refuses unexpected changes rather than replacing identities or choices the owner made.

Allow sudo in Linux jobs

Linux runners block privilege elevation by default. To let authorised jobs use an account's existing sudo permissions, the runner owner can set:

"allow_sudo": true

Leaving the setting out, or setting it to false, blocks elevation for new jobs. Restarting the service does not change jobs that are already running.

ax exec info <runner> advertises the sudo adapter when sudo is permitted. This reports the runner's policy. It does not promise that sudo is installed or that a particular command is allowed. Use sudo -n in jobs, so that a password requirement fails immediately. ax does not change sudoers, supply passwords or open a terminal. The effective setting is recorded in each sealed job specification.

Before you enable it:

• Enabling it removes the job's no_new_privs restriction, which also affects other setuid and file-capability programs.
• The setting applies to every authorised job on that runner. Enable it only when those callers may use the job account's sudo permissions.
• Sudo may permit full host administration, including changing ax or moving work outside its supervision. Account permissions and working-directory limits do not contain root. Use another runner account or a narrower sudoers policy when callers need less access.
• An enabled job fails at launch if it inherits a no_new_privs restriction. ax cannot clear that kernel flag.

Next steps

• Install ax over SSH explains the readiness checks a deployment runs.
• Security model: the accounts and privilege separation of a system installation.
• Run ax as a service compares user and system installations.