Installation Wizard
The Installation Wizard provides a guided experience for adding hosts to Proxima Console. It walks you through platform selection, configuration, agent installation, and verification.
Overview
The wizard is a two-page flow:
- Platform Selection (
/hosts/add) — Choose your deployment method (Linux, Docker, Kubernetes, etc.) - Installation Page (
/hosts/add/linuxor/hosts/add/docker) — Configure, install, and verify in three steps
Using the Wizard
Step 1: Choose a Platform
Navigate to Hosts > Add Host or go directly to /hosts/add. Currently supported:
- Linux — systemd service for amd64/arm64 architectures
- Docker — container deployment with
docker runor Docker Compose
Coming soon: Kubernetes, Ansible, Terraform, and Push Install (SSH/Teleport).
Step 2: Configure
Select the client (organization) and environment (production, staging, etc.) where the host will be registered. The first environment is auto-selected for convenience.
Advanced Configuration
Expand the Advanced Configuration section to customize host-level agent settings:
- Log Level — debug, info, warn, error (default: info)
- Hostname Override — Custom hostname instead of system hostname
- Automatic Updates — Enable/disable auto-update (default: enabled)
Collectors (Docker, PostgreSQL, Nginx), labels, and change detection are configured after installation via the Agent Config page in the host detail view or at the environment level in Admin settings. The backend pushes configuration to agents automatically — no restart required.
Step 3: Install
Before generating, set two token options:
- Token expires in — how long the token stays valid (1 hour to 30 days; default 24 hours).
- Max installs — how many agents may enroll with the token: Single-use, a bounded count (5/10/25, default 10), or Unlimited. Single-use is the safest choice — a leaked token can enroll at most one host. Pick Unlimited only when rolling out a fleet from one token.
Click Generate Install Command to create the install token and reveal the installation command.
Linux
curl -fsSL https://install.prxm.uz/agent.sh | sudo bash -s -- \
--backend-url https://your-console.example.com \
--install-token <generated-token>
With a non-default log level selected in Advanced Configuration, the command appends --log-level:
curl -fsSL https://install.prxm.uz/agent.sh | sudo bash -s -- \
--backend-url https://your-console.example.com \
--install-token <generated-token> \
--log-level debug
Hostname override and collector/auto-update settings are not passed as install
flags — they are applied after enrollment from the Agent Config page (see the
post-install tip above). The install script only accepts --backend-url,
--install-token, and --log-level.
Docker
docker run -d --name proxima-agent \
--restart unless-stopped \
-e PROXIMA_BACKEND_URL=https://your-console.example.com \
-e PROXIMA_INSTALL_TOKEN=<generated-token> \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
registry.prxm.uz/proxima/console/agent:latest
A Docker Compose snippet is also available in a collapsible section on the Docker install page.
The install token is shown only once — copy it immediately. The post-generation banner states the token's actual usage limit and expiry (the wizard defaults to 10 installs over 24 hours).
Step 4: Verify
The wizard automatically polls for the new agent connection. Once detected, you'll see:
- Mini metrics cards — Live CPU, Memory, and Disk usage
- Host name, OS, and agent version
- Agent status badge
- Next steps — Links to view the host, add another, or configure monitoring
If the agent doesn't connect within 2 minutes, a troubleshooting section auto-expands with common solutions.
Pre-flight Checks
The install script runs pre-flight checks before installation to validate host readiness:
| Check | Requirement |
|---|---|
| Root/sudo | Must have root or sudo access |
| OS | Ubuntu 20.04+, Debian 11+, RHEL 8+, Rocky 8+, Alma 8+ |
| Architecture | amd64 or arm64 |
| systemd | Must be available |
| Network | Can reach backend URL |
| DNS | Can resolve NATS domain |
| Disk | >= 500MB free in /var/lib/ |
| No conflicts | No existing proxima-agent service |
| Tools | curl, tar, systemctl |
Pre-flight checks run automatically as part of installation.
First-Time Setup
When Proxima Console has no clients configured, users are automatically redirected to the installation wizard on login. This provides a guided onboarding experience for new deployments.
Host Lifecycle Management
The Host Detail page includes lifecycle management actions:
| Action | Effect | Reversible? |
|---|---|---|
| Deactivate | Blocks future credential renewals. Agent disconnects gracefully when current credentials expire. | Yes — use Activate to restore |
| Activate | Restores credential renewal, allowing the agent to reconnect. | Yes |
| Revoke | Immediately disconnects the agent by revoking its NATS JWT credentials. | Difficult — requires re-enrollment |
These actions require the hosts:write permission.
Troubleshooting
Agent not connecting
- Verify the install command completed without errors on the target host
- Check the agent service status:
systemctl status proxima-agent - Check agent logs:
journalctl -u proxima-agent -f - Ensure the host can reach the backend URL over HTTPS
- Verify NATS connectivity (port 4222 by default)
- Check firewall rules allow outbound connections on ports 443 and 4222
Token expired
Install tokens expire after 24 hours by default. Generate a new token from the wizard or via the API:
curl -X POST https://your-console.example.com/api/v1/clients/{slug}/install-tokens \
-H "Authorization: Bearer <your-jwt>" \
-H "Content-Type: application/json" \
-d '{"description": "manual token", "expires_in": 86400, "max_uses": 1}'
max_uses controls how many agents may enroll with the token: omit it (or pass 1) for a single-use token, a positive integer for a bounded count, or 0 for an unlimited (multi-fleet) token. expires_in is in seconds (max 2592000 = 30 days).
Permission denied
The installation wizard requires the hosts:write permission. Ask your administrator to assign a role with this permission to your account.
Security
All agent communication uses:
- Ed25519 signatures — each host gets a unique cryptographic keypair
- AES-256-GCM encryption — all data encrypted in transit
- Per-host NATS JWT isolation — each agent can only access its own data subjects
- TLS 1.2+ — all connections use modern TLS
See NATS Security Architecture for details.