nanoinfra Documentation
What nanoinfra Is
nanoinfra is a self-hosted AI agent for infrastructure work. It keeps an inventory of your servers, the credentials to reach them, and the tools to act on them. The tools are execution over SSH, Ansible, AWS SSM, or an HTTP endpoint you configure. It also keeps saved topology diagrams it can read and edit. You reach it from a terminal, a browser, or sixteen chat apps.
That focus is the point. nanoinfra is not a general-purpose assistant that happens to have a shell tool. An agent that can reach production needs layers between it and your hosts, and it has them today —
- Deny by default. Every channel needs an explicit sender allowlist. An empty list denies everyone, and direct messages additionally require pairing approval. See Configuration.
- A kernel-level sandbox. On Linux, shell commands can run inside bubblewrap, where the process sees the workspace and nothing else. Bubblewrap masks your config and API keys. See Configuration.
- Credentials that do not come back out. Secrets are encrypted at rest and no API or agent tool returns a plaintext value. Provider keys can stay as
${VAR}references so they exist only in memory. See Secrets and Servers. - Tools that declare their blast radius. Every tool marks whether it only reads, and mutating operations take a dry run first.
- A gate on every mutating and remote action. Each tool carries a capability class. Each action resolves a scope of one host, a host group, or all hosts. An unattended context refuses remote execution by default. See Capability Gates.
- An automation that tells you what it needs before it runs. Creating a scheduled automation rehearses it once with every gated action previewed. Nothing executes. You learn whether an unattended run would be permitted and which standing grant it would need, instead of finding out from a refusal at 03:00. See Commissioning.
- A human approval on a second path. An unusual remote action suspends and waits. The approval must arrive on an authenticated path other than the path of the request. It covers the exact command and host list the executor rendered. See The Approval Path.
- A privilege split with a sandbox on each helper. Remote execution, web access, and stdio MCP servers each run in their own process. Each one gets a Unix socket, an account, and a Landlock policy of its own. See The Process Split.
Use these docs to get a working agent first, then open a task guide only when you need the next capability. Source-level design and extension details are kept in the contributor section. These docs follow the current source tree and can be newer than the latest published package.
Start Here
| Your situation | Read this | You are done when... |
|---|---|---|
| You are comfortable running commands | Install and Quick Start | nanoinfra status is healthy and the WebUI or CLI can get one reply |
| Something already failed | Troubleshooting | You have isolated the problem to install, config, model, gateway, channel, or tool access |
The recommended first-run path is:
- Install nanoinfra.
- Let the installer open
nanoinfra webuion a fresh local desktop. - Configure a provider and model in Settings → Models.
- Send
Hello!before configuring anything else.
Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain nanoinfra onboard --wizard as a terminal fallback. After the WebUI opens, use Settings for models and built-in capabilities, Settings → Channels for chat apps, and Apps for CLI App or MCP integrations.
Add One Capability
Pick the row that matches what you want to accomplish next:
| Goal | Guide |
|---|---|
| Learn the browser workbench | WebUI |
| Connect Telegram, Discord, Slack, Signal, Email, or another chat app | Channels |
| Choose a hosted, OAuth, company, or local model | Provider Cookbook |
| Add model fallbacks | Configure Model Fallback |
| Enable web search | Configure Web Search |
| Add an MCP tool server | Configure MCP Tools |
| Generate images | Image Generation |
| Store credentials and let the agent connect to a server (SSH, Ansible, SSM, API) | Secrets and Servers |
| Schedule work or create a local trigger | Automations |
| Learn what permission an automation needs before it runs unattended | Commissioning |
| Understand and manage long-term memory | Memory |
| Let the agent search your own runbooks, with citations | Knowledge |
| Store a topology the agent can read and edit | Infra Diagrams |
| Run nanoinfra continuously | Deployment |
| Run separate bots or workspaces | Multiple Instances |
| Call nanoinfra from Python | Python SDK |
| Expose an OpenAI-compatible endpoint | OpenAI-Compatible API |
For shorter, outcome-focused walkthroughs, browse the task guide index.
Operate nanoinfra
| Need | Read |
|---|---|
| Commands and flags | CLI Reference |
| In-chat slash commands | In-Chat Commands |
| Config, workspace, gateway, sessions, tools, and memory in plain language | Concepts |
| Policy for remote execution, approvals, and the audit log | Capability Gates |
| Provider/model matching and selection | Providers and Models |
| Setup and runtime diagnosis | Troubleshooting |
| Put your own SSO in front of the gateway | Identity and SSO |
| Serve more than one customer from one host | Multi-Tenancy |
| See what changed in the version you run | Changelog |
| Read the long-form 0.x history | Release Archive |
Reference
Use reference pages to look up an exact option after you know what you are trying to configure:
| Area | Reference |
|---|---|
| How config is loaded, secrets, environment variables, channels, deployment-wide settings | Configuration |
| Every provider, model preset, fallback and transcription field | Provider and Model Configuration |
| Named agents, tool groups, web tools, MCP, knowledge, connectors | Agent and Tool Configuration |
| Capability gates, approvers, standing grants, pairing | Security Configuration |
| Provider and model behavior | Providers and Models |
| Channel prerequisites and manual JSON | Channels |
| WebSocket authentication and wire protocol | WebSocket |
| Python SDK classes, events, sessions, and hooks | Python SDK |
| OpenAI-compatible HTTP routes and payloads | OpenAI-Compatible API |
| Runtime self-inspection and tuning | My Tool |
Configuration examples are usually snippets to merge into ~/.nanoinfra/config.json, not complete replacement files. The docs use camelCase because nanoinfra writes config that way. Keep real API keys, bot tokens, and passwords out of issues and public logs.
Extend or Contribute
These pages explain implementation and extension points. You do not need them to install or operate nanoinfra.
| Goal | Read |
|---|---|
| Understand source ownership and runtime flow | Architecture |
| Set up a development environment | Development and CONTRIBUTING.md |
| Add a channel package | Channel Package Guide |
| Build the WebUI source | WebUI Development |
If a command or screen no longer matches these docs, please open an issue. Include your nanoinfra version, operating system, and the page that needs correction.