Shared Server

Everything in the previous sections runs on your laptop. That's the fastest way to get started, but when you want your Omnigent accessible from your phone, shareable with teammates, or running while your laptop sleeps, you need to deploy.

This section covers Omnigent's architecture, the options for hosting the server, and the options for hosting the runner.

Omnigent has three components: the server, the runner, and the UI.

Server

The server is the central coordinator. It manages:

• Session history. Every conversation, message, and tool call is persisted in a database (Postgres or SQLite).
• Artifacts. Files, Omnigent bundles, and uploads.
• Catalog. Registered and built-in Omnigent specs.
• MCP proxy & policies. Proxies MCP tool calls with server-side policy enforcement.
• Skills. Skill definitions that Omnigent can load.
• Auth & accounts. User authentication (built-in accounts or OIDC/SSO).

There are a few options for hosting the server on the cloud:

Docker Compose

Deploy the Omnigent server with Docker Compose. The stack includes the server and a Postgres database.

cd deploy/docker
./bootstrap.sh          # generates DB password + cookie secret into .env
docker compose up -d    # Omnigent server + Postgres

Key variables in .env (See Auth & SSO for details on multi-user auth):

Cloud platforms

Deploy the server to a cloud platform with managed infrastructure.

Railway & Render. On Railway, import the repo and it handles the rest, including managed Postgres; Render provisions the app and managed Postgres over HTTPS via one-click deploy. Both default to built-in accounts auth, so multi-user works out of the box.

Fly.io. Deploy with fly deploy using SQLite on a persistent volume. Configuration files are in deploy/fly/ in the repo.

cd deploy/fly
fly deploy

Hugging Face Spaces. Demo-grade Docker Space with SQLite. See deploy/hf-spaces/ in the repo.

Databricks

On a Databricks workspace there are two paths, and most users want the managed one.

Managed (recommended). Omnigent on Databricks (Beta) is a fully managed service: Databricks operates the Omnigent server for you, already wired to workspace identity, Foundation Models, AI Gateway, and MLflow Tracing. There is no deploy tooling, Lakebase bootstrap, or bundle to maintain. Enable the Omnigent preview in your workspace settings and follow the quickstart there.

Self-managed. Deploy and operate the Omnigent server yourself on Databricks Apps via Databricks Asset Bundles, backed by Lakebase (Postgres) and Unity Catalog Volumes. Configuration is in deploy/databricks/ in the repo. Reach for this only when the managed service is not available in your region, or when you need something it does not expose yet — custom YAML policies, bring-your-own provider API keys, or custom egress controls.

Kubernetes

Deploy the Omnigent server to a Kubernetes cluster with the kustomize manifests in deploy/kubernetes/ in the repo. The overlays/sandbox-runners/ overlay additionally turns on the kubernetes managed sandbox provider (sandbox.provider: kubernetes): a host_type: managed session spawns a dedicated runner Pod that runs omnigent host and dials back to the server.

That provider imports a Kubernetes client the base server image omits, so the overlay pulls the official ghcr.io/omnigent-ai/omnigent-server-kubernetes image variant — the standard server image plus the kubernetes client extra (OMNIGENT_EXTRAS=kubernetes). No self-built image is required; the overlay's images: block already points at it.

kubectl apply -k deploy/kubernetes/overlays/sandbox-runners
# then create the omnigent-creds harness Secret (see the overlay README)

Persistent storage for runner Pods

Runner Pods are ephemeral: the workspace lives on an emptyDir and is destroyed with the Pod. To expose durable data (datasets, model caches, shared output directories), mount pre-created PersistentVolumeClaims into every runner Pod with sandbox.kubernetes.pvc_mounts:

sandbox:
  provider: kubernetes
  kubernetes:
    pvc_mounts:
      - claim_name: omnigent-datasets
        mount_path: /mnt/datasets
        read_only: true       # default true; set false only for shared scratch

Each entry is a {claim_name, mount_path, read_only?} mapping. read_only defaults to true. Omnigent only references the claim — you pre-create the PV/PVC in the runner namespace (omnigent-sandboxes) out of band, so the server RBAC stays unchanged. Mounts land on the host container only; the init container that clones the repo never sees them.

Keep these caveats in mind:

• Mount paths are validated at server startup. A mount_path may not overlap /home/omnigent, Secret projections, or the image's OS directories (e.g. /home, /var, /run, /tmp, /etc, /opt); a malformed or reserved path fails startup rather than the first launch. Paths must be absolute and normalized, and may not duplicate or nest within each other.
• Writable claims are shared across concurrent runners. Use a ReadWriteMany-capable backend (NFS/SMB/CephFS) for anything writable, and prefer read_only: true everywhere else — a writable shared mount lets one session read and modify what another wrote, and its contents outlive the Pod.
• ReadWriteOnce claims pin all runners to one node — combine with node_selector deliberately, or later Pods sit Pending.
• A mount visible in the Pod is not automatically visible to a harness's own OS-level sandbox (Omnibox path grants are separate).

See deploy/kubernetes/README.md and deploy/kubernetes/overlays/sandbox-runners/README.md in the repo for the full guide.

sandbox:
  provider: kubernetes
  server_url: https://your-server.example.com
  kubernetes:
    secret_mounts:
      - secret_name: git-token          # a Secret in the runner namespace
        mount_path: /mnt/secrets/git     # absolute, non-reserved in-Pod path
      - secret_name: npm-token
        mount_path: /mnt/secrets/npm

Runner

The runner is the per-session process that executes Omnigent loops. It manages the harness (Claude Code, Codex, Claude SDK, etc.), runs tools, and streams events back to the server over WebSocket. The server starts runners on a host: a machine you register with the server.

By default, the host is your laptop. Register it with:

omni login <server-url>  // if auth is enabled
omni host <server-url>

This is why your local Claude Code or Codex installation "just works." Runners started on your laptop have direct access to your machine's tools, files, and credentials.

However, moving the runner to a cloud sandbox host gives you:

• No laptop dependency. Your Omnigent runs even when your machine is off.
• Cloud-native tooling. Your Omnigent can access cloud resources directly.
• Isolation. Each Omnigent runs in its own container, separate from your local environment.
• Scalability. Run many Omnigents in parallel without taxing your machine.

We currently support the Modal and Daytona platforms, with more integrations on the way. Check out the Cloud Sandbox Host page for more detailed setup instructions.

UI

The web UI, terminal UI, and mobile UI all talk to the server. They never talk to the runner directly. This means:

• If the server is on your laptop, UI access is local only
• If the server is deployed to the cloud, any device can reach it, including your phone. Notably, cloud-hosted servers also allow you to collaborate with other users on the same server.

Collaboration

Once the server is cloud-hosted, Omnigent is multi-user: share a live session with a link, let a teammate co-drive your Omnigent, or fork a conversation so someone can continue independently. This has moved to its own page — see Pair Programming for co-drive, sharing with Read/Edit permissions, and forking.