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:

1. Platform Selection (/hosts/add) — Choose your deployment method (Linux, Docker, Kubernetes, etc.)
2. Installation Page (/hosts/add/linux or /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 run or 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 how this host enrolls. Every field shows its default as a placeholder; leave it blank to keep the default.

• Log Level — debug, info, warn, error (default: info)
• Console URL — the address the host reaches this console at. Defaults to the address you opened the console at.
• NATS URL — overrides, for this host only, the NATS URL the console hands out at enrollment (its PROXIMA_NATS_PUBLIC_URL), for a host that reaches NATS by another name or path. Written into the agent's unit as PROXIMA_NATS_URL.
• Installer URL (Linux) — where install-agent.sh is fetched from.
• Agent download base (Linux) — where the installer downloads the agent binary from.
• Agent image (Docker) — for a registry mirror.

A value that is not a well-formed URL (or image reference) is marked, and no command is shown until it is fixed.

Post-install configuration

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

note

Collector and auto-update settings are not install flags — they are applied after enrollment from the Agent Config page (see the post-install tip above).

Self-hosted installations

On a self-hosted (on-prem) installation the wizard prints the same command console-ctl bootstrap does, pointed at the installation itself rather than install.prxm.uz:

• the installer comes from https://<your-console>/install-agent.sh, and is piped into bash (run it as root);
• when the installation serves agent binaries at /releases/, the command adds --download-base https://<your-console>/releases, so the host needs no internet access;
• in private network mode (an internal CA), the command first fetches the CA from /ca.pem and checks it against the installation's fingerprint, and only then downloads the installer over that verified CA. It stops with ABORT if they differ. The fingerprint is also passed as --ca-fingerprint.

The Docker command on a private installation does the same check first and mounts the verified CA into the container.

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> \
  registry.prxm.uz/proxima/console/agent:latest

The Docker socket mount is not generated

The wizard emits no -v flags. If you want the agent's Docker collector to see containers on the host, add the socket mount yourself:

  -v /var/run/docker.sock:/var/run/docker.sock:ro \

A Docker Compose snippet is also available in a collapsible section on the Docker install page.

caution

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

1. Verify the install command completed without errors on the target host
2. Check the agent service status: systemctl status proxima-agent
3. Check agent logs: journalctl -u proxima-agent -f
4. Ensure the host can reach the backend URL over HTTPS
5. Verify NATS connectivity (port 4222 by default)
6. 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.

Related

• Agent Installation
• Agent Configuration
• System Requirements