Orva

Self-hosted Functions-as-a-Service for your homelab or on-prem server.

Write a JavaScript, TypeScript, or Python function, hit deploy — Orva runs it in an isolated nsjail sandbox and serves it over HTTP. One Docker container gives you the runtime, a dashboard, a CLI, an MCP server, and a built-in AI assistant. It's for the Lambda/Workers workflow — write a function, invoke it over HTTP, schedule it, chain it — on hardware you control (a Pi, a homelab box, a VPS, bare metal). No cloud account, no per-invocation billing.

Active development. Solid for homelabs, side-projects, and internal tools. Not recommended for customer-facing production yet.

---

Quick start

docker run -d --name orva -p 8443:8443 \
  --pid host --cgroupns host \
  --cap-add SYS_ADMIN \
  --security-opt seccomp=unconfined \
  --security-opt apparmor=unconfined \
  --security-opt systempaths=unconfined \
  --device /dev/net/tun \
  -v orva-data:/var/lib/orva \
  -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
  ghcr.io/harsh-2002/orva:latest

--pid host and --cgroupns host are required on the default runc runtime: nsjail enrolls each sandbox PID in the host cgroup hierarchy, and without them every invocation fails with Launching child process failed. --device /dev/net/tun is what network_mode: egress functions need — each sandbox gets its own TAP device inside nsjail's user namespace, so the container itself needs no NET_ADMIN (only add it back if you force ORVA_DISABLE_USERNS=1). docker compose up -d (see Install) sets all of this for you.

Open http://localhost:8443, finish onboarding (~30s), and deploy your first function from the in-browser editor.

Prefer Compose, a bare-metal service, or just the CLI? See Install.

---

Features

• Two runtimes — node (Node.js 24, also runs TypeScript) and python (Python 3.14).
• Real isolation — every function runs in its own nsjail sandbox: user namespace, chroot, cgroup v2 limits, and a seccomp syscall allowlist. → Security
• Warm pools — idle workers stay resident per function, so repeat calls skip cold start.
• Built-in primitives — per-function KV store, background jobs (retries + backoff), cron schedules, function-to-function calls, encrypted secrets, custom routes, and signed inbound webhooks.
• Distributed tracing — every HTTP → F2F → job chain shares one trace, with a waterfall view and zero code changes.
• Versioning — content-hashed deploys with one-click (or one-command) rollback and side-by-side diffs.
• MCP + AI — a 73-tool operator MCP server at /mcp and a built-in agentic AI assistant (dashboard or orva chat) that operate your instance with your own provider key. → AI & MCP
• Templates — 21 starters (Stripe/GitHub webhooks, JWT/OAuth, CSV→JSON, URL shortener, …) in the editor.

---

Write a function

The orva SDK is preinstalled in every sandbox — KV, function-to-function invoke, and background jobs, with nothing to install:

// Node — Python uses the same shape: from orva import kv, invoke, jobs
const { kv, invoke, jobs } = require('orva')

exports.handler = async (event) => {
  await kv.put('hits', (await kv.get('hits') || 0) + 1)
  await invoke('send-notification', { msg: 'hello' })   // child span in the same trace
  await jobs.enqueue('audit-log', { at: Date.now() })   // async, retried on failure
  return { statusCode: 200, body: { ok: true } }
}

The SDK reaches Orva over HTTP, and network_mode defaults to none — so set the function's network mode to egress or every SDK call fails with ENETUNREACH. The editor warns you at deploy time when it spots the import.

Handler contract, event shape, and streaming: docs/RUNTIMES.md.

---

Install

Docker Compose (recommended for persistent setups):

curl -fsSL https://raw.githubusercontent.com/Harsh-2002/Orva/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

Compose publishes on http://localhost:3000 (it maps 3000:8443), not :8443 like the docker run above.

Bare-metal / VM — systemd or OpenRC, no Docker (Debian/Ubuntu, Fedora/RHEL/Rocky/Alma, Alpine, Arch, openSUSE):

curl -fsSL https://github.com/Harsh-2002/Orva/releases/latest/download/install.sh | sh

CLI only — operator laptop or CI runner (Linux, macOS, Windows × amd64/arm64):

curl -fsSL https://github.com/Harsh-2002/Orva/releases/latest/download/install-cli.sh | sh   # macOS / Linux
irm  https://github.com/Harsh-2002/Orva/releases/latest/download/install-cli.ps1 | iex        # Windows

Installers are idempotent — re-run to upgrade; pin a version with ORVA_VERSION=vYYYY.MM.DD. TLS, reverse proxy, and backup guidance: docs/DEPLOYMENT.md.

---

CLI

Orva ships a full Linux server binary and a slim cross-platform CLI. They share the same client-command library, so after orva login the whole platform is in your terminal:

orva deploy ./src --name my-fn --runtime node   # runtimes: node | python
orva invoke my-fn --body '{"name":"world"}'
orva logs my-fn --follow
orva chat                                        # the AI assistant, in your terminal

Output is scripting-clean (-o json; data on stdout, status on stderr). Full reference: docs/CLI.md.

---

AI & MCP

Add Orva to any MCP client (Claude Code, Cursor, or claude.ai via OAuth) with one URL:

https://your-orva-instance/mcp

The agent can create and deploy functions, invoke them, read logs, manage secrets, and browse KV. Prefer not to wire up an external client? The dashboard's AI section — and orva chat — run the same agent in-product with your own provider key (OpenAI, Anthropic, or any OpenAI-compatible endpoint) and optional per-write approval.

---

Configuration

Defaults work out of the box. Common knobs: ORVA_PORT (8443), ORVA_DATA_DIR (/var/lib/orva), ORVA_SECURE_COOKIES (only needed if neither TLS nor X-Forwarded-Proto reaches Orva — it sets the flag itself when it can see the real scheme). Full reference: docs/CONFIG.md.

---

Documentation

ARCHITECTURE	System design, request + deploy lifecycle
SECURITY	Threat model, sandbox isolation, verification recipe
RUNTIMES	Handler contract, event shape, streaming
Reference	The canonical single-page reference — also served at /web/docs.md and by orva docs
API	Full REST API reference
CLI	Config precedence, command reference, workflows
CONFIG	All configuration knobs
DEPLOYMENT	TLS, reverse proxy, backups, upgrades
OPERATIONS	Monitoring, troubleshooting, common errors
ERRORS	Error-code catalogue: slug → HTTP status → what to do
TRACING	Causal trace model, propagation, W3C interop
SUPPORT	Distro / kernel / container-runtime matrix
CAPACITY	Throughput numbers + benchmark methodology
CONTRIBUTING	Dev setup, build from source, tests
TESTING	End-to-end verification guide: bring-up, testing layers, user journeys, triage

Runtime isolation specifics (Kata, gVisor) live in docs/KATA.md and docs/GVISOR.md.

---

License

Apache-2.0