Skip to main content

Installation

The Proxima Agent is installed via a single shell script that handles binary download, preflight checks, and systemd service setup.

Prerequisites​

  • OS: Ubuntu 20.04+, Debian 11+, RHEL 8+, Rocky 8+, or Alma 8+
  • Architecture: amd64 or arm64
  • Init system: systemd
  • Access: Root or sudo privileges
  • Network: Outbound HTTPS (port 443) to the backend URL and NATS (port 4222)
  • Disk: At least 500 MB free in /var/lib/
  • Tools: curl, tar, systemctl

Quick Install​

The agent uses an install token for enrollment. It enrolls over HTTPS and receives per-host NATS credentials automatically.

curl -sL https://install.prxm.uz/agent.sh | bash -s -- \
  --install-token <token> \
  --backend-url https://api-console.prxm.uz
ParameterDescription
--install-tokenInstall token created via POST /api/v1/clients/{slug}/install-tokens
--backend-urlBackend HTTPS URL for enrollment

The agent obtains its agent_id, client, environment, and NATS URL automatically during enrollment — no additional flags are needed. The enrollment response contains agent_id (the UUID from the agents table), not a host_id. The host record is created later by the backend when the first inventory message is processed.

Dynamic Configuration

After installation, the agent automatically receives its operational configuration (collectors, labels, change detection, log collection) from the backend. Configure these settings via the Console UI — changes are pushed to agents in real-time without requiring a restart. See Agent Configuration for details.

tip

Install tokens are single-use by default and expire (default 24 hours, max 30 days). To reuse one token across a fleet, create it with max_uses: 0 (unlimited) or max_uses: N. See NATS Security -- Agent Enrollment for the full flow.

What the Install Script Does​

  1. OS/arch detection — automatically detects the operating system and architecture (linux/amd64 or linux/arm64)
  2. Resolves version — if --version latest (default), fetches the latest stable version tag from R2
  3. Downloads the binary — fetches the appropriate agent binary from Cloudflare R2 and verifies the SHA256 checksum
  4. Runs preflight checks — executes proxima-agent preflight --backend-url <url> to verify connectivity and system requirements
  5. Creates data directory — creates /var/lib/proxima-agent with mode 0700 for persistent agent state
  6. Creates systemd unit — installs a systemd service that passes all configuration via Environment= lines (no config file) and restarts the agent automatically on failure (Restart=always)
  7. Starts the service — the agent enrolls on first boot, receives its agent_id from the backend, and writes state.json (containing agent_id, agent_type, JWT, nkey seed, and slugs) to the data directory

Optional Flags​

Install a Specific Version​

By default the script installs the latest stable release. Use --version to pin a specific version:

curl -sL https://install.prxm.uz/agent.sh | bash -s -- \
  --install-token <token> \
  --backend-url https://api-console.prxm.uz \
  --version v0.2.0-beta.1

Dev Mode (Skip Download)​

If you have a locally built binary, use --dev to skip the download step:

curl -sL https://install.prxm.uz/agent.sh | bash -s -- \
  --install-token <token> \
  --backend-url https://api-console.prxm.uz \
  --dev /path/to/proxima-agent

Uninstall​

To remove the agent and stop the service:

curl -sL https://install.prxm.uz/agent.sh | bash -s -- --uninstall

This stops and disables the systemd service, removes the binary and unit file. The data directory (/var/lib/proxima-agent) is preserved for safety — remove it manually if needed.

Auto-Update​

The agent supports two update mechanisms:

Backend-Controlled Updates (Default)​

The agent reports its version in every heartbeat. The backend compares against the desired version and sends a self_update command via NATS when an update is needed.

Update modes (configured per-environment in the backend):

ModeBehavior
auto (default)Backend automatically sends update command on version mismatch
manualUI shows "update available" badge; admin triggers update
disabledNo backend-initiated updates

CLI Self-Update​

Prefer console fleet rollouts

The recommended way to update agents — one host or the whole fleet — is now the console Fleet Management / Agents page, which runs observable, canary/batched rollouts with pause / resume / abort and automatic pause-on-failure. See Updating Agents (Fleet Management). Use the CLI/manual path below for single-host, one-off updates (or to bootstrap a host whose build predates the v0.6.1 self-update fix).

An ops engineer on the host can always update manually:

proxima-agent self-update            # update to latest
proxima-agent self-update v0.5.1     # pin to specific version

The update process:

  1. Downloads the new binary and verifies SHA256 checksum
  2. Backs up current binary to proxima-agent.prev
  3. Swaps the binary (atomic rename)
  4. Updates version field in state.json
  5. Prints a reminder to restart — the CLI does not restart the service itself; run systemctl restart proxima-agent to load the new binary. (Automatic restart only happens for backend/fleet-driven updates.)

Managing the Service​

After installation, the agent runs as a systemd service:

# Check status
systemctl status proxima-agent

# View logs
journalctl -u proxima-agent -f

# Restart the agent
systemctl restart proxima-agent

# Stop the agent
systemctl stop proxima-agent

# Check installed version
proxima-agent --version

# Run preflight checks
proxima-agent preflight --backend-url https://api-console.prxm.uz

# Manually trigger self-update
proxima-agent self-update