Build and run Omnigent’s server and Postgres together with Docker Compose on a laptop or existing Docker host. Use the supplied configuration and troubleshooting guidance to rebuild images, investigate startup problems, or adapt deployment to another platform.
Run the Omnigent server as a Docker compose stack (server + Postgres) on any Docker host — your laptop, a VPS, EC2 by hand, or as the base layer of any container-platform deploy. Invoke when the user wants to build the image, bring up the compose stack, debug the stack on a host they already have, or extend the stack for a new platform.
Review the instructions the agent will receive before you install.
The Dockerfile here is the single image used by every non-Databricks
deploy path. It bundles the FastAPI server + a pre-built web SPA
into a slim Python runtime. The compose file pairs it with Postgres
and exposes the server on port 8000.
The image is "external runner only" — it does NOT include tmux,
the harness SDKs, or anything that would let it execute agent code
in-process. Runners live on user machines and dial in via the
WebSocket tunnel. This keeps the image small (~250 MB), the security
boundary clean (server doesn't execute user code), and the deploy
shape consistent across hosts.
The same Dockerfile also has a host target — the prebaked Omnigent
HOST image (omnigent-host) that remote sandboxes boot from
(omnigent sandbox create --provider modal, server-launched managed
hosts). It is the inverse profile: full omnigent install plus git +
tmux, no SPA, no psycopg, no server entrypoint. Both images are
published by the same workflows with the same :sha-<short> /
:latest / :vX.Y.Z tag scheme. See the "Host image" section in
README.md here.
cd deploy/docker
cp .env.example .env # edit POSTGRES_PASSWORD at minimum
docker compose up -d --build
docker compose logs -f omnigent # Ctrl-C when you see "Uvicorn running"
Server is on http://localhost:8000.
Dockerfile | Multi-stage build with two final targets. web-builder (node:20) runs npm install && npm run build on web/. builder (python:3.12) installs omnigent into /opt/venv; server-builder overlays the SPA bundle from web-builder and adds psycopg. The default target (runtime) copies the venv + /build/ from server-builder and runs entrypoint.py. --target host builds the host image instead (from builder: omnigent + git/tmux, no SPA/psycopg/entrypoint). |
Dockerfile.dockerignore | BuildKit-aware exclude. Trims deploy/databricks/, deploy/aws/, tests, dev tooling — keeps the build context small. |
entrypoint.py | Server process entrypoint. Reads DATABASE_URL, runs Alembic migrations, builds the SQLAlchemy stores, calls create_app(), runs uvicorn. Single source of truth for what env vars the container respects. |
docker-compose.yaml | Two services: postgres (16-alpine, persistent volume) and omnigent (built from the Dockerfile, depends on postgres healthcheck). Build context is ../.. (repo root). |
.env.example | Documents every env var the compose file passes through: POSTGRES_PASSWORD, OMNIGENT_PORT, all the OMNIGENT_AUTH_* and OMNIGENT_OIDC_* vars. |
README.md | Customer-facing quickstart + the OIDC walkthrough (GitHub OAuth, Google Workspace, generic OIDC). |
# Force a clean rebuild after a Dockerfile or source change
docker compose build --no-cache omnigent
# Reset everything (drops the DB + artifact volumes)
docker compose down -v
docker compose up -d --build
POSTGRES_PASSWORD is only honored on first init of the data volume.
If you change it in .env, you need docker compose down -v before
up -d or the server will fail to authenticate against the existing
cluster.
| Symptom | Likely cause | First check |
|---|---|---|
Root URL returns {"service":"omnigent",…} instead of the SPA | npm build didn't produce the bundle inside the container | docker compose exec omnigent ls /build/omnigent/server/static/web-ui/ — empty = the web-builder stage didn't run cleanly. Rebuild with --no-cache. |
ModuleNotFoundError: No module named 'uvicorn' at startup | venv copy didn't pick up the install | Sanity-check the Dockerfile's VIRTUAL_ENV=/opt/venv is set before the uv pip install calls. |
psycopg.OperationalError: password authentication failed | POSTGRES_PASSWORD changed in .env after the data volume was initialized | docker compose down -v then up -d (wipes the DB). |
| Web UI loads but new chats hang forever | Expected — runners are external. The UI's landing page prints the CLI command to launch a runner. |
Cloud Run, Fly.io, Render, k8s, HF Spaces — they all consume the
same image. The platform-specific bit is the manifest (fly.toml,
service.yaml, Helm chart, Spaces config) and any platform-managed
TLS / DB wiring. Put that under deploy/<platform>/ next to
docker/, with its own README + SKILL.
deploy/README.md — the deploy-options menu.designs/OIDC_AUTH.md — full native OIDC design.No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Test Omnigent’s native Antigravity integration with a live local server and the real agy CLI. Verify messages traveling between the web interface and terminal, mirrored replies, permission requests, interruption, session resumption, and process cleanup.
Test Omnigent’s Antigravity SDK integration against a live local server. Build test agents and run real conversations to check Gemini authentication, model selection, tool connections, and failures across the full execution path.
Create reference documentation directly from source code for public functions, classes, command-line commands, and endpoints. Organize parameters, defaults, return values, errors, and runnable examples, then check that the documentation matches the implementation.
Create an Omnigent agent directory using validated templates for configuration and instructions. Choose how the agent runs, then add web search, shell access, external tool connections, or subagents only when the task requires them.
Turn a selected range of commits or merged pull requests into release notes grouped by change type. Describe user-visible effects, link to supporting changes, and highlight breaking changes so readers can assess an upgrade.
Test Omnigent’s setup, help, and terminal interactions by driving the real CLI in an isolated environment. Capture rendered screens and compare checks before and after a change to establish whether a reported interface problem was fixed.