ongrid: the example environment file ships an admin password and a JWT placeholder

The example environment ships an admin password, a JWT secret and a DSN with credentials

The configuration template is where this project is least cautious, and the values in it are copy-paste ready.

[email protected]
ONGRID_ADMIN_PASSWORD=change-me-on-first-login

# JWT signing
ONGRID_JWT_SECRET=change-me-to-a-long-random-string
ONGRID_JWT_ACCESS_TTL=15m
ONGRID_JWT_REFRESH_TTL=168h

The admin account is seeded on first startup if the email address is unused, which means the example values produce a working login. The comment offers the alternative: leave both empty and you get an empty users table, where nobody can log in until you set them and restart. Those are the only two states, a known password or no access.

The database line carries credentials too:

ONGRID_DB_DIALECT=mysql
ONGRID_DB_DSN=ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local

The user and password are both `ongrid`. SQLite is offered as an opt-in for single-user local development rather than as the default.

The token lifetimes are also worth a decision rather than an acceptance. A 15 minute access token is conventional; the refresh token is 168 hours, which is seven days, and that is the window in which a leaked refresh token stays usable.

None of this is hidden. The file is a template with names that say change me. It is simply the first file anyone copies, and the passwords in it are the ones that end up in a real deployment when nobody reads the comments.

The Prometheus flag ships true while its own comment says to leave it false

One line in the template contradicts the three above it.

ONGRID_PROM_ENABLED=true
ONGRID_PROM_URL=http://prometheus:9090/prometheus

The comment attached to it explains that when the flag is true the manager forwards `push_prom_samples` to remote_write and the agent gains a `query_promql` tool, then instructs the reader to leave it false until a Prometheus container is actually deployed.

So the default enables a feature whose prerequisite the same comment says is not yet there. The shipped value and the shipped advice point in opposite directions.

In practice the failure is quiet rather than fatal: the manager holds a URL for a Prometheus that may not exist in the compose topology, and forwarding samples to nothing produces no error anyone would notice during a first install.

The rest of the port configuration is better behaved. The in-container addresses are 8080 for HTTP and 9100 for metrics, and nginx fronts them on the host with 443 for HTTPS and 80 for a redirect, with `ONGRID_HTTP_REDIRECT_PORT=0` documented as the way to turn the redirect off. Each of those lines cites the architecture decision record it came from, so the reasoning is traceable even where the default is debatable.

The Frontier broker address follows the same pattern, defaulting to `frontier:40011` in compose and to localhost for the make target, with the comment naming which to use where.

Zero inbound ports rests on a third-party broker pinned to one version

The headline security property is that nothing on your hosts listens. No port 22, no 80, no 443, because the edge agent dials out. Browser SSH then rides on that same outbound path as a reverse tunnel, with no keys and no jumpbox, and every call audited.

That design depends on a component this project does not own. The environment file names it as the Frontier broker, citing the upstream `singchia/frontier` and an architecture decision record. The manager dials the broker's service-bound port 40011 and registers itself under the service name `ongrid-manager`.

The build file pins it:

FRONTIER_VERSION ?= 1.2.6
FRONTIER_SOURCE_IMAGES ?= docker.io/singchia/frontier:$(FRONTIER_VERSION)
FRONTIER_MIRROR_IMAGE ?= $(CLOUD_IMAGE_REPO)/frontier:$(FRONTIER_VERSION)

One version, with a mirror path of the same version held alongside the upstream image. And the Go client library is a different maturity level: the module list carries `github.com/singchia/geminio v1.3.0-rc.2`, a release candidate rather than a stable tag.

That is a reasonable dependency for a communication primitive, and it is also the single component whose failure mode is hardest to reason about, since every host's connectivity depends on it. If you deploy this, know which version of the broker you are running and where its mirror lives.

The other side of the property is worth stating plainly: the reverse tunnel is a shell into your hosts, so the audit log and the approval gate are what stand between it and production.

Every documentation link points at the hosted site

The documentation table is thorough and completely external. Get started, install and operate, capabilities, agents and reference each resolve to ongrid.cloud URLs, and the product tour sections describe features whose detail lives in the same place.

So there are two documentation surfaces: the repository, which contains a `docs/` directory, and the site, which is what the README actually links to. Nothing in the table points into the repository copy.

That matters for the deployment this project is designed for. Ongrid is an operations agent, and operations agents tend to run in environments where an external URL is unreachable or slow, which is precisely why a Mainland China CDN mirror is provided for the release archives. The same reasoning would apply to the documentation, and it is not extended there.

The repository does carry substantial prose of its own. There are nine README files, one per language, and two roadmaps, one of them in Simplified Chinese. There is a `SECURITY.md`, a `TRADEMARK.md` alongside the AGPL licence, an `AGENTS.md`, a `CHANGELOG.md` and a `VERSION` file.

Installation, by contrast, is fully self-contained, with a wget, an extract and a `sudo ./install.sh`, pinned to the exact version in the URL, for two architectures and a mirror path for each:

wget https://github.com/ongridio/ongrid/releases/download/v0.17.6/ongrid-v0.17.6-linux-amd64.tar.xz
tar -xf ongrid-v0.17.6-linux-amd64.tar.xz && cd ongrid-v0.17.6-linux-amd64
sudo ./install.sh

A bash sandbox and browser SSH arrive together, and the write gate is the boundary

The host tooling is described in one line with a lot inside it: a bash sandbox, more than 26 inspection tools, and every call audited.

Alongside that there is a browser SSH that reverse-tunnels a shell into any host. The module list includes a pseudo-terminal library, so sessions get a real terminal rather than a pipe.

Neither capability is restricted by itself. What separates read from write is a separate feature, the approval and write gate, described as keeping risky actions behind approvals with a visible policy boundary before anything changes a production system.

So the security model has three layers rather than two: audited read tools available broadly, a shell available for interactive work, and a gate in front of changes. Authorization underneath is handled by Casbin, with both the core library and the GORM adapter in the module list, which is a policy engine rather than hard-coded roles.

Two other capability claims carry weight in the same way. Root-cause analysis is described as walking topology, correlating metrics, logs and traces, and pinning the why to a source-code line. Network device management discovers neighbours from edge hosts, verifies them over SNMP, polls interfaces, and maps links between hosts and devices, which extends the topology past servers.

Kubernetes lifecycle arrived later, enrolling clusters through the edge, inspecting workloads and events, managing upgrades, and mirroring cluster resources into topology. The agent roster is a coordinator dispatching to SRE, network and database specialists, plus an incident investigator that spawns a root-cause worker and writes the cause back into the chat thread where the alert came from.

The Makefile declares itself the only build entry point, in Chinese

The first two lines of the build file are a policy statement, and they are not in English.

# ongrid Makefile — 唯一构建/测试/部署入口（gospec 红线）
# 所有 CI / Dockerfile / README 都应只调 make target，禁裸 go build / docker build。

It says this is the only build, test and deployment entry point, that it is a gospec red line, and that CI, the Dockerfiles and the README should all call make targets with bare `go build` or `docker build` forbidden.

Everything around it is English, including the variable names, the inline comments explaining the packaging decisions, and the README that the policy claims to govern. So the instruction that every contributor must follow is the one part a non-Chinese-reading contributor cannot read.

The same split appears elsewhere in the tree: `ROADMAP.md` and `ROADMAP.zh-CN.md` sit side by side, and nine README translations exist while the policy files stay in one language.

The architecture logic inside the file is worth reading because it explains the download URLs you will use:

TARGET_OS   ?= linux
TARGET_ARCH ?= amd64
PLATFORM    ?= $(TARGET_OS)/$(TARGET_ARCH)
PACKAGE_EDGE_TARGETS ?= linux-amd64 linux-arm64

Set `PLATFORM` from the environment or the command line and it is split on the slash into the two targets. Otherwise it defaults to linux on amd64. Manager packages stay architecture-specific for compatibility with existing URLs and upgrade clients, while every production package caches both edge architectures so a mixed fleet can be upgraded, with device dispatch selecting the matching one at install time.

Three pseudo-versions and a test-only module sit in the production require block

The module requires Go 1.25.0 and about thirty direct dependencies. Four entries are worth pulling out.

Two document splitters are pinned to pseudo-versions on the same commit:

	github.com/cloudwego/eino-ext/components/document/transformer/splitter/markdown v0.0.0-20260724103301-c9a5dc923462
	github.com/cloudwego/eino-ext/components/document/transformer/splitter/recursive v0.0.0-20260724103301-c9a5dc923462

A pseudo-version means no tagged release was used, so those two will not move to a newer tag without a deliberate edit, and they will not receive a patch automatically. A third pseudo-version, on a PDF parsing library, is pinned the same way.

The fourth is a testcontainers MySQL module sitting in the same require block. Go does not separate test dependencies, so this is expected placement rather than a mistake, but it does mean a test harness ships in the module graph of a production binary.

The rest of the list tells you what the product does. Prometheus client libraries and OpenTelemetry SDK, metric and trace exporters cover the observability side. WebSocket and a pty library cover live terminals. gosnmp covers network devices. Lark and DingTalk SDKs match the chat channels. A SQLite driver and a cron library cover storage and scheduling. Casbin and JWT cover authorization and sessions.

Model routing is bring-your-own: Anthropic, OpenAI, GLM, DeepSeek, Gemini and Kimi, with hot routing between them and the OpenAI-compatible client in the module list.

Editorial conclusion

ongrid is built for a team that already runs Prometheus, Loki and Tempo and wants an agent to correlate them against a topology rather than another dashboard. The architecture choice worth borrowing is the edge model, where every host dials out and nothing listens inbound, which also gives you browser SSH without keys or a jumpbox. Three things to check before you point it at production. The example environment file contains a working admin password and a JWT secret placeholder, and there are exactly two safe configurations: change both or set them empty and accept that nobody can log in. The Prometheus flag ships true while its own comment says to leave it false. And the zero-inbound-ports property depends on a third-party broker pinned to one version, so that is the component to watch when something stops connecting.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. ongridio/ongrid on GitHub
3. Project website
4. README
5. Releases