Deploy Omnigent on Fly.io, Modal, or Hugging Face Spaces

Three additional platforms cover specialized deployment needs: Fly.io for CLI-first deploys with SQLite on a persistent volume, Modal for an always-on web server with a durable artifact Volume, and Hugging Face Spaces for a demo-grade Docker Space with zero database setup. All three use the same ghcr.io/omnigent-ai/omnigent-server image that Docker Compose and the one-click platforms use.

Fly.io

Fly.io is CLI-first. There is no embeddable one-click button; you deploy with fly deploy from the repo root. The default configuration uses SQLite on a persistent volume — no separate database app to provision — making it the simplest path for a single-instance deploy.

What gets provisioned

omnigent — a machine running ghcr.io/omnigent-ai/omnigent-server, served on https://<app>.fly.dev with automatic HTTPS
artifact_data — a 1 GB persistent volume mounted at /data/artifacts, holding the artifact store, the minted cookie secret, and (by default) the SQLite database

Deploy

Create the app and volume

fly apps create <your-app>
fly volumes create artifact_data --size 1 --region iad -a <your-app>

Pick a region close to your team. The volume region must match the primary_region in fly.toml.

Deploy

fly deploy -c deploy/fly/fly.toml -a <your-app>

The fly.toml pins a 1 GB machine ([[vm]] memory = "1gb"). The server idles around ~275 MB RSS, so Fly’s 256 MB default OOM-loops. Do not reduce the memory allocation.

Get the admin password

fly logs -a <your-app>

Look for Created initial admin account ... password: <generated> (also written to /data/admin-credentials on the volume). The cookie secret and base URL (FLY_APP_NAME → <app>.fly.dev) are handled automatically.

Connect your laptop

omnigent login https://<your-app>.fly.dev
omnigent host https://<your-app>.fly.dev

Switching to Postgres

For multiple instances or managed backups, point DATABASE_URL at Postgres instead of the volume SQLite. Two options:

# Option 1: Fly Postgres
fly postgres create
fly postgres attach <pg-app-name> -a <your-app>    # sets DATABASE_URL as a secret

# Option 2: Neon (bring your own)
fly secrets set DATABASE_URL='postgres://…' -a <your-app>

Remove the DATABASE_URL = "sqlite:///…" line from [env] in fly.toml so the attached or secret value wins.

When switching to a remote Postgres, raise grace_period in the [[http_service.checks]] block from 20s to approximately 90s. First boot runs migrations over the network and takes ~1 minute — Fly will otherwise kill the machine mid-migration on the first deploy.

Setting OIDC auth

fly secrets set \
  OMNIGENT_AUTH_PROVIDER=oidc \
  OMNIGENT_OIDC_ISSUER=https://github.com \
  OMNIGENT_OIDC_CLIENT_ID=<client-id> \
  OMNIGENT_OIDC_CLIENT_SECRET=<client-secret> \
  OMNIGENT_OIDC_REDIRECT_URI=https://<your-app>.fly.dev/auth/callback \
  OMNIGENT_OIDC_COOKIE_SECRET=$(openssl rand -hex 32) \
  -a <your-app>

Cost: a shared-cpu-1x 1 GB machine plus a 1 GB volume runs a few dollars a month for a lightly loaded instance.

Modal runs the Omnigent server as a single always-on web server. Modal provides the HTTPS URL, log streaming, and a persistent Volume for the artifact store — uploaded agent bundles survive restarts and redeploys. Modal also has no managed Postgres, so you bring your own.

Prerequisites

A Modal account and the CLI: pip install modal && modal setup
A Postgres database. The fastest option is Neon: create one and copy the connection string.

Deploy

Create the Modal secret bundle

The app URL is deterministic: https://<workspace>--omnigent-server.modal.run (your workspace name is shown by modal profile current).

modal secret create omnigent-deploy \
  DATABASE_URL='postgres://…neon.tech/…' \
  OMNIGENT_ACCOUNTS_COOKIE_SECRET="$(openssl rand -hex 32)" \
  OMNIGENT_ACCOUNTS_BASE_URL='https://<workspace>--omnigent-server.modal.run'

If the printed URL after deploy differs from what you guessed (e.g. a non-default Modal environment adds a suffix), update the secret and redeploy.

Deploy the server

modal deploy deploy/modal/modal_app.py

The first boot runs DB migrations over the network (~1 minute on Neon).

Get the admin password

modal app logs omnigent

Look for:

✓ Created initial admin account (accounts auth provider).
    password: <generated>

To set a known admin password instead of the auto-generated one, add OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=<password> to the omnigent-deploy secret before the first deploy.

Connect your laptop

omnigent login https://<workspace>--omnigent-server.modal.run
omnigent host https://<workspace>--omnigent-server.modal.run

2 MiB WebSocket message cap. Modal’s ingress limits WebSocket messages to 2 MiB each. Normal streaming traffic is far smaller, but a single very large tool payload over the tunnel can fail on this platform.
24-hour input timeout. A proxied WebSocket occupies one Modal function input, and inputs are capped at 24 hours — so a tunnel lives at most one day before being cut. Runners auto-reconnect with jittered backoff.
One always-on container by design. min_containers=1 / max_containers=1 in modal_app.py. The runner registry is in-memory, so traffic must not be spread across containers, and scale-to-zero would kill live runner tunnels.
No SQLite tier. The artifact Volume is durable but not suitable for a live .db file (eventual-consistency semantics). Always use Postgres on Modal.
Memory requirement. The app pins memory=1024 — the server’s working set exceeds Modal’s defaults.

Switching to OIDC auth

Replace the omnigent-deploy secret with OIDC values and redeploy:

modal secret create omnigent-deploy \
  DATABASE_URL='…' \
  OMNIGENT_AUTH_PROVIDER=oidc \
  OMNIGENT_OIDC_ISSUER='https://github.com' \
  OMNIGENT_OIDC_CLIENT_ID='…' \
  OMNIGENT_OIDC_CLIENT_SECRET='…' \
  OMNIGENT_OIDC_REDIRECT_URI='https://<workspace>--omnigent-server.modal.run/auth/callback' \
  OMNIGENT_OIDC_COOKIE_SECRET="$(openssl rand -hex 32)"

modal deploy deploy/modal/modal_app.py

Upgrading: run modal deploy deploy/modal/modal_app.py again — Modal re-resolves ghcr.io/omnigent-ai/omnigent-server:latest. Cost: an always-on 1 GiB instance runs roughly

6–8/month, which fits inside the Starter plan's

30/month of free credits — effectively free for a lightly loaded server.

Hugging Face Spaces

HF Spaces (Docker SDK) builds a Dockerfile at the Space repo root and runs it. The setup uses the prebuilt image with SQLite — no external database required. This is a demo-grade target; the free tier’s disk is ephemeral.

On the free tier of Hugging Face Spaces, the disk is ephemeral — data (including the SQLite database) resets on every restart. Use this for demos and short-lived experiments only. For data that survives restarts, add HF’s paid persistent storage or point DATABASE_URL at an owned external Postgres such as Neon.

Setup

Create a Docker Space on Hugging Face

Go to huggingface.co/new-space and select Docker as the SDK.

Add the Dockerfile and README front-matter

Add the Dockerfile from deploy/hf-spaces/ at your Space repo root (it pulls the prebuilt image). Add a README.md with the required HF front-matter:

---
title: Omnigent
emoji: 🤖
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 8000
---

Set variables and secrets in Space Settings

Go to Settings → Variables and secrets and add:

Name	Kind	Value
`PORT`	variable	`8000`
`HOST`	variable	`0.0.0.0`
`DATABASE_URL`	variable	`sqlite:////data/artifacts/chat.db`
`OMNIGENT_ACCOUNTS_COOKIE_SECRET`	secret	output of `openssl rand -hex 32`

Pin OMNIGENT_ACCOUNTS_COOKIE_SECRET explicitly — ephemeral disk would otherwise drop active sessions on restart.

Get the admin password and log in via the direct URL

The Space builds and boots. The admin password is printed in the Space Logs on first boot. The base URL is auto-detected from SPACE_HOST.Log in via the direct URL (https://<user>-<space>.hf.space) in its own tab — not HF’s embedded preview. The session cookie is SameSite=Lax, which browsers won’t send inside HF’s cross-origin iframe, so logging in from the embedded view loops back to /login. Make the Space Public so the direct URL is accessible without HF authentication.

Adding persistence

To make data survive restarts, replace DATABASE_URL with an external Postgres:

Go to pg.new and create a free Neon Postgres. Sign in to keep it — an unclaimed instant database expires.
Copy the connection string and set it as the DATABASE_URL Space secret (replacing the SQLite value). The entrypoint normalizes postgres:// automatically.

Note that first boot against a remote database takes ~1 minute while migrations run; subsequent boots are fast.

Back to Deployment overview.

Get Started

Core Concepts

Guides

Deployment

Reference

Deploy Omnigent on Fly.io, Modal, or Hugging Face Spaces

Fly.io

What gets provisioned

Deploy

Switching to Postgres

Setting OIDC auth

Prerequisites

Deploy

Switching to OIDC auth

Hugging Face Spaces

Setup

Adding persistence

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Reference

Documentation Index

​Fly.io

​What gets provisioned

​Deploy

​Switching to Postgres

​Setting OIDC auth

​Modal

​Prerequisites

​Deploy

​Modal-specific caveats

​Switching to OIDC auth

​Hugging Face Spaces

​Setup

​Adding persistence

Build docs developers (and LLMs) love

Fly.io

What gets provisioned

Deploy

Switching to Postgres

Setting OIDC auth

Modal

Prerequisites

Deploy

Modal-specific caveats

Switching to OIDC auth

Hugging Face Spaces

Setup

Adding persistence