Install ngn¶

ngn is the terminal and headless client for nagents. Choose a published distribution for a release snapshot, or an editable checkout for current development. Do not let Poetry and uv independently manage the same virtualenv.

Release availability¶

Published distributions provide the ngn console entry point, terminal client, coding harness, and headless commands. The verified v0.15.0 wheel also includes ngn serve, the web extra, and built React assets under nagents/web/static/, alongside the tui and voice extras. The web client is not source-only.

Install the terminal client into your chosen virtual environment:

python -m pip install 'nagents[tui]'
ngn --demo

For the browser client, install nagents[web] and run ngn serve. Published wheels serve bundled frontend assets without requiring Node. Omit these extras for headless-only use. Pin a release with ==VERSION when reproducibility is required, and consult the release notes.

Documentation follows the checkout

This guide can describe changes newer than your installed distribution. Compare release notes and installed commands before relying on a particular feature or fix. Use the web client guide for ngn serve.

The editable workflows below are for development. Local version metadata can lag source changes; check ngn --help, installed source, and release contents as well as ngn --version when verifying feature availability.

Requirements¶

Python >=3.11, <4.0; Python 3.13 is used in the uv examples below.
A POSIX host for the guarded coding tools and shell process-group cleanup. Windows is not yet a supported coding-tool host.
An interactive terminal for the full-screen TUI. Use ngn run for pipes, scripts, and environments without a terminal.
The tui extra for Textual. Headless use and importing the nagents library do not require it.
A provider account/API key for live model requests, or eligible ChatGPT/Codex device login for the default OpenAI route. Neither is needed for --demo.

The base runtime dependencies are aiohttp>=3.9.0, aiosqlite>=0.20.0, and pyyaml>=6.0; the TUI adds textual>=8.2.8 and its dependencies. The project uses minimum version constraints, not a promise that one frozen dependency set is always the latest. A fresh uv pip install resolves versions satisfying those constraints; Poetry uses its lockfile. The CLI does not require the OpenAI or Anthropic SDK, or a heavyweight gateway SDK. Connecting to a LiteLLM server does not install or start that server.

macOS notes¶

The coding harness targets Linux and macOS. CI exercises Python 3.11-3.14 on macos-latest, plus Python 3.13 on an Intel macOS runner. It uses fake audio and HTTP fixtures: passing CI does not validate a physical microphone, terminal key mapping, or access to a paid provider account.

Use a supported Python installation and a UTF-8 terminal. The Poetry and uv commands on this page also apply to macOS.
Shift+Enter requires the terminal to send a distinct key sequence. If it does not, use Ctrl+J for a newline. Alt/Option+Enter also works when the terminal is configured to send Option as Meta. Most shortcuts use Ctrl rather than Command; copying also accepts Command+C when the terminal forwards it. Mouse selections copy on release, and local macOS copying uses pbcopy, including in Terminal.
macOS configuration stays at ~/.config/ngn/config.json and state at ~/.local/share/ngn, unless XDG settings override them; ngn does not switch to ~/Library/Application Support on this platform.
Use consistent on-disk casing when selecting a workspace: case variants can currently select different session scopes even on case-insensitive APFS. Prefer workspace-relative tool paths. macOS aliases such as /tmp versus /private/tmp are not interchangeable for absolute guarded-tool paths; a custom XDG_DATA_HOME must use physical, non-symlinked ancestors. The ordinary defaults under /Users/... avoid these system aliases.
A shell command or trusted plugin can still be OS-specific. ngn does not translate Linux utilities into macOS equivalents. The guarded shell uses /bin/sh, not the user's interactive zsh configuration.

Existing Poetry workflow¶

From the repository root, keep the project's existing local workflow:

poetry install -E dev -E tui
poetry run ngn --demo

For a terminal-only environment without development tools, use poetry install -E tui instead. Continue using poetry run for that environment:

poetry run ngn --help
poetry run ngn --version
poetry run ngn run --demo --json "Explain the offline demo"
poetry run ngn doctor --demo

Do not recreate an existing Poetry-managed .venv with uv venv. There is no need to migrate an environment or rewrite a lockfile just to try ngn.

If the Poetry shell plugin is installed, your existing shell workflow also works:

poetry shell
ngn --demo

This uses the editable checkout in Poetry's environment, not a separate global ngn executable. Without the plugin, poetry run ngn needs no shell activation.

Local editable install with uv¶

For a new local environment, run these commands from the repository root:

uv venv --python 3.13
uv pip install --python .venv/bin/python -e '.[tui]'
uv run --no-project --python .venv/bin/python ngn --demo

-e installs this checkout editably: Python source changes are reflected on the next launch without reinstalling. Re-run the install after changing dependency metadata or extras. Quote '.[tui]' so the shell does not expand the brackets.

The explicit interpreter selects the local environment without activation. --no-project prevents uv run from treating this as a uv-managed project and automatically synchronizing project dependencies. These commands do not require uv sync, uv lock, or any changes to an existing uv.lock. In particular, do not use project-lock synchronization as an installation step for this workflow.

If .venv already belongs to Poetry or another workflow, keep it intact. Either use that workflow or choose a different local environment explicitly:

uv venv --python 3.13 .venv-ngn
uv pip install --python .venv-ngn/bin/python -e '.[tui]'
uv run --no-project --python .venv-ngn/bin/python ngn --demo

The relative interpreter path is relative to the shell's current directory. From another directory, use the absolute path instead:

uv run --no-project --python /absolute/path/nagents/.venv/bin/python ngn --workspace /path/to/project --demo

Optional activation¶

For a POSIX shell, activation makes the installed ngn command directly available. Only use the --active variant after activating the intended environment:

source .venv/bin/activate
ngn --demo
uv run --no-project --active ngn --demo

Without activation, prefer the explicit --python .venv/bin/python form. --active does not create or identify the intended environment for you.

Explicit environment files¶

ngn does not load .env automatically. If you intentionally keep provider credentials in a local environment file, uv can load it for the launched process:

uv run --no-project --python .venv/bin/python --env-file .env ngn --provider-id my-openrouter --model openai/gpt-6-luna

Use only a file you trust. Keep it out of version control and do not include its contents in logs, screenshots, or bug reports. Configure my-openrouter in providers.json with "api_key_env": "OPENROUTER_API_KEY". The filename is a launcher option; the secret value is never a CLI argument or YAML field.

Headless-only install¶

Omit the extra if you do not need the full-screen interface:

uv venv --python 3.13
uv pip install --python .venv/bin/python -e .
uv run --no-project --python .venv/bin/python ngn run --demo --json "Hello"

As above, only create .venv if it is not already managed by another workflow.

Optional isolated tools¶

These alternatives are not the default local editable workflow. They are useful when you intentionally want uv to manage a separate tool environment. Replace /absolute/path/nagents with a local checkout containing this CLI:

uvx --from '/absolute/path/nagents[tui]' ngn --demo

This is a non-editable, built installation in uv's tool cache, not a live link to your source tree. Do not expect source changes to appear automatically in a cached invocation. For a fresh, disposable build after source changes, bypass both the cache and previously installed tool environments:

uvx --no-cache --isolated --from '/absolute/path/nagents[tui]' ngn --demo

This rebuilds and installs dependencies again; prefer the local editable workflow for repeated development launches. Let concurrent source edits finish before building a non-editable snapshot.

For an explicitly installed, isolated tool that does track local Python source:

uv tool install --editable '/absolute/path/nagents[tui]'
ngn --demo

The checkout must remain at that path. Follow uv's PATH instructions if ngn is not found, and use uv tool uninstall nagents to remove that tool installation. Tool environments are separate from the repository's Poetry or .venv environment; they are not needed just to run from the checkout.

Optional microphone support for Realtime voice¶

Realtime speech-to-speech examples use the voice extra (sounddevice>=0.5.6) for microphone capture. In the local uv environment:

uv pip install --python .venv/bin/python -e '.[voice]'

With Poetry, select the same extras, retaining -E dev if desired:

poetry install -E voice

sounddevice requires a working audio input device and PortAudio support on the host. On systems where PortAudio is not supplied with the Python package, install the appropriate system library. Grant microphone access through the operating system if needed. Headless containers and SSH sessions often have no usable local microphone; the ordinary text interface needs none of this.

Verify the installation¶

With the local uv environment, these checks require no provider credentials:

uv run --no-project --python .venv/bin/python ngn --version
uv run --no-project --python .venv/bin/python ngn --help
uv run --no-project --python .venv/bin/python ngn run --help
uv run --no-project --python .venv/bin/python ngn doctor --demo
uv run --no-project --python .venv/bin/python ngn run --demo --json "Hello"

The JSON command should emit JSON Lines with schema_version: 1 and finish with a done event. --demo makes no model requests, runs no shell commands, performs no workspace edits, and skips Python plugins. It can list visible workspace paths and saves demo conversations in local state storage. It is not a no-filesystem-I/O mode. JSON parsing and validation still happen in demo mode.

For an interactive check, start ngn --demo through your selected environment, then try demo approval, demo subagents, /help, and session resume. The approval is a preview only; approving it does not edit a file.

Troubleshooting¶

Symptom	Check
`ngn` is missing or has different flags	Check the selected environment, `ngn --version`, and release availability. Upgrade or choose an editable checkout if the needed command postdates the installed release.
TUI extra is missing	Install `nagents[tui]` (or an editable checkout with `[tui]`), or use the headless `run` subcommand.
TUI needs a terminal	Use a real interactive terminal, or `ngn run --json "prompt"` in a script.
uv tries to synchronize the project or use `uv.lock`	Use `uv pip install --python ...` and `uv run --no-project --python ...`; do not substitute `uv sync` or bare project-managed `uv run`.
Changes do not appear in an isolated `uvx` run	It is non-editable. Use the local editable workflow for development, or `uvx --no-cache --isolated --from '/absolute/path/nagents[tui]' ngn --demo` for a fresh build.
Missing API key	Configure an environment-variable name with `api_key_env`, set its value outside JSON, or use eligible OpenAI device login. `--demo` needs neither.
A setting in the environment seems ignored	JSON has higher priority than `NGN_*` defaults. Check precedence.
New fields or extras are unavailable	Compare the installed distribution with its release notes and the current source. The verified v0.15.0 distribution includes `voice`, `tui`, and `web`; newer configuration fields can still require a later release or checkout.

Continue with the usage guide and the complete configuration reference.