When it does not work

Start here:

nouride doctor

It checks the things that commonly stop a fresh install — a provider with no credential, an agent pack that did not load, a gateway stuck reconnecting, no agent enabled at all — and every finding says what to do about it. It exits non-zero on a real problem, so it also works inside a healthcheck.

What doctor checks, in full →

---

Install

What you see	What it usually is
unsupported architecture	32-bit ARM. You need a 64-bit OS — see Raspberry Pi
Binary “not found” on Alpine, and the file is right there	musl versus glibc, or a missing apk add libstdc++
macOS refuses to open the binary	Gatekeeper quarantine — xattr -dr com.apple.quarantine ~/nouride
download failed	No release at that URL yet. Build one and pass --tarball, or --repo to pull from GitHub releases
The install finished but nouride is not a command	The symlink went somewhere not on your PATH. Run it by full path: /srv/nouride/nouride status

Starting

The service starts and /health never answers. The daemon refused its config and exited after systemd reported success. systemctl start returning 0 means a process was spawned, not that it is serving.

sudo journalctl -u nouride -n 50 --no-pager

nouride status reports no daemon while one is clearly running. The CLI resolves the install relative to your working directory, so from /tmp it looks for /tmp/.nouride/data/.control-token. The error names the path it wanted, which is the fastest way to spot this. Run it from the install directory, or set NOURIDE_URL and NOURIDE_TOKEN.

nouride restart refuses. It works by asking the daemon to exit so its supervisor brings it back. With nothing supervising it, that is just a stop — so it returns a 409 instead of silently shutting you down. nouride service status says plainly whether anything would respawn it.

Reaching the dashboard

What you see	What it usually is
Unreachable from another machine	Bound to loopback by default. Re-run the installer with --host 0.0.0.0, or tunnel: ssh -L 18254:127.0.0.1:18254 you@host
Published Docker port reaches nothing	HOST=0.0.0.0 is missing. A container that binds loopback binds its own loopback
The page loads but every asset 404s	The dashboard/ directory is not beside the binary. They travel together — reinstall from the tarball rather than copying one file
Missed the first-run password	It is shown once and there is no reset. See first run — and set INITIAL_ADMIN_USERNAME / INITIAL_ADMIN_PASSWORD in .env before the first start so it cannot happen again

The agent does not answer

Nothing at all, on any surface. No agent is running. nouride agents lists what loaded and what state each is in; a pack that failed to parse is reported by nouride doctor with the error.

It answers in the dashboard but not in a chat app. Either the connection was saved but the daemon has not restarted — adapters are built at boot — or the sender has not been let in. Check nouride gateway for the connection and nouride access for the person.

It answers in a DM but ignores a group. On Telegram, privacy mode is on: /setprivacy → Disable in BotFather, or make the bot an admin. Otherwise groups_require_mention is doing what it says, and the agent is waiting to be addressed by name.

It replies “I cannot do that” to something it should be able to do. The tool is not on that agent’s list. nouride skills <agent> -v shows what it carries, and the agent’s [tools] enabled in .nouride/agents/<id>/config.toml is what grants it.

Every message fails with a model error. The provider profile has no credential, or the wrong one. nouride doctor names the profile; nouride secret lists which credential names exist, never their values.

Commands and files

A command is refused however it is spelled. The directory is not a workspace root for that agent. nouride doctor reports a declared root that does not exist — the case where everything else looks green while every path is rejected.

An agent asks for approval on something harmless, every single time. ask = "always" never remembers an answer. on-miss is the default and remembers per command. Check with:

nouride policy check rm -rf /tmp/build

That answers “would this be gated” without running anything, and it works while the daemon is down — which is exactly when somebody is debugging a refusal.

An agent will never stop asking about terraform apply. Infrastructure commands are a hardline class: they ask every time and can never become a standing grant. Their read halves — plan, get, describe, anything with --dry-run — are not gated at all.

Memory and load

The box gets tight during a build. Commands the agent spawns run at nice 10, and the generated systemd unit carries a soft MemoryHigh ceiling at 80% of what the machine reports. On Raspberry Pi OS the memory cgroup controller ships disabled, so systemd accepts that setting and enforces nothing:

systemctl show nouride -p MemoryCurrent --value   # `[not set]` means it is inert

Add cgroup_enable=memory cgroup_memory=1 to /boot/firmware/cmdline.txt and reboot.

Footprint and sizing →

Still stuck

nouride logs -n 200          # the daemon's own log — works with no journal, and remotely
nouride status               # agents, gateways, queue, on one screen
nouride config check         # validate the config without starting anything

nouride logs reads the log the daemon keeps itself, so it works on a machine with no journal and against a remote daemon over NOURIDE_URL.