ngent/noid.gg
Documentation

>NGENT_

A self-hosted NoidChat agent that lives on your machine. Two commands to get going: install it, then run ngent setup. Everything below is the reference.

01 Install

One line. It installs into ~/.ngent — $HOME-only, no sudo — and re-running it updates in place without clobbering your data.

$ curl -fsSL https://ngent.noid.gg/install.sh | bash

The installer fetches and checksum-verifies the code tarball (fail-closed — a mismatch refuses to install), builds an isolated venv, writes your config, scaffolds your agent, optionally pairs a NoidChat identity, and installs the daemon + the ngent command.

Requirements

  • python3 ≥ 3.10 — the runtime.
  • node — only needed to pair a NoidChat bot (skip it with --skip-pair for terminal-only).
  • curl — to fetch the installer + code.
  • uv (preferred, self-contained) or your distro's python3-venv — to build the virtualenv. The installer uses uv if present and falls back to stdlib venv.

Flags

Append flags by piping into bash -s --:

$ curl -fsSL https://ngent.noid.gg/install.sh | bash -s -- --terminal-only
--terminal-onlyInstall just the local ngent command — no NoidChat pairing, no daemon. (Equivalent to --skip-pair --skip-service.)
--skip-pairDon't pair a NoidChat account. The ngent terminal still installs; node is no longer required.
--skip-serviceDon't install the always-on systemd daemon. (Auto-applied when no systemd --user session is detected — see Troubleshooting.)
You can set OPENROUTER_API_KEY in the environment before installing to skip the interactive key prompt. NGENT_HOME overrides the install dir.

02 ngent setup

The configure step. After installing, run:

$ ngent setup

The wizard walks you through four things, in order:

  1. OpenRouter key. Paste your sk-or-… key. It's the only credential you bring — written to ~/.ngent/.env (chmod 600) and never leaves your machine.
  2. Choose a model. Pick from the registry or type any OpenRouter model id. The choice is written to config.yaml → oracle.model.
  3. Pair your NoidChat bot. A QR appears — scan it with the NoidChat app and approve the request. Your bot gets its own identity, saved locally so it stays paired.
  4. Enable auto-boot. Setup enables and starts the daemon, so the bot comes online now and on every reboot.
Re-run ngent setup any time to re-pair, change the key, or switch models. It never clobbers data it doesn't need to touch.

03 Models

NGENT talks to its model through OpenRouter — so any model OpenRouter serves (DeepSeek, Claude, GPT, and more) is one id away. Your key is the only credential, and switching models needs no reinstall.

Set the model

  • In ngent setup — pick from the registry or type any OpenRouter id.
  • From the NoidChat picker — selecting a model in chat rewrites config.yaml → oracle.model.
  • By hand — edit ~/.ngent/config.yaml:
oracle:
  provider: openrouter
  model: deepseek/deepseek-v4-pro      # ← any OpenRouter model id
  base_url: https://openrouter.ai/api/v1

The model registry

The NoidChat model picker reads ~/.ngent/models.md. One model per line: <openrouter-id> | <window> | <note>. A line starting with # is inactive (hidden from the picker); the running model is the active line matching config.yaml (marked ★). Default ships as:

deepseek/deepseek-v4-pro | 1.05M | ★ running — long window, strong reasoning, low cost

Uncomment a line to offer it (verify the id on OpenRouter first). Pre-listed siblings include deepseek/deepseek-v4, anthropic/claude-opus-4.8, anthropic/claude-sonnet-4.6, anthropic/claude-haiku-4.5, and openai/gpt-5.1.

04 Two modes

Same agent, two front doors. Run it as an always-on resident you DM, drop into it live in your terminal, or both.

Mode A — the daemon

A systemd --user service that auto-starts on boot and auto-restarts on crash. It signs into NoidChat as your bot — just message it. loginctl enable-linger keeps it running across logout.

$ systemctl --user status ngent     # is it up?
$ systemctl --user restart ngent    # bounce it

Mode B — the ngent terminal command

Type ngent anywhere for an interactive agent that operates in the folder you launched it from — full tool access, immediate feedback. No daemon required; it's always installed even with --terminal-only.

$ ngent          # interactive session in the current folder
Zero-dependency fallback for watching the daemon: bash ~/.ngent/status.sh --watch.

05 Skills & Combos

Skills are atomic abilities — one thing each (download-video, transcribe, echo-brief). Combos chain Skills into one move — e.g. video-to-transcription = download → extract → transcribe. Both live under Inventory/Abilities/ and are discovered together (the bot's use_skill and /skills see everything).

How a skill graduates

Skills aren't born finished. The moment the bot does something repeatable it captures the method, and that method climbs visible stages — repetition, not first impulse, earns a skill (the rule of three):

Use #1
DraftsFirst capture. Lands in Learning/Drafts/, tagged [draft] — already discoverable and usable.
Use #2
Pre-GraduateProven once. Moves to Learning/Pre-Graduate/, tagged [pre-graduate] — usable, still on probation.
Use #3
SkillsGraduated. Promoted into Inventory/Abilities/Skills/ as a first-class, named skill.

Each capture moves the skill one folder forward (the older copy is deleted, so a skill lives in exactly one place). The count + latest recipe are tracked in .capture-ledger.json.

06 NoidChat pairing

Your bot gets its own NoidChat identity — scan-to-pair, no copy-pasting tokens. It happens during ngent setup (or install, unless you passed --skip-pair).

  1. A QR appears in your terminal during pairing.
  2. Scan it with your NoidChat app.
  3. Approve the request in NoidChat.
  4. Identity is saved locally at ~/.ngent/.secrets/ngent/identity.json — so the bot stays paired.
  5. Auto-boot brings the daemon online; DM the bot to confirm it's listening.
Pairing is self-service and skippable. If identity.json already exists, setup won't re-pair unless you ask it to. Pairing needs node.

07 CLI reference

ngentMode B — start an interactive agent session in the current folder.
ngent setupThe configure wizard: OpenRouter key → model → pair NoidChat → auto-boot.
systemctl --user status ngentMode A — check whether the daemon is running. Use start / stop / restart to control it.
bash ~/.ngent/status.shOne-glance status of the running bot (pid, uptime, NoidChat auth, saved-fact count, last activity). Add --watch for a live feed, --raw for everything.
$ bash ~/.ngent/status.sh
═══ Ngent status ═══
● RUNNING   pid=… uptime=…
● NoidChat  authenticated ✓

08 Troubleshooting

"checksum mismatch — refusing to install"

The installer is fail-closed: it verifies the code tarball against ngent-code.sha256 before unpacking. A mismatch means the download was corrupted or tampered with — it refuses rather than installing bad code. Just re-run the curl command to fetch a clean copy.

"couldn't build a venv"

NGENT needs uv or python3-venv to create its isolated environment. Install one and re-run:

$ curl -LsSf https://astral.sh/uv/install.sh | sh   # uv (fast, self-contained)
# …or install your distro's python3-venv package, then re-run the installer

No systemd session → terminal-only

On containers, sandboxes, or macOS there may be no systemd --user session, so the always-on daemon (Mode A) can't install. The installer detects this and skips the service automatically — the ngent terminal command (Mode B) still installs and works. You can force this anywhere with --terminal-only.

Can't type ngent from anywhere

The command lands in ~/.local/bin. If it's not on your PATH, add it:

$ export PATH="$HOME/.local/bin:$PATH"   # add to your shell rc to persist

"python 3.10+ required" / "node not found"

Install python ≥ 3.10 (required) and node (only for pairing — or pass --skip-pair to go terminal-only without it). curl is always required.

Back to top