Deploy Omnidev on the internet with TLS, secrets hygiene, IP allowlisting, and operational verification commands.
This guide describes how to deploy Omnidev on the public internet with a defense-in-depth posture: TLS, trusted network paths, strong authentication, secret handling, and operational habits. It complements Environment Setup, Docker Setup, API Authentication, and Credentials Management.
Omnidev installs and orchestrates the publicly available Claude Code package. Users must have their own Claude account and active subscription. Claude Code is a product of Anthropic PBC and is not affiliated with this project.
Omnidev is a single-user control plane that can clone repositories, run an agent, push branches, and expose APIs. If an attacker gains dashboard or API access, they can trigger work against configured remotes and data on disk (data/, workspaces). The goal of secure deployment is to:
| Approach | Security | Tradeoff |
|---|---|---|
Public HTTPS + strong auth + optional ALLOWED_IPS | Good for remote access from known locations | Requires a correctly configured reverse proxy for IP trust |
| Private network / VPN / Tailscale only | Strongest reduction of attack surface | No direct public URL; more setup |
| Edge firewall / WAF / Cloudflare | Absorbs bots and credential stuffing before the app | Extra service and configuration |
The application does not replace a firewall or WAF; combine layers.
NEXTAUTH_URL to the canonical public URL (scheme https, no trailing slash, no :3000 in production).See Docker Setup for production Compose and health checks (GET /api/health).
| Variable | Role |
|---|---|
NEXTAUTH_SECRET | Session encryption/signing. Generate with openssl rand -base64 32. |
NEXTAUTH_URL | Public base URL; must match the URL users type in the browser. |
INITIAL_SIGNUP_TOKEN | Strongly recommended in production. Prevents arbitrary first-user signup if the signup UI is reachable. Generate with openssl rand -hex 32. |
Persisted data includes SQLite (data/ralph.db), API key hashes (data/api-keys.json), and user credentials. Treat the volume or host directory like a secrets store:
data/ in encrypted backups; treat backups as sensitive.data/ or .env to git (use pnpm run check:secrets in CI where applicable).data/api-keys.json) over long-lived keys only in environment variables.Session-based dashboard traffic is authenticated via NextAuth; API clients use X-API-Key or Authorization: Bearer as described in API Authentication.
ALLOWED_IPS)The app enforces an optional IP allowlist before session/API-key checks. Client IP is taken from X-Forwarded-For (first hop) or X-Real-IP.
Rules:
ALLOWED_IPS behind a trusted reverse proxy that sets or overwrites these headers from the TCP connection, not from the client request.203.0.113.10,198.51.100.2). The value * allows all IPs (not recommended for public exposure without other controls).0.0.0.0 if relying on IP rules; keep the app on an internal Docker network and expose only the proxy.Example Caddy snippet (conceptual; adapt to your install):
reverse_proxy app:3000 {
header_up X-Forwarded-For {remote_host}
header_up X-Real-IP {remote_host}
}
See Environment Setup for Traefik notes (trustedIPs / forwarded headers).
API_RATE_LIMIT)pnpm worker or the worker service in Compose) with the same trusted data/ and workspace volumes as the app so jobs see the same state.Sandbox and PATH behavior for containerized runs are described in Sandbox Architecture.
withAuthA small set of routes are intentionally public or UI-oriented, for example:
GET /api/health — liveness for load balancers (no secrets).GET /api/config/validate — configuration status (may reveal missing integration tokens; still useful behind TLS for the dashboard).Do not rely on obscurity for these; keep TLS and network controls in place.
pnpm audit regularly and after upgrades. Address critical and high issues in direct dependencies first; document accepted risk for dev-only transitive issues.pnpm test and pnpm audit (allow non-zero exit when triaging).Run from the repository root after dependency changes:
Full test suite (includes auth and API integration tests)
pnpm test
# Focused authentication and API middleware tests
pnpm run security:integration
# npm advisory database (may exit non-zero when vulnerabilities exist)
pnpm run security:audit
Optional broader quality gate (types, lint, formatting):
pnpm lint:all
Optional secret scan before commit:
pnpm run check:secrets
Use this before pointing a domain at a new deployment:
NEXTAUTH_URL matches the live URL.NEXTAUTH_SECRET is unique and long; not reused from another app.INITIAL_SIGNUP_TOKEN set; first account created only with the token if that flow is enabled.X-Forwarded-For / X-Real-IP if using ALLOWED_IPS.API_RATE_LIMIT set appropriately; edge limits considered for login routes.data/ and workspace policy documented.pnpm audit reviewed; critical/high items triaged or upgraded.| Document | Topic |
|---|---|
| ENVIRONMENT.md | All environment variables |
| DOCKER.md | Compose, Coolify, ports, health |
| API_AUTHENTICATION.md | API keys, sessions, errors |
| CREDENTIALS.md | Token storage practices |
| SANDBOX_ARCHITECTURE.md | Container execution boundaries |
This guide does not replace a professional penetration test, formal compliance program, or managed SOC. It focuses on self-hosted deployment hygiene for Omnidev.