v1.0.3 Ships with the agent · no extra install · offline-safe

HostAtlas - the agent's sidekick, on the host itself.

A small CLI that lives next to the agent on each server. Run recipes locally, manage services, view what the platform thinks of this host — all without a round-trip to your laptop. For the moments when you SSH in and just want to do something.

$ hostatlas status copy

Installed automatically when you enrol an agent. Get the agent → /tools/agent.

verb groups

extra install steps

offline

runs without the platform

root@web-prod-04 · ssh session

root@web-prod-04:~# hostatlas status
host web-prod-04 · ubuntu 22.04 · eu-fra · prod
platform view healthy · last sync 1.1s ago
uptime 23d 4h 12m
services 47 running · 1 failed (clamav-freshclam.service)
open alerts 1 warning · disk pressure on /var (78%)

root@web-prod-04:~# hostatlas recipe restart-php-fpm
→ resolving recipe… ok · 4 steps · audit-id e8f3a2c1
● systemctl reload nginx
● systemctl restart php8.4-fpm
● wait for socket /run/php/php8.4-fpm.sock
● curl -fsS http://localhost/health · 200 OK
→ ran in 1.4s · logged to platform

root@web-prod-04:~# hostatlas alerts ack 3f9c
→ acknowledged · audit ok · visible in dashboard _

— Why a CLI on the host

Some things are easier from the box itself.

The laptop CLI is for orchestrating across the fleet. The Server CLI is for the moments after ssh user@server, when typing one more command is faster than switching context.

ssh-in flows

You're going to SSH in for the rare debug anyway. Why pop back to the laptop CLI to run a recipe when the same verb is right here?

offline-safe

Recipes execute locally against the agent. Status output is the last cached platform view. The Server CLI keeps working while you fix the connectivity that broke upstream.

lower-trust path

A host with multiple operators can let each run local recipes without giving them a platform-wide API token. Permissions are tied to the local agent's scope.

— What it does

Six verbs, scoped to this host.

Same nouns and verbs as the laptop CLI where they overlap. If you can spell hostatlas service restart nginx, you can probably guess the rest.

hostatlas status

What the platform thinks of this host: uptime, services, recent alerts, cached metric peaks. The summary you wanted before you opened htop.

hostatlas recipe

Run any recipe scoped to this host. Same playbook library you have on the platform, audit-logged the same way, no laptop round-trip.

hostatlas service

Shorthand for systemctl restart … + the audit-log entry that proves you did it. Same syntax for nginx, php-fpm, postgres, custom units.

hostatlas alerts

See what's open for this host. hostatlas ack <id> acknowledges in place. No flipping back to the dashboard mid-incident.

hostatlas logs

Tail the same auto-discovered log sources the platform viewer shows — journald units, nginx access/error, php-fpm slow, application logs — server-side filtered.

hostatlas agent

agent restart, agent version, agent diag — talks to the local agent directly. Useful when the agent itself is the thing you're debugging.

— Reference

The verbs, expanded.

Every command has hostatlas <cmd> --help; this is the shareable version.

hostatlas status

Show the platform's current view of this host: uptime, services, open alerts, cached metric peaks, agent health.

Synopsis

$ hostatlas status [--services] [--metrics] [-o table|json|yaml]

Flags

--services

Include the full service list with their plugin metrics.

--metrics

Include the cached CPU/RAM/Disk peak values from the last interval.

-o, --output

Output format: table (default), json, yaml. JSON is the format you'd pipe to jq.

Examples

# Default snapshot
$ hostatlas status

# Full snapshot, pipe-friendly
$ hostatlas status --services -o json | jq .services[].name

hostatlas alerts

List alert events currently open on this host. Acknowledge or resolve in place — same audit trail the platform writes.

Synopsis

$ hostatlas alerts [list|ack|resolve] [<id>] [--severity <s>]

Flags

list (default)

Open events for this host.

ack <id>

Acknowledge an alert. Stops re-paging without resolving the underlying condition.

resolve <id>

Force-resolve. Rule keeps evaluating; will re-fire if the condition still holds.

--severity <s>

Filter: critical / warning / info.

Examples

# What's open right now
$ hostatlas alerts

# Ack everything critical, AI keeps watching
$ hostatlas alerts list --severity critical -o ids | xargs -L1 hostatlas alerts ack

hostatlas logs

Tail the same auto-discovered log sources the platform shows: journald units, web-server access/error, slow-query logs, application paths.

Synopsis

$ hostatlas logs <source> [--grep <pattern>] [--since <dur>] [-f]

Flags

A service name (nginx, php-fpm, postgres) or one of the auto-discovered application log paths.

--grep <pattern>

Server-side regex filter — applied before lines hit the terminal.

--since <duration>

Start point: 5m, 1h, 24h. Default tails live.

-f, --follow

Keep following after backfill.

Examples

# Live tail nginx 5xx
$ hostatlas logs nginx --grep "5\d\d " -f

# Last hour of slow queries
$ hostatlas logs mysql.slow --since 1h

hostatlas recipe

Run a recipe scoped to this host. Reads the same playbook library as the platform; every step is audit-logged.

Synopsis

$ hostatlas recipe <key> [--input <k=v>] [--dry-run] [-w]

Flags

<key>

Recipe slug from the platform library, or a local path to a YAML file.

--input <k=v>

Input variable. Repeatable.

--dry-run

Print the plan, run no commands. Useful for change-management review.

-w, --watch

Stream step output as the recipe runs (default).

Examples

# Run the standard php-fpm restart recipe
$ hostatlas recipe restart-php-fpm

# Run a parameterised recipe
$ hostatlas recipe rotate-secret --input service=billing

# Preview only
$ hostatlas recipe full-backup-now --dry-run

hostatlas service

systemctl + audit-log in one verb. Same syntax for any unit on the host.

Synopsis

$ hostatlas service <action> <name> [--reason <text>]

Flags

One of: start, stop, restart, reload, status.

<name>

Unit name (nginx, php8.4-fpm, postgresql) — tab-completes from active units.

--reason <text>

Free-text reason recorded with the audit entry. Encouraged for restarts in prod.

Examples

# Restart nginx with a reason for the audit log
$ hostatlas service restart nginx --reason "config reload after vhost edit"

# Quick status check
$ hostatlas service status postgresql

hostatlas agent

Talk to the local agent process itself. Restart, version-check, diagnostic snapshot, force a re-discovery.

Synopsis

$ hostatlas agent <subcommand> [--json]

Flags

restart

Restart the local agent. Same as `systemctl restart hostatlas-agent` plus an audit entry.

version

Print the running agent version + latest available.

diag

Dump a structured diagnostic snapshot — config, last error, dial-out state, plugin attachment status.

discover

Force an immediate re-discovery pass. Normally happens on a schedule.

--json

Machine-readable output for any of the above.

Examples

# Quick health check
$ hostatlas agent version && hostatlas agent diag

# After installing a new service
$ hostatlas agent discover

— Honest answers

Questions that come up the first time you use it.

Does it need internet?

No. It runs against the local agent. Status output reflects the last platform state the agent cached — out-of-date messaging if the agent can't reach upstream right now.

What about credentials?

Permissions inherit from the local agent. A non-root user can run read-only commands; writes go through the same polkit policy the agent uses for service control.

How is it different from the laptop CLI?

The laptop CLI is multi-host and talks to the platform. The Server CLI is single-host and talks to the local agent. The verbs feel similar on purpose — same mental model, different blast radius.

Can I script with it?

Yes. -o json on every command, exit codes follow Unix conventions, recipes return their structured result on stdout. Designed for cron and ad-hoc shell scripts.

Where does it install?

It doesn't — it ships inside the agent binary. After agent install, hostatlas is on your PATH. No second package, no second update channel.

Discovery & Mapping

For developers

HostAtlas - the agent's sidekick, on the host itself.

Some things are easier from the box itself.

Six verbs, scoped to this host.

The verbs, expanded.

Questions that come up the first time you use it.

Does it need internet?

What about credentials?

How is it different from the laptop CLI?

Can I script with it?

Where does it install?

Connected capabilities.

Already installed if your agent is.