Install and Quick Start

This guide has one goal: get a normal nanoinfra reply in your browser. Do not add chat apps, MCP servers, fallback models, or deployment until this path works.

Nothing is assumed. If a word below is new, If a word here is new defines it, and the four install methods are ordered easiest first.

These repository docs follow current main. uv tool install, pip and the container all give you the stable release. So a WebUI screen documented here may not appear until the next release. Each advanced guide also gives a CLI or manual config path.

What You Need

Python 3.11 or newer.
Access to one supported AI provider, company endpoint, or local model server.
The credential, endpoint URL, and model ID required by that service. Local providers such as Ollama may not require a key.

Git is only needed for a source install. The published package already contains the WebUI. A current-source install needs bun or npm so its WebUI bundle can be built.

An API key is password-like. Do not post it in an issue, a screenshot, a chat or a public config file.

If a word here is new

Word	Meaning
Terminal	A text window where you paste a command and press Enter
Command	One instruction typed into the terminal
Provider	The service or local server that runs the AI model
Model ID	The exact model name that provider expects
API key	A secret credential that lets software call the provider
Wizard	A question-and-answer setup menu
WebUI	The local browser page where you use nanoinfra

To open a terminal: on macOS press Command+Space, type Terminal and press Enter. On Linux, open the application menu and search for Terminal.

If you do not have Python 3.11 or newer, install it from python.org before you continue.

1. Install nanoinfra

Four methods, easiest first. Pick one. Each keeps nanoinfra out of the system Python environment. The commands are the same ones the install page shows.

uv

The shortest path. Install uv first if you do not have it. That is one command.

uv tool install nanoinfra
nanoinfra onboard --wizard

pip

Run this inside a virtual environment.

python -m pip install nanoinfra
nanoinfra onboard --wizard

If pip reports externally-managed-environment, the system Python is off limits. Use uv, pipx install nanoinfra, or a virtual environment you made yourself.

Docker

The only deployment where the kernel enforces the privilege split. The entrypoint gives the executor, the fetcher, the MCP host and the connector host their own accounts.

Run the wizard once:

docker run --rm -it \
  -v ~/.nanoinfra:/home/nanoinfra/.nanoinfra \
  ghcr.io/nanoinfraorg/nanoinfra onboard --wizard

Then start the gateway:

docker run -d --name nanoinfra \
  -v ~/.nanoinfra:/home/nanoinfra/.nanoinfra \
  ghcr.io/nanoinfraorg/nanoinfra gateway

Two things to know. gateway is not optional, because the default command is status. And the WebUI binds 127.0.0.1 inside the container, so publishing port 8765 also needs channels.websocket.host set to 0.0.0.0 and a token. See Deployment for the capabilities it needs.

Source

This method builds the WebUI, so bun or npm must be present. uv reads the lockfile in the repository.

git clone https://github.com/nanoinfraorg/nanoinfra.git
cd nanoinfra && uv sync
uv run nanoinfra onboard --wizard

Then start the WebUI and configure the first provider there:

nanoinfra webui

2. Configure Your Model

The browser opens the local WebUI. Go to Settings → Models and:

Choose the provider or endpoint that owns your credential.
Enter its API key or base URL when required.
Create or select a model preset using a model ID that provider can run.
Save the configuration.

The WebUI launcher creates or updates:

Path	Purpose
`~/.nanoinfra/config.json`	Provider, model, WebUI, channel, tool, and runtime settings
`~/.nanoinfra/workspaces/default/`	Sessions, memory, skills, automations, and generated files

If the browser did not open, run:

nanoinfra webui

SSH, headless, existing-config, and older-release installs retain the terminal setup path:

nanoinfra onboard --wizard

3. Check the Setup

nanoinfra status

You want:

a check mark for Config and Workspace
the model or preset you selected
a configured state for the provider used by that model.

Most other providers can say not set. This command validates local setup but does not call the model.

4. Get the First Reply

If the WebUI is no longer running, run nanoinfra webui again. Leave that terminal open. The first-run WebUI binds to localhost, so no other device on your network can reach it.

Send:

Hello!

Any normal assistant answer is success. It proves that nanoinfra can load the config, reach the selected model, use the workspace, and serve the browser UI.

Leave the terminal open while using the WebUI. If you prefer a managed background process, stop the foreground process with Ctrl+C, then run:

nanoinfra gateway --background
nanoinfra gateway status

Use nanoinfra gateway logs, restart, and stop to manage that background gateway.

Terminal-Only Check

If you do not want the browser or need to isolate a WebUI problem, send one message directly:

nanoinfra agent -m "Hello!"

Then start an interactive terminal chat with:

nanoinfra agent

In interactive mode, Enter sends and Alt+Enter inserts a newline. Exit with exit, /exit, :q, or Ctrl+D.

Choose One Next Step

After the first reply works, add one capability and test again:

Goal	Recommended path
Learn sessions, workspaces, tools, and access modes	WebUI guide
Connect a chat platform	Open Settings → Channels, then use Channels for platform prerequisites
Change or add a model	Open Settings → Models. The Provider Cookbook has a recipe
Add web search, voice, or image generation	Use the matching WebUI Settings page, then consult Configuration for advanced fields
Add an App or MCP integration	Open Apps or follow Configure MCP Tools
Schedule agent work	Read Automations
Run continuously or remotely	Read Deployment
Integrate from code	Use the Python SDK or OpenAI-Compatible API

When `nanoinfra` Is Not on PATH

The package can be installed and the shell still not find the command, because the command belongs to the environment that installed it. Use that environment's runner:

uv tool run --from nanoinfra nanoinfra --version
pipx run --spec nanoinfra nanoinfra --version
uv run nanoinfra --version                      # in a source checkout
~/.nanoinfra/venv/bin/python -m nanoinfra --version

Replace --version with webui, onboard --wizard, or any other arguments. Use plain python -m nanoinfra only when that Python executable belongs to the environment where nanoinfra was installed.

pipx install nanoinfra is a fourth way to install, equivalent to uv tool install if pipx is what you already have.

What a Source Install Gives You

A source install follows current main, so it can be newer than the published package — and newer than these docs. uv sync installs from the lockfile in the repository. The install then triggers a build hook that bundles the current WebUI. That hook is why bun or npm must be present.

For editable Python or frontend development, follow CONTRIBUTING.md and webui/README.md.

Manual Configuration Fallback

Use this only when the wizard is unavailable or you intentionally manage JSON. First run nanoinfra onboard, then merge a provider and a named model preset into ~/.nanoinfra/config.json.

A generic OpenAI-compatible setup has this shape:

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "provider": "custom",
      "model": "model-id-from-your-provider"
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Replace the provider, endpoint, and model together. Do not pair a credential from one service with a model ID from another. See Provider Cookbook for hosted, OAuth, company, and local examples, and Configuration for exact fields.

Updating

Upgrade with the same method you used to install:

uv tool upgrade nanoinfra
pipx upgrade nanoinfra
python -m pip install -U nanoinfra
docker pull ghcr.io/nanoinfraorg/nanoinfra:latest

For a source checkout:

git pull
python -m pip install .

Then check nanoinfra --version. Run nanoinfra onboard --refresh when you want to add newly introduced default fields while preserving existing settings.

If the First Reply Fails

Do not change several settings at once. Start with:

nanoinfra --version
nanoinfra status
nanoinfra agent -m "Hello!"

Symptom	First check
`nanoinfra: command not found`	Use the runner that owns the installation, listed under When `nanoinfra` Is Not on PATH
JSON parse error	Check the commas and braces. Docs examples are usually snippets, not whole files
`401` or invalid API key	Verify the selected provider owns that key and remove accidental spaces
Model not found	Use a model ID available from the provider selected in the active preset
CLI works but WebUI does not open	Use port `8765`, not gateway health port `18790`
WebUI works but a chat app does not	Check Settings → Channels, then run `nanoinfra channels status`

Continue with the ordered Troubleshooting guide if the cause is still unclear.

What You Need​

If a word here is new​

1. Install nanoinfra​

uv​

pip​

Docker​

Source​

2. Configure Your Model​

3. Check the Setup​

4. Get the First Reply​

Terminal-Only Check​

Choose One Next Step​

When nanoinfra Is Not on PATH​

What a Source Install Gives You​

Manual Configuration Fallback​

Updating​

If the First Reply Fails​