Installation and onboarding

Outcome

This procedure installs the signed argus host wrapper and creates a verified, managed Argus instance at /opt/argus. It is for a fresh VPS Docker host, not a workstation and not a manually maintained existing instance.

Prerequisites

The clean-host installer matrix covers Ubuntu 22.04 and 24.04 plus Debian 12 and 13, across Linux AMD64 and ARM64 where represented by the matrix. Release images are built for linux/amd64 and linux/arm64. Use x86_64/amd64 or aarch64/arm64, a sudo-capable account, outbound HTTPS, and at least 5 GiB free disk space. Onboarding checks Docker Engine, Docker Compose, daemon access, memory (at least 1 GiB, or 2 GiB with managed SearXNG), and the selected API port before it changes the instance.

Inspect the installer before it changes a host

Download the installer from the public distribution URL, inspect it, then run its no-change inspection mode:

curl -fsSLo /tmp/argus-install.sh https://argus.gpsxtre.me/install.sh
less /tmp/argus-install.sh
ARGUS_INSTALL_INSPECT=1 sh /tmp/argus-install.sh

The generated installer embeds the Ed25519 trust root. During installation it downloads manifest.json and manifest.sig, verifies the manifest signature before trusting its contents, validates the canonical manifest shape, then verifies the downloaded wrapper's SHA-256 hash. A failed signature, malformed manifest, or hash mismatch stops before the wrapper is replaced.

Install only after reviewing the report:

curl -fsSL https://argus.gpsxtre.me/install.sh | sh

Durable management launcher

The signed installer writes the strict /opt/argus/management.state file and installs one immutable /usr/local/bin/argus launcher. Later argus update commands advance the verified management state without replacing the launcher. The next release refuses legacy version-pinned wrappers; remove an obsolete launcher explicitly before installing it.

Do not edit management.state. A missing or malformed state makes the launcher fail closed before Docker starts. Rerun the signed installer to repair the launcher/state pair.

Docker-present and Docker-absent paths

With usable Docker Engine and the Compose plugin, the installer downloads and installs the verified wrapper. With Docker absent, an interactive run asks for approval before it installs Docker from Docker's official apt repository. For a non-interactive approved install, download the script first and run:

ARGUS_INSTALL_DOCKER=1 sh /tmp/argus-install.sh

Use ARGUS_INSTALL_DOCKER=0 when Docker installation is forbidden; in that case the installer reports a missing Docker dependency instead of installing it. It also refuses conflicting distribution Docker packages and stops if the daemon or Compose plugin is unavailable.

Interactive onboarding answers

Run interactive onboarding after the wrapper is installed:

argus onboard

The answer groups appear in this order:

• Storage and API always appear: SQLite (the default) or PostgreSQL, then the API port (default 8788).
• Sources and watch always appear: choose X, public Telegram announcements, and/or Web; then give the watch ID and cron schedule. The selected source receives only its relevant inputs: X accounts and queries, public Telegram channel names, or Web URLs, feeds, and queries.
• SearXNG appears only when at least one Web search query is entered. Choose a managed service or an external endpoint.
• FxEmbed appears only when X is selected. The default runs FxEmbed on the same VPS. It stays on Argus's private Compose network and publishes no host port. Cloudflare deployment and an external endpoint are advanced choices.
• Intelligence always appears as the OpenRouter summaries choice. When enabled, it asks for the model; when disabled, no OpenRouter secret is needed.
• Keywords always appear and become watch classification metadata.
• Secrets are hidden prompts: an Argus API token always; a PostgreSQL password for PostgreSQL storage; a Cloudflare API token only when Cloudflare FxEmbed is explicitly selected; and an OpenRouter API key for intelligence.

Telegram is limited to public channels. Do not enter private conversations or private channels. Managed SearXNG is meaningful only for Web query targets; direct URLs and feeds do not require it.

File-driven onboarding and secret handling

For repeatable non-secret choices, use a strict YAML answers file. It must use version 1, require /opt/argus as its root, match the current onboarding schema, and not be group- or world-writable. It must never include a secret field. Inspect the plan without mutation with:

argus onboard --from answers.yaml --dry-run --json

After reviewing that plan, run the file-driven apply from an interactive terminal so the CLI can collect any required hidden secrets. Use --yes only when you have already reviewed the current plan.

argus onboard --from answers.yaml

The generated secret file is /opt/argus/secrets.env. It is a regular, owner-owned 0600 file; Argus rejects symlinks, non-files, and unsafe modes. Secrets are referenced from generated configuration but are not written into the versioned YAML answers file or the applied configuration snapshot.

Managed files and safe repeatability

Onboarding manages these instance files:

• /usr/local/bin/argus — the verified host wrapper installed by the signed installer.
• /opt/argus/argus.yaml — generated runtime configuration, written after validation.
• /opt/argus/secrets.env — owner-only secret environment file.
• /opt/argus/compose.yaml — Argus-managed Docker Compose definition.
• /opt/argus/state.json — validated persisted deployment state.
• /opt/argus/searxng/settings.yml — present when managed SearXNG is selected.

Do not edit generated Compose settings or secret files to repair a deployment; use the CLI so it can inspect, apply, and verify a bounded plan. Re-running the installer verifies and replaces the wrapper atomically. Re-running onboarding re-inspects the host and desired state; a stale plan, failed validation, or failed verification stops with a stable error and recovery guidance rather than claiming a successful deployment.

Verify

After onboarding, inspect the managed services and diagnostics:

argus status --json
argus doctor --json

A successful JSON response has contractVersion: 1 and ok: true; doctor also reports whether every checked component is healthy. If Docker or the instance is unhealthy, follow the recovery command in argus doctor --json before retrying an operation.

Next step

Use the quick start to create and query the controlled Web watch, then read core concepts and configuration before changing production watches.