Mycel

The open kernel for AI-native service businesses.

OpenCode in a sandbox. A human on every send.
Clients, cases, approvals, invoices — not another chat loop.

_{Ranked next moves on npm run demo:seed (Ridgeline Books). Filmed on Cloud against this kernel. The clone is headless — Cloud is a /v1 consumer, not in the repo.}

git clone https://github.com/mycelhq/mycel && cd mycel
npm i && npm test          # green. no keys, no Docker, no Postgres.

That is the whole first look. The suite drives the /v1 contract against a mock agent in-process.
If it is red, the clone is broken — not your machine.

Pre-alpha. The core is real and tested. APIs still move. Watch the repo; don't pin to it yet.
CHANGELOG.

What this is

Plenty of things run an LLM in a loop. Mycel is the operating system around that loop for a
firm that sells work: a client logs in, a job runs in a sandbox, nothing reaches the outside world
until a human approves, the artifact is a deliverable, the money is an invoice.

A wedge is a service as config — wedge.json + skills (how) + knowledge (what's true) — not a
fork of the engine. Bookkeeping, dunning, GEO, recruiting, and a contract desk all sit on the same
kernel.

The agent never holds a credential. It gets an opaque nonce. The harness holds the secret, shows
a preview, executes on approve, and writes an audit row. There is no code path from the sandbox to
the network that skips that gate.

flowchart LR
  API["Your API"] --> Box["Sandboxed OpenCode<br/>skills + knowledge · no secrets"]
  Box --> Gate["Human gate<br/>approve / edit / reject"]
  Gate --> Conn["Connection<br/>the real send"]

The secret never enters the box. The host of every write comes from the connection, not from the
agent.

Hosted Cloud (invite-only) is the commercial layer: mycelai.dev.
This repository is the kernel. Apache-2.0, self-host it.

Why not the thing you already have

If you want a generalist that runs your company from a chat, this is the wrong repo.
If you want the kernel under a service business you actually bill, it is the right one.

Try it (no keys)

npm run demo         # kernel on :4000, in-memory, mock runtime
npm run demo:seed    # another shell — builds "Ridgeline Books"

Five clients, invoices in every state, engagements, a wait blocked on a bank statement, ranked
moves derived from that state. There is no UI in this repository — Mycel is headless. The
console at :3000 is a separate consumer of the same contract, not part of the kernel. The GIF at
the top, and this invoice, are that consumer on this seed:

A business to look at

The seed writes into the owner's project. /v1 is project-scoped with no default, so read it
back as the owner, with that project's id. demo:seed prints the same command when it finishes.

LOGIN=$(curl -s localhost:4000/v1/auth/login -H 'content-type: application/json' \
  -d '{"email":"[email protected]","password":"demo-ridgeline"}')
TOKEN=$(echo "$LOGIN" | jq -r .token)
PROJECT=$(echo "$LOGIN" | jq -r '.projects[] | select(.name=="Ridgeline Books") | .id')

curl -s localhost:4000/v1/moves \
  -H "authorization: Bearer $TOKEN" -H "x-mycel-project: $PROJECT" | jq

mycel_demo_key will not show you this. That API key is a different tenant — it resolves
to its own key-derived project, so GET /v1/moves with it correctly returns {"moves":[]} even
after a successful seed. That is tenant isolation working, not a failed seed.

A task, from curl:

curl -X POST http://localhost:4000/v1/tasks \
  -H "authorization: Bearer $MYCEL_API_KEY" -H "content-type: application/json" \
  -d '{"wedge":"books-keeper","task_type":"chase_receipts","input":{"period":"2026-10"}}'

curl -N http://localhost:4000/v1/tasks/<id>/events \
  -H "authorization: Bearer $MYCEL_API_KEY"

Or: curl -fsSL https://mycelai.dev/init | bash — same tree, setup.sh writes the env.

Scaffold a product on the contract with npx create-mycel-app.

The [mock] trap (read this)

With MYCEL_RUNTIME=mock, every task succeeds — real schema, real contract — and every string
field is the literal [mock]. That is the fake runtime stamping a placeholder. It is not a broken
model.

The other first-run failure: defaults are opencode + local sandbox. No opencode binary → the
task sits on start_opencode for 60s, then opencode failed to start (no log). There is no log
because the process never existed.

Boot prints both. npm test and npm run demo use mock on purpose.

For a real agent: unset MYCEL_RUNTIME, install opencode-ai, put a provider key in .env.
setup.sh walks that.

What Mycel provides

Sellable wedges (config you can provision):

invoice-chaser, books-keeper, and contract-desk ship a blueprint (wedge + connections +
schedules in one POST).

Machinery (internal: true, not products): business-shaper (description → service definition),
harness-operator (the kernel on itself), product-builder (the founder's app).

A generated definition cannot author away its own gate — no required: false on approvals, no
executable workflow code, no raising harness ceilings. Promotion is a human.

The rest of the kernel

• Harness profiles (decide / operate / build) — toolset, budget, whether the box even gets an
  action token. Authored JSON cannot raise a ceiling; the plan clamps down.
• Connections: email, webhook, custom, composio (OAuth, 250+ toolkits), linkedin. Bind to
  capabilities (send_email, read_payments), not vendors.
• Hash-chained audit log. GET /v1/audit/verify names the first broken link.
• Stated vs observed knowledge — a founder claim that contradicts something the system watched is
  declined, not averaged.
• Autonomy that narrows itself on rejection rate and never widens itself.
• Postgres if MYCEL_DATABASE_URL is set; otherwise in-memory (fine for the first hour, gone on
  restart).

How to write a wedge: docs/WEDGES.md.
What the kernel still cannot express: docs/ROADMAP.md.

/v1 (server-to-server)

Auth   Authorization: Bearer <project key | member session>
       POST /v1/auth/login · GET /v1/me
Work   POST /v1/tasks · GET :id · GET :id/events (SSE) · POST :id/cancel
       POST /v1/approvals/:id/{approve,reject}
Who    clients · threads · cases · deliverables · invoices
Where  connections · channels · POST /v1/channels/:id/inbound
Wedge  GET /v1/wedges/:wedge · knowledge

Integration + honest security limits: docs/INTEGRATION.md.
Event reference: docs/CONTRACT.md.

Configure (env)

npm run dev loads .env if present. Real env wins. setup.sh writes that file.

Running with no keys, and the [mock] trap

The [mock] trap is documented under Try it, above. Defaults without an opencode binary hang
for 60s on start_opencode. npm test and npm run demo use mock on purpose.

Develop

npm i
npx tsc --noEmit
npm test
MYCEL_TEST_DATABASE_URL=postgres://... npm test   # durability

A handful of tests # SKIP with a reason naming a sibling that lives in the private monorepo and
is not published here. They skip rather than fail so a stranger's clone is green honestly.

Needs: Node 20+, git. Docker / Daytona / Postgres only if you choose those backends. Real runs
need an opencode binary and a provider key.

Principles

1. Grounded, not guessing. Skills + knowledge, not a naked prompt.
2. Draft-and-approve. Outward action pauses. Autonomy is earned, never self-widened.
3. Rented commodities. Swap sandbox or model with one env var.
4. Honest signals. Validated output, real failures, no fake successes. The [mock] stamp exists
   so mock cannot impersonate a model.
5. Contract over packages. No @mycel/react. Generate UI against /v1.

Layout

harness/      /v1, orchestrator, sandbox, gate, stores
wedges/       services as config (see table above)
blueprints/   wedge + connections + schedules
skills/       procedures the agent reads mid-run
docker/       sandbox image
docs/         contract, wedges, roadmap

License

Apache-2.0. Open-core: this kernel is free and self-hostable, with no metering, no seat
limit and no expiry — bring your own model key.

What that gets you: the /v1 contract, the harness, every gate, every service definition, and an
operator console to run and approve work from. What it does not: clients, engagements, invoices,
chasing, a client-facing portal, or the machinery for finding clients — that is the hosted product.

The line, and the three rules used to decide it, are written down in
docs/OPEN-CORE.md. Short version: the
engine is open, the firm is paid.

_{github.com/mycelhq/mycel · mycelai.dev}