Quickstart

Goal: in about 10 minutes you will have…

The full Ongrid stack running on a single Linux box via docker compose (manager + frontier broker + Prometheus + Loki + Tempo + Grafana + Qdrant + SearXNG).
The admin user logged in over HTTPS.
One ongrid-edge registered against your manager, shipping CPU / memory / disk metrics that you can see on the Monitor page.

If you want a deeper walk-through, read Server install and Edge install instead.

0. Prerequisites

One Linux box (Ubuntu 22.04+, Debian 12+, RHEL/Rocky/Alma 9+ tested).

4 GB RAM minimum (8 GB recommended)
20 GB free disk under /var/lib/ongrid (the data dir)
root or sudo
docker ≥ 24 with the docker compose v2 subcommand
openssl (used to mint the self-signed TLS cert on first boot)
TCP 443 and 40012 open to the hosts where your edges will run

For local-only testing

You can run everything on a laptop. Just keep in mind that ONGRID_PUBLIC_URL defaults to the laptop's LAN IP, so any edge you install on another machine has to be able to reach that LAN IP on TCP/443.

1. Install the server

The canonical install path is gh release download plus sudo ./install.sh. The tarball is self-contained — docker images, edge binaries, config files, all bundled.

bash

# Pick the latest tag from https://github.com/ongridio/ongrid/releases
VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

What install.sh does, in order:

Preflight. Verifies docker + docker compose v2 are present and the daemon is reachable.
Stages config under /opt/ongrid/ (compose file, prometheus, loki, tempo, grafana, searxng, edge artifacts).
Creates data dirs under /var/lib/ongrid/ (mysql, prometheus, loki, tempo, qdrant, grafana, embeddings) and chowns them to the uid each container image expects. Logs go to /var/log/ongrid/.
Generates a self-signed TLS cert in /opt/ongrid/certs/ — browsers will warn the first time. Replace with a real cert later; see Server install.
Loads docker images (ongrid, ongrid-web, frontier) from the tarball — no Docker Hub pull required.
Fills .env with strong random passwords for MYSQL_*, ONGRID_JWT_SECRET, GRAFANA_ADMIN_PASSWORD, and the bootstrap ONGRID_ADMIN_PASSWORD.
Prompts for ONGRID_PUBLIC_URL with a 30-second countdown. This is the URL your edges will use to reach this manager's data plane (logs → Loki, traces → OTLP push). On an interactive terminal a wrong value here is the #1 cause of "only the manager-host edge ships logs", so confirm it. See ONGRID_PUBLIC_URL.
Runs docker compose up -d and polls https://localhost/healthz for up to 60 seconds.
Prints a banner with the Web URL, API URL, tunnel endpoint, and the bootstrap admin password — recorded once.

A healthy install ends like this:

text

[INFO] ongrid is healthy (took ~14s)

===============================================================
  ongrid installation complete
===============================================================

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

Record the admin password

The bootstrap password is shown once in the install banner and is also stored (chmod 600) in /opt/ongrid/.env as ONGRID_ADMIN_PASSWORD. If you lose both you'll need to reset it from the database; see first-boot checklist.

Open https://<your-host>/ in a browser. Accept the TLS warning (or install a real cert first). Sign in with:

email — whatever you put in .env as ONGRID_ADMIN_EMAIL (default admin@example.com)
password — the one from the install banner

On first login you land on the chat home page. The model picker in the top bar reads "no provider configured" — fix that before continuing.

3. Configure a model (1 min)

Go to Settings → Models. Pick any one of:

OpenAI — paste sk-…, default model gpt-5.4.
Anthropic — paste sk-ant-…, default claude-opus-4-7.
Zhipu (GLM) — paste API key, default glm-4.7.
DeepSeek, Gemini, Kimi, or Custom (OpenAI-compatible) for anything else (vLLM, Ollama, OpenRouter, a corporate relay…).

Press Save. The form pre-registers the provider — no restart needed. Then in the same page set Default provider to the one you just configured.

Why the default matters

The Default provider drives every back-end LLM call (alert investigation, translate, summarize). The model picker on the chat page only overrides for the current chat thread (see the Models section in the sidebar for routing details).

Walk back to Chat in the top nav and ask "hello". If the model replies, you're wired.

4. Register your first edge

Click Edges → New edge in the side nav. Fill in:

Name — anything; e.g. prod-web-01.
Description — optional.

Press Create. The detail page shows two things you need:

Access key / secret key — generated server-side; the secret is shown once.
Install command — a single line like:

bash

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=203.0.113.10:40012 \
    --server-http-addr=203.0.113.10:443

SSH to the host you want to monitor (it can be the same box you installed the manager on — that's a valid demo) and run that command as root.

What happens, in order:

The installer downloads the matching ongrid-edge-linux-amd64 binary, plus four plugin binaries (promtail, node_exporter, process_exporter, otelcol-contrib) and the apply-pending-upgrade.sh hook into /usr/local/lib/ongrid-edge/.
Creates the ongrid-edge system user, makes it a member of adm and systemd-journal so the logs plugin can read /var/log/* and the journal.
Drops a systemd unit at /etc/systemd/system/ongrid-edge.service.
Writes /etc/ongrid-edge/ongrid-edge.env with the access/secret key (mode 0640, owned root:ongrid-edge).
systemctl enable --now ongrid-edge. Polls the journal for the agent: registered with cloud line for up to 20s.
Prints a self-check (plugin binaries present? journald readable? data-plane host reachable?).

A successful registration ends with:

text

[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

5. See it in the UI

Back in the browser:

Edges — your edge is in the list with a green "online" dot. The card shows hostname, kernel version, total RAM, disk, distro.
Monitor — pick the edge. Within ~30 seconds you'll see CPU, memory, disk, load, network IO charts populating. They're Grafana panels embedded into the page via the /grafana/ sub-path.
Logs — pick the edge. Tail /var/log/* and the systemd journal live; LogQL supported in the search bar.
Topology — the edge appears as a host node. As you add more edges (or detect services via the expand_topology skill), the graph fills out.

6. Ask the agent

Go back to Chat. Try one of:

"List my edges and show me which has the highest load."
"Tail /var/log/syslog on prod-web-01 for the last 5 minutes."
"Why did CPU spike on prod-web-01 around 10:42?"

The agent calls real tools — list_edges, bash, query_promql, search_logs, find_topology_node, etc. The transcript shows each call as a collapsible chip; click one to see arguments and output.

What next?

Configure a channel so the agent can reply on Slack / Telegram / Larksuite / DingTalk / WeCom.
Author an alert rule — Ongrid ships 6 built-in host rules and 14 rule kinds across PromQL / log_match / log_volume / trace_latency / trace_error_rate.
Connect a knowledge base — the built-in vault is offline; add your own org playbooks (Markdown, PDF, DOCX) or sync a Git repo.
Production hardening — replace the self-signed TLS cert, set ONGRID_PUBLIC_URL to a real domain, back up /var/lib/ongrid, set up a real default_provider with a budget cap.

Uninstall

On the manager: cd ongrid-vX.Y.Z-linux-amd64 && sudo ./uninstall.sh. On an edge: curl -k -sSL https://<server>/install.sh | sudo bash -s -- --uninstall. Logs under /var/log/ongrid-edge are preserved.

Quickstart ​

0. Prerequisites ​

1. Install the server ​

2. Sign in ​

3. Configure a model (1 min) ​

4. Register your first edge ​

5. See it in the UI ​

6. Ask the agent ​

What next? ​