Install & Prerequisites

This page covers how to install the mono-agent CLI (including the terminal and browser operator consoles), the runtime prerequisites you need, and how to run an unreleased build straight from a clone of the repo.

The shipped command line lives in @mono-agent/agent-app (the config-first host that reads one mono-agent.config.json), the terminal console lives in @mono-agent/tui, and the always-on browser console lives in @mono-agent/web. All publish under the @mono-agent/* scope on npm. For convenience there is also an unscoped create-mono-agent installer: run it with npm create mono-agent@latest, and a global install of it puts the natural mono-agent command on your PATH. Both installer bins delegate to @mono-agent/agent-app; only the create-mono-agent name adds the npm-init routing described below.

Note

The bare mono-agent npm name isn’t ours — npm rejects it as too similar to an unrelated monoagent package — so the installer follows npm’s create-* convention (create-mono-agent), which npm create mono-agent resolves natively.

Prerequisites

Requirement	Version	Why
Node.js	>=22.19.0	Runtime for the CLI, host, and TUI. This matches the minimum required by the bundled Pi runtime.
pnpm	>=10	Only needed to build the workspace from source (the published packages install with plain npm/npm exec).
Provider sign-in	Provider account	Anthropic, GitHub Copilot, and OpenAI Codex sign in through the Pi runtime’s bundled OAuth flow (mono-agent auth login <provider>); OpenCode-Go uses OPENCODE_API_KEY. No external CLI install is required.

The default openai-codex:gpt-5.6-terra runtime signs in through the bundled Pi OAuth flow rather than a separate Codex CLI. mono-agent auth login openai-codex prints an auth URL to open in a browser, waits for the localhost callback, and accepts a pasted redirect URL / authorization code on remote or headless machines:

mono-agent auth login openai-codex

Note

You do not need pnpm to use the published packages — npm i -g and npm exec are enough. pnpm is only required for the “run an unreleased build” path below, which builds the workspace from source.

The repository includes .nvmrc, so source contributors using nvm can run nvm use to select the exact minimum version exercised in CI. Newer Node releases remain supported by the >=22.19.0 package engine range.

Install the CLI

Install the create-mono-agent installer globally to get the mono-agent command on your PATH:

npm i -g create-mono-agent

create-mono-agent ships both a create-mono-agent and a mono-agent bin. The persistent mono-agent name forwards arguments unchanged to @mono-agent/agent-app (installed alongside it). The installer name treats a bare invocation or any invocation whose first argument is a flag as init, except that singleton --help/-h prints the init help topic and singleton --version/-v prints the shared mono-agent <version> identity. Explicit subcommands pass through. Prefer the scoped host directly? It also puts mono-agent on your PATH and additionally installs the mono-agent-memory-recall helper bin used by the memory recall tool:

npm i -g @mono-agent/agent-app

Not installing globally? Run any command through npm exec with either name:

npm exec --package create-mono-agent -- mono-agent --help
npm exec --package @mono-agent/agent-app -- mono-agent --help

Scaffold without installing

If you only want to create an agent folder, use the bare npm-init form or spell init explicitly — no global install needed:

npm create mono-agent@latest
# explicit equivalent:
npm create mono-agent@latest init
# equivalently:
npx create-mono-agent init

This downloads and runs the published CLI for that one scaffold command. It does not require a global install or the source-build workspace setup. create-mono-agent --help and -h show init-specific help without scaffolding; --version and -v print the exact shared CLI version without writing anything. The scoped equivalent is npm exec --package @mono-agent/agent-app -- mono-agent init.

The TUI console

The operator console is built into the CLI — once an agent is running (mono-agent start), open it from any directory:

mono-agent tui

It discovers running agents on the machine and gives you live chat with structured thinking/tool/telemetry insight, bounded recorded-run replay, and a config view. The underlying @mono-agent/tui package also ships a low-level mono-agent-tui bin for custom hosts (--responder embedded mode, --url direct connect):

npm i -g @mono-agent/tui   # only needed for the standalone bin

See TUI for the console walkthrough.

The always-on web console

Once one or more agents are running, start the managed browser console from any directory on macOS:

mono-agent web start
mono-agent web

On Linux and other supported non-macOS hosts, use the foreground mono-agent web run command under your preferred service manager.

It listens on 0.0.0.0:5050 by default for local, LAN, and tailnet use; bare web only reports status and exact URLs. There is no application login, so use it only on a trusted LAN/tailnet or pass --loopback. See the web console guide for persistent threads, attachments, and service lifecycle.

Verify the install

Confirm both binaries resolve and print their help:

mono-agent --help
mono-agent-tui --help

The CLI exposes these commands (more detail in the CLI Reference):

Command	Purpose
init	Non-destructive scaffold of a config, IDENTITY.md, and .mono-agent/. A fresh built-in Journal/BuJo selection also gets one empty provider-free managed generation; pre-existing memory roots are never changed. On a TTY with no flags it runs the step-by-step wizard (preset or custom; walks you through model, channels, memory, tools, sandbox, observability); any flag or a non-TTY writes the scaffold silently. setup is an alias.
presets	List the built-in setup presets (list) or show a preset’s generated config, .env.example, and checklist (show <id>). Replaces the removed recipes command.
validate	Validate mono-agent.config.json and live checks that can be tested safely before starting.
start	Start the host for every configured channel (backgrounds on macOS; use --foreground elsewhere).
restart / stop / status / logs	Manage the backgrounded instance (macOS).
tui	Open the operator console and connect to any running agent.
web	Manage or run the always-on browser conversation console.
sessions (removed)	Removed — use mono-agent tui (recorded-run replay) or mono-agent web (live console).
install-skill	Install the authoring composer and its documentation MCP companion, or maintain managed project skills.
backfill	Replay historical runs into observability.

Next: scaffold your first agent

Once the binaries are verified, scaffold a clean project folder:

mkdir my-agent
cd my-agent
mono-agent init

On a terminal with no flags, mono-agent init is the readiness-proven step-by-step wizard: name the agent, enter the exact Role destined for IDENTITY.md → ## Role, search the Pi/Codex/Claude catalogs, configure any number of fallbacks and their exact efforts, then choose capabilities. The review says whether that Role will be written or an existing identity preserved. Escape goes back. A concrete creation review precedes provider/SRT mutations. On macOS it proves every selected route sequentially, prepares the private managed runtime, starts or refreshes the single canonical per-config launchd agent, waits for a fresh exact-snapshot ready trace source, and prints the edit → validate → restart → ordinary tui handoff. Interrupted preflight can resume fingerprint-matching successes or restart all checks. Pass --yes or any flag (or run in a non-TTY) for scaffold-only automation; that path never starts a process or makes a readiness claim. Off macOS, edit the preserved scaffold manually, validate, start the service or foreground process, and open ordinary mono-agent tui. See Setup security and managed runtime for the closure, environment, single-instance, and snapshot-integrity contracts behind the managed path.

mono-agent init --preset telegram-assistant --yes   # scaffold from a preset
mono-agent presets list                             # browse the built-in presets first

Then continue with the Quickstart to start the agent and send a webhook request. For the full key reference, see Config Blueprint and Environment Variables.

Updating

One-time managed-SRT upgrade to 0.9

When upgrading from 0.8 or earlier to 0.9 or later on macOS, treat the managed-SRT lock-protocol transition as offline. Before replacing packages, stop every background and foreground mono-agent process for this OS user and wait for any older mono-agent init or mono-agent sandbox setup command to exit. Keep old processes stopped until the new-version packages are installed and the first new-version mono-agent sandbox setup completes. Versions 0.8 and earlier do not acquire the permanent OS-level guard introduced in 0.9, so old and new setup or repair must never overlap.

Update global installs with npm:

npm update -g create-mono-agent     # (or @mono-agent/agent-app)
npm update -g @mono-agent/tui

The create-mono-agent installer, @mono-agent/agent-app, @mono-agent/tui, @mono-agent/web, and every other @mono-agent/* package release in lockstep at one version — keep any pinned references (scoped or the create-mono-agent installer) on the same version.

For reproducible installs or one-shot scaffolds, pin the version explicitly to a published release — use the same version across every @mono-agent/* package (pick one from the published npm versions):

version='0.13.0' # Replace with the published version you want to install.
npm i -g "@mono-agent/agent-app@$version" "@mono-agent/tui@$version"
npm exec --package "@mono-agent/agent-app@$version" -- mono-agent init

Source collaborators can review each version’s notes in the repository CHANGELOG.md and match them to its immutable source tag. Public installers can confirm every published package version through npm metadata. For the Product v1 line, first published to npm as 0.8.0, follow the complete existing-agent cutover checklist after updating the binaries.

Run an unreleased build

To run against unreleased changes (e.g. a feature branch), build the workspace from source and point mono-agent at the built CLI entry. This is the only path that needs pnpm >=10.

git clone https://github.com/robertsreberski/mono-agent.git
cd mono-agent
pnpm install --frozen-lockfile
pnpm run build

pnpm run build builds every package in dependency order. On supported POSIX/macOS hosts it first acquires the ignored exclusive .mono-agent-build.lock, removes the prior .mono-agent-build.json, finalizes the required CLI/TUI executable modes, syncs the completed deploy outputs, and atomically publishes a canonical owner-only marker. The marker records the full source SHA and state, Node version and ABI, completion time, a deterministic digest of the actual deploy outputs, and a separate digest of the installed root and workspace node_modules topology, modes, and file bytes (including native addons). Fleet deployment checks require the checkout to remain clean on both reads, recompute both digests, and bind every running instance to the full expected SHA. The marker and lock are operational state, not files to commit or copy between checkouts. A concurrent build fails closed; remove a stale lock only after proving no root build is still active, then rerun the complete build. Windows and unsupported hosts still run the normal build commands but do not publish this POSIX/macOS deploy proof. On a managed launchd fleet, --expect-labels <csv> additionally pins the exact host topology; the checker revalidates each selected canonical plist after its expensive probes, while auto-discovery alone cannot detect a plist that was removed before the run began. Current managed plists execute an owner-private copied runtime under ~/.mono-agent/runtimes, so pass --repo <deploy-checkout> to select the source checkout whose build marker and SHA are being proved. The checker also requires the copied CLI to occupy the canonical content-addressed path and verifies its v4 marker, complete closure manifest, package bytes, configured-plugin closure, and install-time execution-filesystem proof (including every resolution-path directory inside the private install root) against that source checkout at both ends of the probe; canonical ancestors above that root are separately required to remain owner-private. The running process must start after the conservative finalized-runtime boundary. After the build, the source CLI entry point is packages/agent-app/dist/cli.js. For a literal source-build smoke test from a clean folder, call that entry directly:

repo=/absolute/path/to/mono-agent
agent_dir=$(mktemp -d)
cd "$agent_dir"
node "$repo/packages/agent-app/dist/cli.js" init --model openai-codex:gpt-5.6-terra
node "$repo/packages/agent-app/dist/cli.js" validate

You can also alias mono-agent to the built entry so you can run the local build from anywhere:

alias mono-agent="node /absolute/path/to/mono-agent/packages/agent-app/dist/cli.js"
mono-agent --help

For the TUI bin from the same clone, alias mono-agent-tui to packages/tui/dist/bin/mono-agent-tui.js:

alias mono-agent-tui="node /absolute/path/to/mono-agent/packages/tui/dist/bin/mono-agent-tui.js"

Caution

Rebuild (pnpm run build) after pulling new changes — the alias points at compiled output in dist/, not the TypeScript sources, so edits are not picked up until you rebuild. Cross-package types and tests resolve against built dist/, so a stale build can mask or surface errors that do not match src.

Tip

Editable global link instead of an alias? After pnpm run build, run npm link from packages/agent-app (and packages/tui) to put the local bins on your PATH. You still rebuild after each change.