Installation

Get started with the Pharos ecosystem using our frictionless automated installer.

Pharos is designed for “60-second success.” Our automated installer detects your environment and sets up the requested component with minimal friction.

🚀 The One-Liner (Recommended)

Run the following command on your target machine (Ubuntu, Debian, macOS, or WSL):

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- [hub|node]

Replace [hub|node] with the appropriate role for your machine:

  • hub: (Recommended for your main server) Installs the Pharos Server, Web Console, and Scan Engine.
  • node: (Recommended for managed nodes) Installs the Pulse Agent, mdb, and ph CLI tools.

🛠️ Role Selection

🏠 Home Lab: The “All-in-One” Hub

Most Home Labbers want a single “Hub” that hosts the server and manages the network, while existing and future nodes run the lightweight “Node” bundle.

1. Set Up The Hub (Main Server)

Run this on your primary Ubuntu/Debian host (e.g., a Proxmox LXC):

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- hub

Reachable at a real domain instead of just a LAN IP? Pass it as a second argument to include it in the server’s certificate:

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- hub pharos-01.example.com

2. Set Up Nodes (Managed Machines)

Run this on every machine or container you want Pharos to track, passing your hub’s address as the second argument:

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- node 192.168.1.5

Copy the hub’s CA certificate first

The hub’s TLS certificate is signed by a private, self-signed CA — the node needs to trust it before pulse can report in, or you’ll see TLS handshake failed: UnknownIssuer in journalctl -u pharos-pulse. The installer’s own “Next Steps” output tells you whether this step is needed — skip it if it already found a local CA (e.g. this node is also a hub).

This is a one-time copy, not a live sync: if the hub’s CA is ever regenerated later, remote nodes won’t pick up the change automatically and this step will need repeating.

# From the node — copy the hub's CA cert over SSH (adjust user@host for your setup):
sudo mkdir -p /etc/pharos/certs
scp youruser@192.168.1.5:/etc/pharos/certs/pharos-ca.crt /tmp/hub-ca.crt
sudo mv /tmp/hub-ca.crt /etc/pharos/certs/hub-ca.crt

# Point pulse at it — inserted into [Service], not appended to the end of the file,
# since a plain append would land after [Install] and be silently ignored:
sudo sed -i '/Environment=PHAROS_SERVER=/a Environment=PHAROS_CA_CERT=/etc/pharos/certs/hub-ca.crt' /etc/systemd/system/pharos-pulse.service
sudo systemctl daemon-reload
sudo systemctl restart pharos-pulse

Prefer this automated instead of copying files by hand? Append --fetch-ca-ssh <user@host> to the node install command itself — it pulls the hub’s CA over SSH and configures pulse to trust it, and (if this run just generated a fresh signing key) enrolls that key’s public half on the same hub over the same SSH connection, replacing everything in the box above plus the manual key-enrollment step that would otherwise follow it:

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- node 192.168.1.5 --fetch-ca-ssh youruser@192.168.1.5

🔍 Optional: Unattended Network Discovery

Want Pharos to automatically discover devices that don’t run pharos-pulse — switches, IoT gear, anything with no agent? Install pharos-scan with its own recurring systemd timer:

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- scan-auto 192.168.1.5

This is a standalone, opt-in target — it doesn’t come bundled with hub or any other role, so install it explicitly wherever you want the scanning to run. See Network Scan for what the resulting cycle actually does.

📋 Prerequisites

RequirementSupported Versions
OSUbuntu 22.04+, Debian 12+, macOS (Apple Silicon), WSL2
ArchLinux: x86_64 & aarch64 (full support). macOS: Apple Silicon (aarch64) client-only (ph/mdb only). Intel Macs: unsupported (build from source).
Dependenciescurl, tar (Automatically checked)

🔍 Post-Installation Checklist

After running the installer, verify your setup:

  • Server: sudo systemctl status pharos-server should be active (running).
  • Security tier: hub/server installs default to open (unauthenticated reads, writes always need a key) — the installer’s own “Next Steps” output states this, or check with systemctl cat pharos-server. See Server Setup before exposing the server beyond a trusted local network.
  • Pulse: sudo systemctl status pharos-pulse should be active (running).
  • Agent-Native Control Plane: The Web Console ships as a container image and isn’t started automatically by hub — run it separately (see Server Setup), then access https://your-server-ip:3000.
  • CLIs: Run mdb status to verify CLI path injection.

🛑 Manual Installation

If your environment is air-gapped or restricted, you can download the binaries directly from our GitHub Releases.

  1. Download the binary for your OS/Arch (e.g. pharos-server-linux-x86_64) — these are plain executables, not archives.
  2. chmod +x it and move it to /usr/local/bin.
  3. (Optional) Configure systemd services manually as described in Server Setup.