Intent. Execution. Evidence.

Rust VM · repository guide

rust-stark-zkvm

www.zkvm.host STARK-Verifiable Virtual Machine for Provable Computation

A small, real zero-knowledge virtual machine: an interpreter, a STARK arithmetization (AIR), and a prover/verifier built on Winterfell. It executes ADD/SUB/MUL programs with real conditional control flow (JZ/JNZ) and a small fixed register file (LOAD/STORE), and produces a STARK proof that a specific program — including which branch it took and which register it touched — was executed correctly.

See ZZTOKEN0ZZ for what this does and — just as importantly — does not cover yet, and how it relates to the larger multi-phase strategy it grew out of.

Layout

• ZZTOKEN0ZZ — the VM: instruction set, interpreter, .zkasm parser.
• ZZTOKEN0ZZ — the AIR, prover, and verifier.
• ZZTOKEN0ZZ — the zkvm command-line tool (run, prove,

verify, deploy, demo).

• ZZTOKEN0ZZ — an HTTP proving service:

POST /v1/proofs to push a program and get a proof back, POST /v1/verify to check one, plus a ProverBackend-trait-based /v1/backends* surface for routing to more than one prover (today: the real stark backend and an honestly-labeled mock-echo stub). Also exposes prove/verify as real MCP tools (port 4478) for MCP clients like Claude or Cursor. See ZZTOKEN8ZZ for exactly how this relates (and doesn't) to the larger "zkvm.host" pitch it's named after — including a from-first-principles investigation of what a real SP1 backend would actually take.

• ZZTOKEN0ZZ — a Foundry project: an on-chain task/reward orchestrator

with a pluggable, honestly-scoped proof verifier (see ZZTOKEN0ZZ for what a *real* on-chain STARK verifier would additionally require).

• ZZTOKEN0ZZ — wires the two together: a

real proof from the real server gets attested and paid out on a local chain, end to end.

• ZZTOKEN0ZZ — "proof as a CI

check": every PR touching the VM, server, CLI, or contracts builds, tests, then deploys and verifies every example program against a live server.

• ZZTOKEN0ZZ — connect Claude Desktop, Cursor, or any MCP client

straight to the prover; ZZTOKEN0ZZ — what's trustless here (the proof) versus what isn't yet (the on-chain payment); ZZTOKEN1ZZ — a literature-review scope (not an implementation) of what making the on-chain path trustless would actually require.

• ZZTOKEN0ZZ — sample .zkasm programs, including

ZZTOKEN0ZZ and ZZTOKEN1ZZ.

Quick start

cargo build --release
cargo test --release --workspace

Use --release for tests, not just binaries: one of zkvm-stark's constraints has a data-dependent polynomial degree (see the comment in evaluate_transition), which trips a Winterfell debug-only self-check that's stricter than actual soundness requires. --release compiles that check out; it isn't hiding a real bug (all the same tests pass either way once that specific assertion is skipped) — see the code comment for the full explanation.

# run the full execute -> prove -> verify -> tamper-check demo
cargo run --release -p zkvm-cli -- demo

# or drive it by hand
cargo run --release -p zkvm-cli -- run    examples/fibonacci_like.zkasm
cargo run --release -p zkvm-cli -- prove  examples/fibonacci_like.zkasm out.proof
cargo run --release -p zkvm-cli -- verify examples/fibonacci_like.zkasm out.proof

# a program whose result depends on runtime control flow, not just arithmetic
cargo run --release -p zkvm-cli -- run examples/branching.zkasm

# a program that holds a value in a register across unrelated arithmetic
cargo run --release -p zkvm-cli -- run examples/counter.zkasm

# or "push code, get a proof" over HTTP instead of proving locally
cargo run --release -p zkvm-host-server &           # listens on :4477
cargo run --release -p zkvm-cli -- deploy examples/fibonacci_like.zkasm
cargo run --release -p zkvm-cli -- verify examples/fibonacci_like.zkasm examples/fibonacci_like.zkasm.proof

# and the on-chain orchestrator (Foundry)
cd contracts && forge test

# or the full loop: a real proof, paid out on a local chain
./scripts/onchain_demo.sh

# or talk to it over MCP (see docs/MCP.md)
cargo build --release -p zkvm-host-server && ./scripts/mcp_demo.sh

The .zkasm format

INIT 5      # starting accumulator value
ADD 3       # acc = acc + 3
STORE r0    # registers[0] = acc
JZ done     # forward jump to a label, taken if acc == 0
MUL 2       # acc = acc * 2
LOAD r0     # acc = registers[0]
done:
SUB 4       # acc = acc - 4

JZ/JNZ targets are labels, resolved at parse time, and must jump forward only — see ZZTOKEN2ZZ for why loops aren't supported yet. LOAD/STORE address one of a small, fixed set of registers (r0..r3) — scratch space for holding a second live value across arithmetic, not general-purpose memory (there's no dynamic addressing yet; see docs/ROADMAP.md).

How the proof actually binds to the program

Each trace row has one row per *static* instruction (never revisited — see above), holding the accumulator value, the four register values, seven one-hot opcode selectors (s_add, s_sub, s_mul, s_jz, s_jnz, s_load, s_store), the shared immediate/target/register operand, an active flag (did this row actually run, or was it skipped by an earlier taken jump), and a one-hot reg_sel (which register a LOAD/STORE addresses).

Every column except the accumulator and the registers — including active and reg_sel — is individually asserted (as a boundary constraint) against the specific program *and its actual execution*, for every row, not just the first and last. That's sound without an algebraic is-zero/lookup gadget deriving branch outcomes or a mux selecting a register, specifically because this system has no private witness: the verifier already re-executes the program to know the correct value for every row (see the doc comment at the top of zkvm-stark/src/lib.rs for the full argument). The things that *are* checked algebraically, via the AIR's transition constraints, are whether the accumulator's and each register's trajectory are consistent with that already-known-correct (opcode, active, reg_sel) sequence.

A prover cannot swap in a different sequence of instructions, a different control-flow outcome, or a different register access, for the same instructions, and still produce a proof that verifies. zkvm-stark's test suite checks this directly: tampering with the claimed result, program, active flags, or register selectors after proof generation causes verification to fail.

Contributing

Bug reports, .zkasm programs that break something, and small honestly-scoped PRs are welcome — see ZZTOKEN1ZZ for setup and the PR checklist. Found a soundness or security issue? Read ZZTOKEN2ZZ before filing a public issue. This project follows the Contributor Covenant. See ZZTOKEN3ZZ for release history.

Funding

Sponsorship, one-time crypto donations (ETH, USDT, OP, ARB, FIL, BTC, SOL), and a list of real grant programs this project could reasonably apply to are at ZZTOKEN0ZZ — or use the "Sponsor" button GitHub shows on this repo. See ZZTOKEN1ZZ for the one-page case made to grant reviewers specifically.

Python mesh · repository guide

decentralized.hosting

A working local MVP of an open-source, decentralized hosting mesh: a FastAPI control plane, a Docker-based node agent, a Traefik edge proxy, a local container registry, a dhost CLI, and an optional Solana-devnet node-operator credit system.

This is Phase 1 and 2 of the live roadmap — a real, runnable mesh, not a mockup. Confidential-computing enclaves and an optional mainnet credit migration are later phases.

Why decentralized.host?

• No vendor lock-in — standard Docker containers, your own server, no proprietary APIs to migrate off of later.
• No platform markup — the software is free (MIT); you pay only your own VPS/hardware provider, same as running anything else yourself.
• Multi-node scheduling — deploy across whatever machines you register to your own mesh, scheduled by live CPU/RAM load.
• Open source, no open-core trap — every capability described here is in this repository, not gated behind a paid tier.

Project facts (machine-readable)

project:
  name: decentralized.host
  category:
    - decentralized hosting
    - self-hosted PaaS
    - distributed compute
  license: MIT
  status: Phase 1 and 2 complete (see roadmap)

interfaces:
  - CLI (dhost)
  - REST API
  - Git SSH
  - Web console (dashboard/)

core:
  control_plane: FastAPI
  database: PostgreSQL
  runtime: Docker
  edge_router: Traefik
  language: Python

capabilities:
  - application deployment (git push or CLI)
  - resource-aware multi-node scheduling
  - server-side container builds (no local Docker needed)
  - deployment history and rollback
  - automatic Let's Encrypt TLS in production

blockchain:
  network: Solana
  status: optional, off by default
  environment: devnet only (no real funds)

Architecture

dhost CLI --snapshot+upload--> Control Plane --forward--> Node Agent --build/run--> App Container
   |         (no Git, no                                        |                        |
   |          local Docker)                                     +----heartbeat-----> Control Plane
   |                                                                                       |
   +----ship/update/history/rollback/status/logs----------------------------------------> |
                                                                                            |
                                                                    +--(N heartbeats)--> Solana devnet (credits)

Traefik routes app.127.0.0.1.nip.io -> the container the node agent just started

• control-plane/ — FastAPI + PostgreSQL. Issues JWTs to nodes, schedules

deployments onto the least-loaded healthy node, tracks state, proxies source uploads to the right node agent to build.

• node-agent/ — Runs on the host Docker daemon (via the mounted

socket). Registers, sends heartbeats, builds images from uploaded source (/build), runs containers, writes Traefik's routing config.

• cli/ — The dhost command: ship, update, history, rollback,

status, logs, node join, node list, wallet, credits, keys add/keys list, clone-url (plus the older init/deploy, kept for anyone who wants to build locally — see below).

• git-server/ — A real SSH git server: git push to auto-create a repo

and deploy it, no separate CI config. See "Real git push deploys" below.

• blockchain/ — Solana devnet integration for node-operator credits.

Optional, feature-flagged, fully documented in blockchain/README.md.

• mcp-server/ — An MCP server exposing the control plane's real API as

tools (list/inspect deployments, logs, nodes, release/engine history, ship, delete) for Claude or any MCP client. Fully documented in mcp-server/README.md.

• web/ — The original single-page landing page. Still shippable through

the mesh (cd web && dhost ship opengit-site --port 80) as a live example of self-hosting, but no longer the canonical public site.

• marketing-site/ — The real public site: a React/Vite/TypeScript SEO

content site (docs, guides, architecture explainer, honest competitor comparisons with evidence sources, an interactive deployment simulator). Meant for www.decentralized.host via Vercel — a legitimate static-hosting use case, distinct from the mesh itself. npm install && npm run dev inside the directory; npm run build for a static dist/. Every claimStatus/codeSource field in its content data cites real files in this repo. It shipped with fabricated testimonials, fake case studies, and several fictional CLI commands/config formats (dhost login, dhost.yml, --repo/--node flags, an install.sh) — all removed or corrected to match what's actually built; see the commit history for specifics if you're curious what changed.

• dashboard/ — OpenGit Console: a single-page web dashboard (vanilla

JS, no build step) at http://localhost:4001. Dashboard, Deployments (with live logs and teardown), Git Manager (real release history — every dhost ship/update/Launchpad ship records a Release row in Postgres with its message, snapshot id, and status), Mesh Nodes, Credits, Settings, and a Launchpad — drag a project folder into the browser and it's detected, previewed (with an optional real Gemini note if GOOGLE_API_KEY is set on the control plane), and shipped through the exact same /deployments/ship pipeline as the CLI. No Dockerfile written to your repo, no local Docker or Git involved either way. A Sandbox tab lists 100 well-known open-source self-hosting tools (dashboard/public/sandbox-catalog.js) — 17 of them genuinely deploy with one click through the real POST /deployments endpoint (an existing pre-built image, no build step, same pipeline any deployment here uses), each individually verified to actually boot; the other 83 are reference entries with the specific real reason they don't fit a single-click container (needs a cluster, needs launch arguments this mesh's deploy pipeline can't pass through, exceeds the mesh's fixed 256MB per-container memory limit, etc.) — never a vague "coming soon." No Analytics or chat-based AI Assistant pages — those would need fabricated data or a much bigger feature (a tool-using conversational agent) than "dashboard," so they were left out rather than faked. Protected by HTTP Basic Auth (dashboard/nginx.conf) when exposed beyond localhost — generate your own dashboard/.htpasswd with htpasswd -c dashboard/.htpasswd admin (from the apache2-utils/httpd-tools package); it's gitignored, not shipped in the repo.

Quick start

Requires Docker (with Compose) running locally — on the machine running the mesh. The developer's own machine does not need Docker or Git installed to use dhost ship.

# 1. Bring up the mesh (postgres, registry, traefik, control-plane, one node-agent)
docker compose up -d --build

# 2. Install the CLI
pip install -e ./cli

# 3. Confirm the mesh is healthy
dhost node list

# 4. Ship a sample app -- no Dockerfile written to disk, no git repo, no local docker build
cd examples/hello-world
dhost ship hello-world

Once it reports "Live", visit the printed URL (http://hello-world.127.0.0.1.nip.io) — this is a real public DNS name that resolves to 127.0.0.1 (via the free nip.io wildcard DNS service), routed by Traefik to the container the node agent just built and started.

Made a change? dhost update "what changed" snapshots and redeploys. dhost history lists every snapshot; dhost rollback <snapshot-id> restores and redeploys an older one. None of this touches git — see cli/dhost/ledger.py for the real (SHA-256 content-addressed) versioning underneath, and node-agent/agent.py's build_and_run for the server-side build that means your machine never runs docker build.

Check dhost status hello-world and dhost logs hello-world to see it end-to-end.

The older init / deploy path

Still there, still works, for anyone who'd rather build locally: dhost init writes a real Dockerfile into your project and dhost deploy <name> runs docker build/docker push on your own machine before scheduling it. ship/update don't use either of those — the Dockerfile is generated in memory and shipped over the wire, never written to your repo unless you ask for it via init.

The landing page itself is hosted the same way: cd web && dhost ship opengit-site --port 80, then visit http://opengit-site.<BASE_DOMAIN>. This project dogfoods itself rather than running its own site on a special-cased container.

AI assistant (optional)

A real chat assistant in the console's Assistant tab -- one model (Gemini, same GOOGLE_API_KEY as the Launchpad's stack notes), not a router across "100 free models." It has read-only tool access to actual deployment status, logs, node health, and release history (control-plane/app/routers/assistant.py) -- it cannot deploy, delete, or change anything, and it's instructed to say so and point at the right CLI command instead if asked to. Off by default; the console shows "not configured" honestly rather than a fake response when no key is set.

# in .env
GOOGLE_API_KEY=your-real-key
docker compose restart control-plane

SEO files for static sites

Any deployment the build detects as a static site (an index.html at the root) gets a real sitemap.xml (every .html file it actually finds, correct scheme/domain for the environment) and robots.txt generated automatically on build, unless the project already has its own — see _maybe_generate_seo_files in node-agent/agent.py. Nothing is fabricated or auto-applied to non-static apps: there's no way to know a Python/Node backend's real routes without introspecting it, so this deliberately doesn't try.

Real git push deploys

A real SSH git server, not the Git-free ledger path above — the two are independent front doors into the same build pipeline. First register a key, then push:

dhost keys add my-laptop ~/.ssh/id_ed25519.pub   # takes up to 30s to sync
dhost clone-url my-app                            # prints the remote URL + setup commands

cd my-app
git remote add opengit ssh://git@localhost:2222/repos/my-app.git
git push opengit main

First push auto-creates the repo and deploys it; every push after that redeploys. No .opengit.yml needed for the common case (port 8080, <name>.<BASE_DOMAIN>) — add one at the repo root only to override:

port: 3000
domain: custom.example.com   # optional, same override dhost ship --domain provides

Deploys whatever branch you push, single-branch-is-live (like a classic Heroku git remote) — there's no multi-branch preview-environment support in this version. Auth is the same single-shared-secret model as the rest of the mesh: any registered key can push to any repo, no per-repo ACLs.

Node-operator credits (optional)

Off by default. To turn on real Solana-devnet credit minting, see blockchain/README.md — short version:

pip install -r blockchain/requirements.txt
python blockchain/scripts/setup_devnet.py
# copy the printed mint address into .env, set ENABLE_BLOCKCHAIN=true
docker compose restart control-plane
dhost wallet <node_id> <your-devnet-wallet-pubkey>

Adding a second node

For another container on this same Docker daemon (quick local testing):

dhost node join --node-name node-2
dhost node list   # should now show two healthy nodes

For a genuinely separate machine, the control plane now tracks each node's own reachable address (Node.advertise_address) and always talks to the specific node a deployment landed on — earlier versions of this project hardcoded one global node-agent URL, which would have silently misrouted builds/logs/teardown to the wrong machine the moment a second *real* node existed. Run the agent directly on the remote machine:

docker run -d --name dhost-node-agent \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CONTROL_PLANE_URL=https://api.<your-domain> \
  -e NODE_JOIN_SECRET=<your real NODE_JOIN_SECRET> \
  -e NODE_NAME=node-2 \
  -e ADVERTISE_ADDRESS=<this machine's reachable host>:8100 \
  -p 8100:8100 \
  dhost/node-agent:latest

ADVERTISE_ADDRESS must be reachable *from the control plane*, not from you — a public IP/hostname for a real remote box, or the Docker network hostname for same-compose testing (the default). The scheduler picks whichever healthy node has the lowest combined CPU+RAM load.

Keeping the mesh up

Two independent checks, for two different failure modes:

• .github/workflows/mesh-health-check.yml — a scheduled GitHub Actions

job (daily, plus manual workflow_dispatch) that curls the public mesh hostnames from outside and fails loudly if any of them are down. External and read-only — it can observe the mesh but can't fix anything on the machine it runs on.

• scripts/mesh-watchdog.sh — a local script that checks Colima and

every dhost-* container on this machine and restarts what it finds stopped. Exists because Colima was found stopping unpredictably (silently, twice within an hour) while the Cloudflare Tunnel in front of it stayed up — every request just 502'd until someone checked by hand. Install it as a per-user LaunchAgent (runs every 15 minutes, no sudo) with:

  bash scripts/install-mesh-watchdog.sh

Logs to ~/Library/Logs/dhost-mesh-watchdog.log. Re-run the installer after editing scripts/mesh-watchdog.sh — it runs from an installed copy under ~/Library/Application Support, not from this checkout, since launchd can't read files under ~/Desktop on this Mac.

Configuration

All runtime config lives in .env (copy .env.example if you don't have one). Notable knobs:

These are dev-friendly defaults, not production secrets — rotate SECRET_KEY, NODE_JOIN_SECRET, and DEPLOY_API_KEY before exposing this beyond your own machine.

What's not real yet

Being upfront about scope, matching the roadmap on the landing page:

• Docker is still the container runtime — ship/update remove Docker

from the *developer's* machine, but the mesh itself (the node agent) still uses Docker internally to build and run containers, the same way most "no Docker" PaaS products work under the hood. This project does not reimplement a container runtime from scratch — doing that safely (namespaces, cgroups, image layering, sandboxing) is a much bigger undertaking than is reasonable here, and a half-built version of it would be a real security downgrade from what Docker already gives us.

• Single-machine by default — dhost node join still runs another

agent container on the same Docker daemon for quick local testing. Real multi-machine now works (each node reports its own reachable address and the control plane addresses that node specifically — see "Adding a second node"), but it hasn't been tested against an actual second physical/cloud machine, only reasoned through and code-reviewed.

• No real TLS/Let's Encrypt for local dev — nip.io + Traefik gets you

real routing, not HTTPS. Production deploys (docker-compose.prod.yml, see DEPLOY.md) do get real Let's Encrypt certs.

• No per-user accounts/RBAC — one shared deploy key, one shared node join

secret, and (new) any registered SSH key can push to any repo. Fine for a single operator running their own mesh, not for a multi-tenant service.

• The git server has no multi-branch preview environments, no per-repo

access control, and deploys whatever branch you last pushed — a single shared "production" per repo, not a full CI/CD system.

• Credits run on Solana devnet only, by design (see

blockchain/README.md for why).

Documentation

• DEPLOY.md — production deployment (real TLS, custom domains)
• blockchain/README.md — Solana devnet node-operator credits
• SECURITY.md — reporting a vulnerability
• CONTRIBUTING.md — running this locally to make a change
• Full docs, guides, and API reference: decentralized.host/docs/
• Live roadmap: decentralized.host/roadmap/

License

MIT. See LICENSE.

AgentSwarm · repository guide

AgentSwarm.in — Live Mission Control

One goal. A governed swarm. Verified work.

This branch upgrades the original AgentSwarm demo into a real full-stack execution path:

React Command Centre
        ↓ HTTP / SSE
Fastify Mission API
        ↓
PostgreSQL durable state + event store
        ↓
Worker / Scheduler
        ↓
Qwen Model Studio (OpenAI-compatible API)
        ↓
Task outputs → Artifacts
        ↓
Verification
        ↓
Mission completion

There is no client-side timer/random-number mission engine. The frontend renders persisted backend state and receives runtime events over SSE.

Truth model

• LIVE — a request/operation actually succeeded.
• CONFIGURED — credentials/configuration exist but a specific operation may not yet have run.
• UNAVAILABLE — a required integration is not configured.
• UNKNOWN — the upstream system did not provide the value.
• ERROR — a real operation failed.

The UI never guesses token usage or cost. If Qwen does not return usage, it is shown as unknown. Actual billing cost is not fabricated.

Requirements

• Node.js 20+
• Docker (for local PostgreSQL + Redis) — or local installs of both; the stack was developed and verified against Homebrew-installed Postgres 17 and Redis 8, no Docker required
• A Qwen / Alibaba Cloud Model Studio API key and OpenAI-compatible base URL for live model execution

Quick start

cp .env.example .env
docker compose up -d
npm install
npm run migrate
npm run dev

Open http://localhost:5173.

Configure Qwen

Set these server-side values in .env:

QWEN_API_KEY=...
QWEN_BASE_URL=https://<your-workspace-or-region-endpoint>/compatible-mode/v1
QWEN_MODEL=qwen-plus

If Qwen is not configured, a new mission is persisted but moves to BLOCKED with provider status UNAVAILABLE. It is never simulated.

Services

apps/web      React/Vite Command Centre
apps/api      Fastify REST + SSE API
apps/worker   durable mission planner/executor
infra         PostgreSQL migration
scripts       migration runner

Mission lifecycle

QUEUED
→ PLANNING
→ RUNNING
→ WAITING_APPROVAL (when required)
→ RUNNING
→ VERIFYING
→ COMPLETED

Terminal/control states include PAUSED, FAILED, CANCELLED, and BLOCKED.

Task lifecycle

QUEUED
→ READY
→ LEASED
→ RUNNING
→ SUCCEEDED

Optional states: WAITING_APPROVAL, RETRY_WAIT, FAILED, CANCELLED, DEAD_LETTER.

Leases are persisted in PostgreSQL; expired leases are recovered by the worker. Retries are bounded by MAX_TASK_ATTEMPTS.

Durable dispatch (Redis/BullMQ + Postgres)

Postgres remains the sole source of mission/task truth — this was true before Redis existed in this stack and hasn't changed. FOR UPDATE SKIP LOCKED is what actually decides which worker process claims a given mission or task; it's safe for any number of concurrent workers by construction.

Redis/BullMQ adds a low-latency wake-up signal on top of that, nothing more:

• After a Postgres transaction commits (mission created, task promoted to READY, a retry/lease-expiry recovery, an approval granted), the API/worker enqueues a lightweight BullMQ job.
• The worker's Worker consumer reacts to jobs by attempting the same claim-and-process logic — the job payload is a *hint*, not an instruction, so a stale, duplicate, or dropped job can never cause duplicate or incorrect execution.
• A slow fallback poll (WORKER_FALLBACK_POLL_MS, default 5s) always runs independently of Redis, sweeping for retry-wait tasks, expired leases, and anything the queue missed.
• enqueue() is timeout-bounded (1.5s) and never holds an open Postgres client while it runs — verified by actually killing Redis mid-request and confirming the API responds in ~1.6s instead of hanging, and that a mission created during the outage still reaches BLOCKED/COMPLETED/etc. via the fallback poll alone.
• If REDIS_URL is unset, the worker runs in Postgres-poll-only mode — same correctness, just higher dispatch latency (up to WORKER_FALLBACK_POLL_MS).

This was verified end-to-end, not just written: mission creation during a real Redis outage, worker process killed and restarted mid-backlog (confirmed exactly one mission.planning_started event afterward — no duplicate processing), and Redis restarted and confirmed to reconnect automatically without a worker restart.

Realtime architecture

Every runtime event is inserted into the events table. A PostgreSQL trigger sends a NOTIFY; the API's SSE endpoint listens and streams matching events to connected clients. Reconnecting clients pass the last event ID and receive missed events from the durable event store.

Qwen execution

The worker uses the configured Qwen OpenAI-compatible chat-completions endpoint for:

1. mission planning;
2. specialist task execution.

Planner output is parsed and validated with Zod before task records are created. Model output never mutates mission state directly.

Approval gates

A task can declare requiresApproval and a risk level. The worker creates a persisted approval request and stops the task in WAITING_APPROVAL. The API is authoritative for approve/reject actions; deciding requires OPERATOR role or above in the mission's organization. Approval resumes the task; rejection fails the mission.

Auth & tenancy

Real, DB-backed authentication — no fabricated "logged in" state:

• Passwords hashed with bcrypt (bcryptjs, cost 12). Sessions are opaque random tokens; only a SHA-256 hash of the token is stored in sessions, with a 30-day expiry.
• The session token is set as an httpOnly, SameSite=Lax cookie (asw_session) — never exposed to client-side JS, never stored in localStorage.
• POST /auth/signup creates a User, an Organization (role OWNER), and a default Project in one transaction. POST /auth/login, POST /auth/logout, GET /me.
• Every mission belongs to exactly one organization_id + project_id, set server-side from a membership check — the client can request a project but can never assign a mission to an org it isn't a member of.
• All mission/approval routes require a valid session and verify org membership before returning data; a mission in an org you don't belong to returns 404 (not 403), so its existence isn't leaked to non-members.
• Roles are OWNER > ADMIN > OPERATOR > MEMBER > VIEWER. Creating a mission requires MEMBER+; deciding an approval requires OPERATOR+; creating a project requires ADMIN+.
• /auth/signup and /auth/login are rate-limited (8/min) via @fastify/rate-limit; the rest of the API defaults to 300/min per IP.

This covers the master build prompt's §34 auth requirements and the §55 Gate C / Gate K cross-org-isolation acceptance tests, verified with real signup/login/cross-org-access curl + browser tests (not just written, actually run). Not yet implemented: OAuth providers, password recovery, org invites (multi-member orgs), and CSRF tokens (currently relying on SameSite=Lax + credentialed CORS restricted to WEB_ORIGIN).

Verification

When every task succeeds, the mission enters VERIFYING. The current real verification gate checks that every succeeded task has a persisted artifact. Only then does the mission become COMPLETED.

This is deliberately minimal and truthful; build/typecheck/security tool gates can be added as real tool adapters rather than decorative green checks.

API

See ZZTOKEN0ZZ.

Current production boundary

This is a fully wired mission/API/model/event/artifact MVP with real auth, org/project tenancy, and durable Redis/Postgres dispatch, not the final enterprise control plane. Before exposing it publicly, still needed: OAuth/SSO, org invites, secret-vault integration (secrets currently come from server .env only), tool/MCP gateway, sandboxed task execution, richer verification gates (build/typecheck/security/a11y — today's gate only checks artifact existence), audit ledger, and deployment hardening (CSRF tokens, security headers, production TLS).

OM · repository guide

🕉 OM — Personal AI Operating Universe

A sovereign, self-hostable AI workspace for private agents, local model routing, durable knowledge and auditable execution.

Live workspace · Self-hosting · Architecture · Contributing · Security

What is OM?

OM is an open-source personal AI operating universe: one interface for missions, agents, notes, prompts, findings, local AI configuration and measured infrastructure health. It is designed for people who want an AI workspace they can inspect, operate and progressively move onto infrastructure they own.

OM is not presented as a fully autonomous production runtime. The interface distinguishes implemented workspace capabilities from external services that still require configuration, credentials or owned infrastructure.

Why OM?

• Sovereign by design — self-hostable application with explicit private-service boundaries.
• Local-model ready — configuration surfaces for Ollama and compatible model routers.
• Durable knowledge — D1/Drizzle-backed records for workspace data.
• Measured status — offline and setup-required services are shown honestly.
• Auditable direction — production-readiness milestones and verification criteria are built into the product.
• One workspace — command center, Kanban, projects, notes, prompts, findings and integrations.

Current capabilities

Architecture

Web / Desktop UI
  └─ Authenticated OM application
     ├─ D1 / SQL · workspace records
     ├─ Model router · Ollama / vLLM / opt-in cloud
     ├─ Vector memory · Qdrant
     ├─ Object storage · MinIO / S3
     └─ Sandbox worker · owned edge node

The repository currently uses Next.js 16, React 19, TypeScript, Vinext/Vite, Cloudflare Worker primitives, D1 and Drizzle ORM.

Quick start

Requirements

• Node.js 22.13 or newer
• npm
• Linux, WSL2 or a compatible environment with bash, flock and GNU timeout

Install and run

git clone https://github.com/CodesbyFebin/-Om-Personal-Ai.git
cd ./-Om-Personal-Ai
npm ci
npm run dev

Open the local URL printed by the development server.

Validate

npm run lint
npm test

Self-hosting

OM can be adapted for Cloudflare/Sites hosting or an owned deployment. A complete sovereign runtime additionally needs:

1. An authenticated model endpoint such as Ollama or vLLM.
2. Qdrant for semantic memory.
3. MinIO or another S3-compatible object store.
4. A sandboxed worker for agent execution.
5. Secret storage, rotation, backups and restore testing.
6. TLS, network policy and production monitoring.

Never commit secrets. Copy documented keys into a local .env that is excluded by .gitignore, or use your deployment platform's encrypted environment-variable store.

Repository map

app/        Application routes and UI
db/         D1 access and schema
drizzle/    Database migrations
public/     Public assets
scripts/    Reproducible install/build validation
selfhost/   Self-hosting resources
tests/      Rendered-output and build tests
worker/     Worker-side services

Frequently asked questions

Can OM run local LLMs?

OM includes configuration and status surfaces for local model routing. Actual inference requires a reachable Ollama, vLLM or compatible endpoint that you operate.

Is OM fully private by default?

The application is designed for private deployment, but privacy depends on your hosting, model providers, connectors and network configuration. Cloud integrations should be explicit opt-ins.

Does OM execute autonomous agents today?

The product includes mission, approval and activity interfaces. Secure autonomous execution requires an owned sandbox worker and must not be inferred from UI simulation alone.

What makes OM different from a chatbot?

OM combines AI interaction with project operations, persistent knowledge, infrastructure health, approvals and a roadmap toward verifiable self-hosted execution.

Roadmap

• Owned local/cloud model router with streaming and circuit breakers
• Hybrid SQL + Qdrant memory with citations
• Durable mission queue, leases and idempotent transitions
• Rootless sandbox execution on owned edge nodes
• Encrypted connector credentials and rotation
• Backup/restore and multi-user isolation tests

Progress should be accepted only with evidence from real services and tests.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md before proposing a change. Security reports belong in the private channel described in SECURITY.md.

License

Released under the MIT License.

Citation and discovery

For AI assistants and research tools, a concise project fact sheet is available in llms.txt. When describing OM, preserve the distinction between shipped application features and infrastructure that requires configuration.

Built by CodesbyFebin for a more inspectable, owner-controlled AI future.