Install the agent
Copies this page as Markdown with context, so an AI can walk you through your case step by step.
A C++20 metrics collector and a Python backup daemon, running as a system service. Under 10 MB of RAM.
Requirements
- Linux x86_64 or arm64 with systemd (Ubuntu 20.04+, Debian 11+, RHEL/Alma/Rocky 8+), or Windows Server 2019+ / Windows 10 and 11.
- Python 3.11 or later (
python3 --version). On Ubuntu 22.04 or earlier:sudo apt install python3.11 python3.11-venv. On Windows:winget install Python.Python.3.13. - Optional:
g++10 or later. If present, the installer builds the native C++20 collector; otherwise it uses the Python collector (same features, slightly higher footprint). - Outbound HTTPS (port 443) to
ganyant.comand*.r2.cloudflarestorage.com. No inbound ports need to be opened. - Administrator access (
sudoon Linux, PowerShell as administrator on Windows).
1. Generate an API key
In the dashboard, Servers → Generate API key. The key starts with gyk_, is shown only once and we only store its SHA-256 hash. The same key works for several servers in the workspace.
2. Install
Linux
curl -fsSL https://ganyant.com/install.sh | sudo GANYANT_KEY=gyk_… shThe installer:
- Creates the
ganyantsystem user (no shell) and adds it to theadmandsystemd-journalgroups so it can read SSH login attempts. - Downloads the agent to
/opt/ganyantand installs its dependencies in an isolated virtual environment (it does not touch the system Python). - Builds the native collector if
g++is available. - Writes
/etc/ganyant/agent.tomlwith mode 600 and a random encryption passphrase (if the file already exists, it is left untouched). - Registers and starts the
ganyant-agentsystemd service, and checks that it is active.
Windows
In PowerShell as administrator:
$env:GANYANT_KEY="gyk_…"; irm https://ganyant.com/install.ps1 | iexIt installs the agent in C:\Program Files\ganyant, the configuration in C:\ProgramData\ganyant\agent.toml (readable only by SYSTEM and Administrators) and registers a ganyant-agent scheduled task that runs as SYSTEM at startup and restarts itself if it stops.
Installer options
| Variable | Purpose |
|---|---|
GANYANT_KEY | Required. The workspace API key. |
GANYANT_NO_NATIVE=1 | Linux only. Skips building the C++ collector and uses the Python one, even if g++ is installed. Useful on servers where you do not want to compile anything, or if the native binary gives you trouble. |
curl -fsSL https://ganyant.com/install.sh | sudo GANYANT_KEY=gyk_… GANYANT_NO_NATIVE=1 sh3. Check that it is running
Within a few seconds the server shows up in Servers as online. To confirm it from the machine:
Linux
# service status: it should say "active (running)"
systemctl status ganyant-agent
# live logs (Ctrl+C to exit)
journalctl -u ganyant-agent -f
# last 50 lines, for example after an error
journalctl -u ganyant-agent -n 50 --no-pagerOn startup the agent logs a line like this one, which also tells you which collector it uses:
2026-11-15 18:02:11 ganyant-agent 1.0.0 · registrado como web-01 (modo full) · recolector nativo C++20(The agent logs in Spanish: registrado como = registered as, recolector nativo = native collector.) The mode is full if your plan includes live telemetry (Pro and Agency) or backup if it only runs backups (Starter).
Windows
# task state: it should say "Running"
Get-ScheduledTask ganyant-agent | Select-Object TaskName, State
Get-ScheduledTaskInfo ganyant-agent # last start and result
# live logs
Get-Content 'C:\ProgramData\ganyant\agent.log' -Tail 50 -WaitYou can also see it in Task Scheduler (taskschd.msc) → Library → ganyant-agent. The agent does not appear in services.msc because it runs as a scheduled task, not a service.
4. Set up backups
What to back up, how often and how long to keep it are chosen in Dashboard → Backups. On the server you only define how to reach the data, in a section named like the job. Credentials and the encryption passphrase never leave the server. Details per database in Backups and restore.
# /etc/ganyant/agent.toml
[vault]
passphrase = "the-passphrase-the-installer-generated"
[backup.shop_prod] # PostgreSQL job named shop_prod
dsn = "postgresql://backup@127.0.0.1:5432/shop_prod"
[backup.uploads] # Folder job named uploads
path = "/var/www/uploads"The daemon reads the file at startup, so restart it after editing. To test a job right away (this command does read the current file):
sudo systemctl restart ganyant-agent
sudo ganyant-agent backup shop_prod --manualOn Windows, to restart: Stop-ScheduledTask ganyant-agent; Start-ScheduledTask ganyant-agent.
Passphrase in an environment variable
If you prefer not to keep the passphrase in the file, use passphrase = "env:GANYANT_VAULT_PASSPHRASE" and define the variable for the service:
sudo systemctl edit ganyant-agent
# in the editor that opens, add:
[Service]
Environment=GANYANT_VAULT_PASSPHRASE=your-passphrase
# save and restart
sudo systemctl restart ganyant-agentThe env: prefix works for any value in agent.toml (for example dsn or uri).
Commands
| Command | What it does |
|---|---|
ganyant-agent run | Starts the daemon. The service uses it; you do not need to run it by hand. |
ganyant-agent backup <job> --manual | Runs a backup now, without waiting for the schedule. |
ganyant-agent restore <job> --at latest --to <file> | Downloads, verifies and decrypts a snapshot. --at accepts latest or a date such as "2026-11-14 03:00". |
ganyant-agent decrypt <file.gya> --out <file> | Decrypts a snapshot downloaded from the dashboard. It asks for the passphrase. |
ganyant-agent version | Shows the installed version. |
On Linux run them with sudo, because agent.toml is only readable by root and the ganyant user. On Windows, from PowerShell as administrator: & 'C:\Program Files\ganyant\venv\Scripts\python.exe' 'C:\Program Files\ganyant\ganyant_agent.py' version.
Restore
sudo ganyant-agent restore shop_prod --at latest --to ./shop_prod.dump
sudo ganyant-agent restore uploads --at "2026-11-14 03:00" --to ./uploads.tar--to is a file: folders are restored as a .tar. How to load each kind of dump in Backups → Restore.
What the agent detects
| Signal | Default threshold |
|---|---|
| Disk | Warning at 80%, critical at 90%, and a 7-day fill prediction |
| SSH brute force | 20 failures from one IP within 5 minutes (journald or /var/log/auth.log / /var/log/secure) |
| RDP brute force | 20 event 4625 entries from one IP within 5 minutes (Windows) |
| New listening port | Any public socket that was not in the previous inventory |
| Traffic anomaly | More than 4 standard deviations above the 1-hour moving average |
Live telemetry and intrusion detection require Pro or Agency; on Starter the agent only runs backups.
Update
Run the same install command again. It downloads the latest version, reinstalls dependencies and restarts the service. Your agent.toml (key, passphrase and jobs) is kept.
Files
| Linux | Windows | |
|---|---|---|
| Program | /opt/ganyant | C:\Program Files\ganyant |
| Configuration | /etc/ganyant/agent.toml | C:\ProgramData\ganyant\agent.toml |
| Logs | journalctl -u ganyant-agent | C:\ProgramData\ganyant\agent.log |
| Service | /etc/systemd/system/ganyant-agent.service | Scheduled task ganyant-agent |
Troubleshooting
| Symptom | What to check |
|---|---|
Se necesita Python 3.11 o superior (Python 3.11+ required) | Install Python 3.11+ and run the installer again. Check with python3 --version. |
GANYANT_KEY con formato inválido (invalid key format) | Copy the full key (gyk_ + 48 characters), with no extra spaces or quotes. |
| The service does not start | journalctl -u ganyant-agent -n 50 --no-pager shows the exact reason. |
401 in the logs | The key was revoked or belongs to another workspace. Generate a new one, edit key in agent.toml and run sudo systemctl restart ganyant-agent. |
| The server does not show up in the dashboard | Check outbound access: curl -sI https://ganyant.com/api/health should answer 200. |
| No SSH attempts are detected | The ganyant user must be in adm or systemd-journal: id ganyant. If you added it by hand, restart the service. |
A backup fails with pg_dump falló or similar | The dump tool is not installed or the user lacks permissions. See requirements per type. |
Uninstall
Linux
sudo systemctl disable --now ganyant-agent
sudo rm -rf /opt/ganyant /etc/ganyant /etc/systemd/system/ganyant-agent.service /usr/local/bin/ganyant-agent
sudo systemctl daemon-reload
sudo userdel ganyantWindows
Unregister-ScheduledTask -TaskName ganyant-agent -Confirm:$false
Remove-Item -Recurse -Force 'C:\Program Files\ganyant', 'C:\ProgramData\ganyant'Before deleting agent.toml, save the encryption passphrase if you will want to restore old snapshots. Then delete the server from the dashboard.