ContextQMD
Back to Nanobot

How to Run a Self-Hosted AI Agent with nanobot

docs/guides/self-hosted-ai-agent.md

0.3.02.5 KB
Original Source

How to Run a Self-Hosted AI Agent with nanobot

This guide sets up nanobot as a self-hosted AI agent runtime on your own machine or server. The result is a gateway process that can serve the WebUI, chat apps, automations, and API integrations.

What you will build

  • a nanobot config and workspace under your control
  • a model provider connected through config.json
  • a long-running nanobot gateway
  • optional browser, chat app, and API access

When to use this

Use this path when you want local or server-side ownership of the agent process, workspace files, memory files, and provider keys. It is also the right path when the agent must keep running after one terminal command finishes.

Install

bash
python -m pip install nanobot-ai
nanobot onboard --wizard
nanobot agent -m "Hello!"

Complete the CLI check before deploying the gateway. A deployment problem is much easier to debug after the provider and model are known to work.

Minimal working example

For chat apps, automations, and WebSocket delivery, start the gateway:

bash
nanobot gateway

For the browser surface, use the WebUI launcher instead. It can start and manage the local gateway for you:

bash
nanobot webui

Or connect a channel in ~/.nanobot/config.json, then keep the same gateway process running for messages.

Production notes

  • Use Docker, systemd, or a macOS LaunchAgent when the process should survive terminal exits.
  • Give every deployed instance a distinct config path, workspace path, and port set.
  • Keep secrets in environment variables and start the service from the same environment.
  • Use health checks against the gateway or API process, not chat app delivery as the only signal.

Security notes

  • Bind local-only services to 127.0.0.1 unless you intentionally expose them.
  • Set an API key before binding the OpenAI-compatible API to a public interface.
  • Prefer pairing for DM-capable chat apps, and keep any static allowFrom allowlists strict.
  • Enable tools.restrictToWorkspace; on Linux, use the bubblewrap sandbox for shell execution.

Troubleshooting

  • Run nanobot status with the same --config and --workspace flags used by the service.
  • Run nanobot gateway --verbose while debugging channel startup.
  • Check port conflicts if the WebUI, WebSocket channel, or API endpoint fails to bind.