Deploying an Omnigent server gives you a stable HTTPS URL that makes every session reachable from any device — including your phone, since the web UI is built for mobile — and lets teammates join shared sessions. The server is the coordination point; your code and model API keys stay on the machines that register as hosts. This page explains how to pick a deployment target, which database backend to use, and how to connect your laptop once the server is up.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt
Use this file to discover all available pages before exploring further.
Deployment targets
Docker Compose
Run on any host you already have — a VPS, home server, EC2 instance, or your own laptop. Most flexible target.
Render
One-click deploy. Render auto-provisions a managed Postgres database and HTTPS on
*.onrender.com. No local tooling needed.Railway
Deploy via GitHub in the Railway dashboard. Railway provisions a managed Postgres plugin. HTTPS on
*.up.railway.app.Fly.io
CLI deploy with
fly deploy. Uses SQLite on a persistent volume by default — no separate database to provision.Modal
Always-on web server with
modal deploy. Durable artifact Volume. Bring your own Postgres (Neon recommended).Hugging Face Spaces
Docker Space for demos. SQLite on disk, zero database setup. Free tier storage is ephemeral.
Execution model
Omnigent runs in two pieces that communicate over a WebSocket tunnel:- Server — the FastAPI app you deploy here. Handles HTTP and SSE routes, terminal-attach WebSockets, persistence, and the web UI.
- Runner (host) — a Python subprocess that runs on the user’s machine (laptop, dev container, etc.). It dials in to the server via
WS /v1/runner/tunnel, executes the LLM loop and tools locally, and streams events back.
omnigent run … --server <url> or omnigent claude --server <url>. This separation is why the server image is small — it contains no tmux, no harness SDKs, and no LLM API keys.
Database: Postgres or SQLite
The server supports two first-class database backends (same schema, same migrations; the backend is selected viaDATABASE_URL):
| Backend | DATABASE_URL format | Best for |
|---|---|---|
| Postgres | postgresql+psycopg://… or postgres://… | Production, multi-instance, managed backups |
| SQLite | sqlite:////data/artifacts/chat.db | Single-instance demos, no database to provision |
DATABASE_URL. Any postgres:// or postgresql:// URL works; the server entrypoint normalizes it to the psycopg3 dialect automatically.
SQLite is the zero-dependency lite tier: the .db file lives on the platform’s persistent disk or volume (Render disk, Fly volume, Railway volume) and survives restarts. On Hugging Face’s free Spaces, the disk is ephemeral, so SQLite data resets on restart. On Modal the Volume’s eventual-consistency semantics don’t suit a live .db file, so skip the SQLite tier there. Tradeoff: single instance only, no managed backups.
First boot against a remote Postgres is slow — migrations run over the network and take approximately 1 minute on Neon (near-instant for local SQLite). Subsequent boots are fast. Make sure the platform’s healthcheck grace period tolerates it: Render and Railway do by default. On Fly, raise
grace_period in [[http_service.checks]] if you use a remote database.After deploying: connect your laptop
Once the server is up, sign in from your machine. The token is reused byrun, attach, and host:
login detects the server’s auth mode automatically — built-in accounts, OIDC, and header-auth proxies all work with the same command.
Then register your machine as a host so sessions created in the web UI can run on it:
Quick network access (no deploy needed)
If all you need is to reach the server from your phone or share it briefly with a teammate, you have two lightweight options that require no platform deploy: LAN access (same network). Find your machine’s LAN IP address (e.g.192.168.1.42) and open http://192.168.1.42:6767 on any device connected to the same Wi-Fi. The web UI is mobile-friendly and works over HTTP on a local network.
Cloudflare quick tunnel (public URL). Install cloudflared and run:
cloudflared prints a randomly generated *.trycloudflare.com URL that proxies to your local server over HTTPS. No account or sign-up required. Share the URL with anyone; the tunnel exists only while the command runs. Remote runners and cloud sandboxes can connect back to it the same way they would a deployed server.