How to Deploy a Long-Running navin AI Agent Gateway

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

What you will build

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

When to use this

Use this when navin 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

python -m pip install navin-ai
navin webui   # configure provider & model in the platform (Settings → Providers)
navin status
navin agent -m "Hello!"

Minimal working example

Run the gateway in the foreground:

navin gateway

For WebUI background usage:

navin webui --background
navin gateway status
navin 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.

Security notes

Plan ports before exposing services. Gateway health defaults to 18790, WebUI/WebSocket defaults to 8765, and navin 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.

Troubleshooting

Use the same --config and --workspace flags for status checks and service startup.
Check logs with docker compose logs, journalctl, LaunchAgent logs, or navin gateway --verbose.
If Docker port publishing does not work, confirm the service is not bound only to container loopback.

Related navin docs

Multiple Instances