From e02e757113def57803554ccdbbf16e0bae68d6db Mon Sep 17 00:00:00 2001 From: Harsh-2002 Date: Fri, 5 Jun 2026 05:09:59 +0000 Subject: [PATCH 1/2] docs: document `orva chat`/`orva docs`, refresh runtime + CLI-size + troubleshooting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bring the docs in line with the shipped CLI overhaul + runtime collapse: - CLI.md: new "AI assistant (orva chat)" + "Reference docs (orva docs)" sections; add both to the command-reference table; slim/server sizes ~20/~55 MB. - reference.md (canonical, re-embedded to mcp/frontend/cli): add orva chat + docs to the command index. - README.md: add orva chat/docs to the CLI examples; note the assistant is also in the terminal; drop the stale "~12 MB" CLI size + "3 binaries" line (ships Linux/macOS/Windows × amd64/arm64); runtime hint node|python. - OPERATIONS.md: stale "3.13 wheel" -> 3.14; add a troubleshooting symptom for EVERY function WORKER_CRASHED on bare-metal (the /proc-overmount + cgroup-delegation causes now fixed) with the nsjail self-check. - cli/CLAUDE.md: intro size ~12 -> ~20 MB (glamour/chroma). --- README.md | 16 ++++++++---- backend/internal/mcp/reference.md | 2 ++ cli/CLAUDE.md | 5 ++-- cli/commands/reference.md | 2 ++ docs/CLI.md | 42 ++++++++++++++++++++++++++++++- docs/OPERATIONS.md | 28 +++++++++++++++++++-- docs/reference.md | 2 ++ frontend/public/docs.md | 2 ++ 8 files changed, 89 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 131358e..50e72e3 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ to install just the client. Then open **http://localhost:8443**. ## Install just the CLI If you only need to talk to a remote Orva server (operator laptop, CI -runner, etc.), grab the ~12 MB standalone CLI. No Docker required, no +runner, etc.), grab the standalone CLI. No Docker required, no server install. Ships for Linux + macOS + Windows × amd64 + arm64. **Linux + macOS:** @@ -92,7 +92,9 @@ Then: ```bash orva login --endpoint https://your-orva.example.com --api-key orva_... orva functions list -orva upgrade # in-place self-update from GitHub +orva chat -p "how many functions do I have?" # the AI assistant, in your terminal +orva docs # the full reference, offline +orva upgrade # in-place self-update from GitHub ``` Full CLI docs at [docs/CLI.md](docs/CLI.md) — configuration (flag / @@ -158,7 +160,7 @@ The Build info card at the top of Settings shows the running release's version, | **Version diff** | Side-by-side source diff between any two past deployments — in the dashboard (CodeMirror merge view) or `orva diff ` for git-style unified output in the terminal. | | **MCP server** | 70 tools at `/mcp` — any MCP client (Claude Code, Cursor, etc.) can create functions, deploy code, manage secrets, browse KV, and read logs. | | **OAuth 2.1** | Add Orva as a custom connector in claude.ai or other OAuth-capable MCP clients — no API key copy-paste needed. | -| **Built-in AI assistant** | An in-product agentic chat (the dashboard's **AI** section) that operates your instance end-to-end — create and deploy functions, read logs, manage secrets and routes — using the same tools as the MCP server, in-process. Bring your own provider key (OpenAI, Anthropic, or any OpenAI-compatible endpoint); writes can be gated behind per-conversation approval. | +| **Built-in AI assistant** | An in-product agentic chat (the dashboard's **AI** section, or the terminal via `orva chat`) that operates your instance end-to-end — create and deploy functions, read logs, manage secrets and routes — using the same tools as the MCP server, in-process. Bring your own provider key (OpenAI, Anthropic, or any OpenAI-compatible endpoint); writes can be gated behind per-conversation approval. | | **16 templates** | Stripe webhooks, GitHub events, JWT auth, OAuth, CSV→JSON, URL shortener, and more — pickable in the editor. | --- @@ -322,16 +324,20 @@ curl -fsSL https://github.com/Harsh-2002/Orva/releases/latest/download/orva-cli- orva login --endpoint https://orva.example.com --api-key orva functions list -orva deploy ./src --name my-fn --runtime node +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 +orva docs # the full reference, rendered offline ``` Every command takes `-o json` for machine-readable output (data on stdout, status on stderr — so `orva … | jq` is always clean), and `orva invoke … --stream` streams a function's response chunk-by-chunk. +`orva chat` (interactive REPL or one-shot `-p`) drives the same AI +assistant as the dashboard, straight from the terminal. -Binaries: `linux-amd64`, `linux-arm64`, `darwin-arm64`. Fully static, no runtime deps. +Binaries: Linux, macOS, and Windows × amd64 + arm64. Fully static, no runtime deps. --- diff --git a/backend/internal/mcp/reference.md b/backend/internal/mcp/reference.md index 3cd7889..6198a07 100644 --- a/backend/internal/mcp/reference.md +++ b/backend/internal/mcp/reference.md @@ -1581,6 +1581,8 @@ orva system health # smoke test | `orva keys` | list / create / revoke | Manage API keys | | `orva activity` | [--tail] [--source web|api|...] | Paginated activity rows; live SSE with --tail | | `orva system` | health / metrics / db-stats / vacuum | Server diagnostics | +| `orva chat` | [-p MSG] | Chat with the AI assistant — interactive REPL or one-shot | +| `orva docs` | [--raw] | Render this reference in the terminal | | `orva setup` | [--skip-nsjail] [--skip-rootfs] | Install nsjail + rootfs on a bare host | | `orva serve` | [--port N] | Run as the server daemon (not the CLI client) | | `orva completion` | bash / zsh / fish / powershell | Emit shell completion script | diff --git a/cli/CLAUDE.md b/cli/CLAUDE.md index 51ce30a..4fabbb4 100644 --- a/cli/CLAUDE.md +++ b/cli/CLAUDE.md @@ -1,7 +1,8 @@ # cli/ -Standalone Orva CLI codebase. Builds into a slim `orva` binary (~12 MB -stripped) that ships on Linux, macOS, and Windows × amd64/arm64 from +Standalone Orva CLI codebase. Builds into a slim `orva` binary (~20 MB +stripped — `orva chat`/`orva docs` pull in glamour/chroma for terminal +markdown) that ships on Linux, macOS, and Windows × amd64/arm64 from every release. ## Layout diff --git a/cli/commands/reference.md b/cli/commands/reference.md index 3cd7889..6198a07 100644 --- a/cli/commands/reference.md +++ b/cli/commands/reference.md @@ -1581,6 +1581,8 @@ orva system health # smoke test | `orva keys` | list / create / revoke | Manage API keys | | `orva activity` | [--tail] [--source web|api|...] | Paginated activity rows; live SSE with --tail | | `orva system` | health / metrics / db-stats / vacuum | Server diagnostics | +| `orva chat` | [-p MSG] | Chat with the AI assistant — interactive REPL or one-shot | +| `orva docs` | [--raw] | Render this reference in the terminal | | `orva setup` | [--skip-nsjail] [--skip-rootfs] | Install nsjail + rootfs on a bare host | | `orva serve` | [--port N] | Run as the server daemon (not the CLI client) | | `orva completion` | bash / zsh / fish / powershell | Emit shell completion script | diff --git a/docs/CLI.md b/docs/CLI.md index fff8528..8153865 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -560,6 +560,44 @@ orva webhooks deliveries sub_… -o json # delivery history for a subscriptio orva webhooks retry del_… # retry a failed delivery ``` +### AI assistant (`orva chat`) + +The same AI assistant as the dashboard's **AI** sidebar, in the terminal. It can +operate your instance end-to-end (list/deploy functions, read logs, manage +secrets, …). Providers, API keys, the default model, and the approval policy are +configured in the web UI under **Settings → AI**; the CLI uses that saved +selection. + +```bash +# Interactive streaming REPL (banner shows the active provider/model). +orva chat +# slash commands: /help /model /thinking /new /clear /yolo /exit +# Ctrl-C aborts the current turn; Ctrl-D exits. + +# One-shot — prints the reply to stdout and exits (pipe-friendly). +orva chat -p "list my functions and their status" +echo "what failed today?" | orva chat -p @- + +# Per-session overrides (don't change the saved default): +orva chat --model gpt-4o --thinking deep -p "summarize recent errors" +``` + +Write/destructive tools pause for a `[y/N]` approval per the server's policy; +reads and invokes run freely. In non-interactive use (piped), a tool that needs +approval **fails closed** unless you pass `--auto-approve`. On a terminal the +reply is rendered as markdown; piped, it's plain text (`--raw` forces plain). + +### Reference docs (`orva docs`) + +```bash +orva docs # render the full Orva reference, paged through $PAGER +orva docs --raw # raw markdown (for grep / redirect) +orva docs | grep -i webhook +``` + +`orva docs` ships the same reference the dashboard and the AI assistant use, +embedded in the binary — no network needed. + --- ## Command reference @@ -593,6 +631,8 @@ Every subcommand at a glance. Run `orva --help` for full flags. | `orva diff [--from --to] [-o json] [--no-color]` | Git-style unified diff between two past deployments | | `orva activity [--follow \| --source X]` | Audit log: every API call, CLI command, MCP invoke | | `orva system health / metrics / db-stats / storage / vacuum` | Diagnostics + maintenance | +| `orva chat [-p MSG]` | Chat with the Orva AI assistant — interactive REPL, or one-shot with `-p` | +| `orva docs [--raw]` | Render the Orva reference documentation in the terminal | | `orva upgrade` | Self-update from the latest GitHub release | | `orva completion ` | Emit a completion script (see below) | | `orva --version` | Build identity (matches `/api/v1/system/health`) | @@ -801,7 +841,7 @@ perspective; the slim CLI is just smaller. | Linux | ✅ (amd64, arm64) | ✅ (amd64, arm64) | | macOS | ✅ (amd64, arm64) | ❌ (nsjail is Linux-only) | | Windows | ✅ (amd64, arm64) | ❌ | -| Size | ~12 MB | ~20 MB | +| Size | ~20 MB | ~55 MB | | `orva serve` | ❌ | ✅ | | `orva setup` | ❌ | ✅ | | `orva init` | ❌ | ✅ | diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 7998080..d18d82e 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -77,12 +77,36 @@ curl -s -H "X-Orva-API-Key: $KEY" "http://localhost:8443/api/v1/executions/$EXEC Look at the `stderr`. If empty, the worker died before writing — common causes: missing dependency (typo in `requirements.txt`), wrong -entrypoint, runtime version mismatch (`requirements.txt` references a -package that doesn't have a 3.13 wheel). +entrypoint, or a package with no wheel for the runtime's Python (3.14). **Fix.** Redeploy with corrected code; or rollback to the last known good version via the Deployments view. +## Symptom: EVERY function returns `WORKER_CRASHED` right after a bare-metal install + +**Diagnosis.** If *nothing* invokes (even a trivial handler) and the +`stderr` is empty, nsjail can't set up its sandbox in this host +environment — not a code problem. Two host-level causes seen on some +kernels/VMs: + +- **`/proc` overmount.** `journalctl -u orva` shows nsjail + `Failed to mount mandatory point: '/proc'`. Caused by the systemd + unit's `ProtectKernelTunables=true` overmounting `/proc/sys`, which + blocks nsjail's procfs mount inside its user namespace. The shipped + unit (`scripts/install.sh`) no longer sets this; if you have an older + unit, remove the `ProtectKernelTunables=true` line and + `systemctl daemon-reload && systemctl restart orva`. +- **cgroup controllers not delegated.** When systemd doesn't delegate + the cgroup v2 controllers to the service (constrained/cloud VMs), + Orva now logs `cgroup v2 controllers not delegated; per-sandbox + memory/pid/cpu caps disabled (rlimit-only fallback)` at startup and + runs functions **without** hard per-sandbox memory caps rather than + crashing. Older builds crashed every worker here — upgrade to fix. + +Quick confirmation that nsjail itself works on the host: +`sudo -u orva nsjail -Mo --chroot /var/lib/orva/rootfs/node -T /tmp -- /usr/local/bin/node --version` +should print the Node version. + ## Symptom: deploys stuck in `building` forever **Diagnosis.** diff --git a/docs/reference.md b/docs/reference.md index 3cd7889..6198a07 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1581,6 +1581,8 @@ orva system health # smoke test | `orva keys` | list / create / revoke | Manage API keys | | `orva activity` | [--tail] [--source web|api|...] | Paginated activity rows; live SSE with --tail | | `orva system` | health / metrics / db-stats / vacuum | Server diagnostics | +| `orva chat` | [-p MSG] | Chat with the AI assistant — interactive REPL or one-shot | +| `orva docs` | [--raw] | Render this reference in the terminal | | `orva setup` | [--skip-nsjail] [--skip-rootfs] | Install nsjail + rootfs on a bare host | | `orva serve` | [--port N] | Run as the server daemon (not the CLI client) | | `orva completion` | bash / zsh / fish / powershell | Emit shell completion script | diff --git a/frontend/public/docs.md b/frontend/public/docs.md index 3cd7889..6198a07 100644 --- a/frontend/public/docs.md +++ b/frontend/public/docs.md @@ -1581,6 +1581,8 @@ orva system health # smoke test | `orva keys` | list / create / revoke | Manage API keys | | `orva activity` | [--tail] [--source web|api|...] | Paginated activity rows; live SSE with --tail | | `orva system` | health / metrics / db-stats / vacuum | Server diagnostics | +| `orva chat` | [-p MSG] | Chat with the AI assistant — interactive REPL or one-shot | +| `orva docs` | [--raw] | Render this reference in the terminal | | `orva setup` | [--skip-nsjail] [--skip-rootfs] | Install nsjail + rootfs on a bare host | | `orva serve` | [--port N] | Run as the server daemon (not the CLI client) | | `orva completion` | bash / zsh / fish / powershell | Emit shell completion script | From 6f946b026605c3e13387b39d8071499ca9f0c77b Mon Sep 17 00:00:00 2001 From: Harsh-2002 Date: Fri, 5 Jun 2026 05:12:33 +0000 Subject: [PATCH 2/2] docs: fix stale runtime badges + build-toolchain versions - README badges showed Node.js 22|24 and Python 3.13|3.14 (URL-encoded, so the earlier sweep missed them) -> Node.js 24, Python 3.14. - README + CONTRIBUTING build requirements: Go 1.25+/Node 22+ -> Go 1.26+/Node 24+ (the embedded AI gateway requires Go 1.26; UI build toolchain is Node 24). --- README.md | 6 +++--- docs/CONTRIBUTING.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 50e72e3..9ebfd27 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fharsh--2002%2Forva-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/Harsh-2002/Orva/pkgs/container/orva) [![License](https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square)](LICENSE) [![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev) -[![Node](https://img.shields.io/badge/Node.js-22%20%7C%2024-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org) -[![Python](https://img.shields.io/badge/Python-3.13%20%7C%203.14-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org) +[![Node](https://img.shields.io/badge/Node.js-24-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org) +[![Python](https://img.shields.io/badge/Python-3.14-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org) **Self-hosted Functions-as-a-Service for your homelab or on-prem server.** @@ -369,7 +369,7 @@ make build-all # production binary → ./build/orva make test # go test ./... ``` -Requires Go 1.25+, Node 22+, and nsjail on Linux for sandbox invocations. +Requires Go 1.26+, Node 24+, and nsjail on Linux for sandbox invocations. --- diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 83e9e25..287c18b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -13,8 +13,8 @@ make dev # frontend on :5173 with hot reload, backend on :8443 Requires: -- **Go 1.25+** -- **Node 22+** +- **Go 1.26+** (the embedded AI gateway requires it) +- **Node 24+** - **nsjail** on PATH — easy install: `make build-nsjail` (clones google/nsjail, builds with apt deps; needs `libprotobuf-dev`, `libnl-route-3-dev`, `bison`, `flex`).