Skip to main content

How to Deploy a Long-Running nanoinfra AI Agent Gateway

The nanoinfra gateway is the long-running self-hosted AI agent process. It keeps WebUI sessions, chat apps, automations, local triggers, heartbeat jobs, Dream and WebSocket delivery online.

What you will build​

  • a verified nanoinfra config
  • a gateway process
  • a service or container deployment path with Docker, systemd, or macOS LaunchAgent

When to use this​

Use this when nanoinfra should keep running after a single CLI turn. Chat apps, browser sessions, background automations, local triggers, and server-side integrations all depend on a live gateway.

Install​

Quick Start ranks four install methods easiest first. This is the first of them. Use pip, Docker or a source checkout instead if you prefer, and come back here.

uv tool install nanoinfra
nanoinfra onboard --wizard
nanoinfra status
nanoinfra agent -m "Hello!"

Minimal working example​

Run the gateway in the foreground:

nanoinfra gateway

For WebUI background usage:

nanoinfra webui --background
nanoinfra gateway status
nanoinfra gateway logs

Production notes​

  • Docker Compose is the most repeatable Linux container path.
  • systemd user services are useful for Linux user-level gateway deployments.
  • macOS LaunchAgent keeps the gateway alive after login.
  • Persist config, workspace, sessions, memory files, channel login state, and generated artifacts.
  • Restart the gateway after editing config.json.
  • Give every deployed instance a distinct config path, workspace path and port set. See Multiple Instances.
  • Keep secrets in environment variables. Start the service from the same environment.
  • Run health checks against the gateway or the API process. Do not use chat app delivery as the only signal.

Security notes​

  • Plan ports before exposing services. Gateway health defaults to 18790, WebUI/WebSocket defaults to 8765, and nanoinfra serve defaults to 8900.
  • Bind externally only when you have configured tokens or API keys.
  • Keep chat access control intentional before deploying.
  • Use Docker or Linux sandboxing when shell tools are enabled for unattended work. Secure a local AI agent covers tools.restrictToWorkspace and the bubblewrap sandbox.
  • Set an API key before you bind the OpenAI-compatible API to a public interface.

Troubleshooting​

  • Use the same --config and --workspace flags for status checks and service startup.
  • Check logs with docker compose logs, journalctl, LaunchAgent logs, or nanoinfra gateway --verbose.
  • If Docker port publishing does not work, confirm the service is not bound only to container loopback.
  • Check for a port conflict if the WebUI, the WebSocket channel or the API endpoint fails to bind.