Getting Started

Prerequisites

Node.js ≥ 22 is required (the package declares engines: node >= 22). npm ships with Node, so if you have a recent Node you already have npm. No external Postgres, no Redis, no cloud config.

Install

npm install -g nodal-agents
nodal-agents up

Prefer not to install anything globally? npx nodal-agents up runs the same stack from a one-off download.

If npm asks you to approve install scripts

Recent npm versions do not run a package's install scripts until you approve them. On a fresh install you may see this:

npm warn allow-scripts 4 packages have install scripts not yet covered by allowScripts:
npm warn allow-scripts   @embedded-postgres/windows-x64@18.3.0-beta.17 (install: (install scripts present))
npm warn allow-scripts   @whiskeysockets/baileys@6.7.23 (preinstall: node ./engine-requirements.js)
npm warn allow-scripts   protobufjs@7.6.6 (postinstall: node scripts/postinstall)
npm warn allow-scripts   tesseract.js@7.0.0 (postinstall: opencollective-postinstall || true)
npm warn allow-scripts Run npm approve-scripts --allow-scripts-pending to review, or npm approve-scripts <pkg> to allow.

Only one of those packages matters. @embedded-postgres/<platform> carries the Postgres binaries Nodal boots, and its install step finishes preparing them. The other three run fine without their scripts. Approve that one package, then install again:

npm approve-scripts @embedded-postgres/darwin-arm64
npm install -g nodal-agents@latest

Use the name for your machine. It is the one npm printed in the warning, and there is exactly one per platform: darwin-arm64 (Apple Silicon), darwin-x64 (Intel Mac), windows-x64, or, on Linux, linux-x64, linux-arm64, linux-arm, linux-ia32, linux-ppc64.

On Windows the gate is harmless. The published @embedded-postgres/windows-x64 ships the Postgres executables inside the tarball, and its install step has nothing to do there: the list of links it would recreate is empty. Measured on the registry with npm pack @embedded-postgres/windows-x64@18.3.0-beta.17 --dry-run --json: 1502 files, native/bin/postgres.exe among them, and a native/pg-symlinks.json of 2 bytes, which is []. The same file weighs 1100 bytes in the Linux package. So if nodal-agents up still fails on Windows after that warning, the cause is elsewhere. Send the output of nodal-agents up with your report rather than approving scripts and hoping.

First run: the setup wizard

The very first time you run nodal-agents up — when no ~/.nodalai/config.json exists yet — the CLI launches an interactive setup wizard before starting anything. It walks you through:

1. LLM provider — which model you want to use, picked from a list of presets (Ollama, LM Studio, Jan AI, llama.cpp, vLLM, Anthropic, OpenAI, OpenRouter…).
2. Endpoint URL — the provider's base URL (pre-filled with a sensible default you can accept or override).
3. Model — the CLI fetches the available models from the endpoint and lets you pick one; if it can't reach the endpoint, you type the model name instead.
4. API key — prompted only for remote providers that require one.
5. Network mode — Loopback (localhost only, no auth) or LAN (accessible on your network, sign up with email + password).

Your answers are saved to ~/.nodalai/config.json. Re-run the wizard any time with nodal-agents init.

Once the wizard finishes (or on every subsequent run, since the config now exists), the CLI spawns an embedded Postgres on a free port, applies migrations, seeds the system skills, and starts the runner (:3001) and the dashboard (:3000). Open localhost:3000.

Your data lives at ~/.nodalai/ — wipe it any time with rm -rf ~/.nodalai. Stop the stack with nodal-agents down.

What you land on

The dashboard opens on an empty conversation, not on a page of numbers: "Hey, what are we building today?" with a composer under it.

Nothing is written until you send your first message, so opening this screen and closing it leaves no trace. Once you send, the thread gets its own address and appears under Channels → Nodal chats in the sidebar.

The sidebar is a rail of five boards — Work, Agents, Run, Approvals, Settings — each opening its own panel. Everything below is reached from there. The full map is the dashboard reference.

Connect a model

The empty conversation cannot answer until a provider key exists.

1. Click Settings at the foot of the rail, then LLM Providers.
2. Click Add provider and pick one — Anthropic, OpenAI, Google, DeepSeek, MiniMax, OpenRouter, or a local endpoint (Ollama, LM Studio, …).
3. Paste the key. Local providers need a base URL instead.
4. Click Test connection. The dashboard makes a real call to the provider and reports what came back. Save is blocked until the test passes — a key that was never verified is worse than no key.

Setup is one key per provider. Every agent in the workspace can then use any model from it, and each agent picks its own. Full walkthrough: Connect a model.

Create your first agent

1. Open the Agents board in the rail and click Create New Agent.
2. Choose how to start:
   • Customize a new agent — an empty form, you pick everything.
   • Pre-filled agent profiles — a profile pre-fills the name, the role, the model and the skills that fit. Recommended connectors are suggested, never imposed.
3. Nothing is written to the database until you create the agent, so everything stays editable while you look at it.
4. After it exists, its tabs carry the rest: Skills, Tools, Connectors, Autonomy (per-tool approval), Channels.

The first orchestrator you create becomes this workspace's ROOT agent — the one the dashboard chat talks to.

Send it something

Go back to Work in the rail and type into the composer, or open a thread that already exists. Follow what happens in Logs → Activity, which lists every run and unfolds onto its tool calls; open any run to get its own page, with what it cost, what it delivered and which files it wrote.

If the agent asks to run something that needs your sign-off, it shows up on the Approvals board.

Update

nodal-agents update

Checks npm for the latest version, stops the stack, installs nodal-agents@latest, and restarts automatically. Your data is preserved.

Other commands

nodal-agents logs [web|runner|postgres]

Tails logs for the given service, or all three if you omit the argument.

nodal-agents checkpoints

Lists the snapshots taken before an agent wrote in the current directory. nodal-agents checkpoints restore <sha> puts the folder back. See Proof.

nodal-agents reset --yes

Deletes all Nodal-Agents data and config. Omit --yes to get a confirmation prompt first.

Every command and flag is in the CLI reference.