BitCadence

Every agent. One beat.

A self-hosted orchestration hub for AI agents: a governed job board with human approval gates, an immutable audit trail, and Drumline — one shared memory every agent reads and writes. Runs entirely on your machine; no cloud account required. The optional TypeSafe/Jev integration adds bounded, typed routing advice; it does not replace deterministic policy or human approval. See the Jev setup and authority contract. Push alerts (ntfy) stay off until you set NTFY_TOPIC. Local-Only does not talk to ntfy.sh by default.

---

Install

For one Windows window and tray icon to manage the local server, scheduler, and workers, see the desktop manager guide.

macOS / Linux — one command

curl -sSf https://bitcadence.ai/install.sh | bash

Clones the repo to ~/BitCadence, finds/installs Python, creates the venv, generates your access token, adds mco to your PATH, then asks: demo mode or connect now. Takes about two minutes.

# If you already cloned:
bash scripts/install.sh

Windows — one double-click

Download the ZIP from GitHub, extract it anywhere, then double-click install.bat. It finds (or installs) Python, builds the venv, generates your access token, and drops a BitCadence shortcut on the Desktop. Your browser opens the console automatically.

# PowerShell one-liner (no ZIP download needed):
iwr -useb https://bitcadence.ai/install.ps1 | iex

# Or headless / CI:
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -NoPrompt

Full walkthrough and troubleshooting: docs/INSTALL.md

From source / Docker

git clone https://github.com/mastalink/BitCadence
pip install -e BitCadence
mco setup --guided    # configure in 60 seconds
mco start             # console at http://127.0.0.1:18789/console

# Docker (team / cloud):
docker compose up     # see docs/DEPLOYMENT.md

---

What it does

BitCadence sits between your agents and the work they do. It gives you:

Job board	Agents post work, workers lease atomically. Dependencies chain; no race conditions.
Drumline	One shared memory across the whole mesh. Completed jobs auto-distill into recallable handoffs.
Approval gates	Flag any job — or an entire role — to pause at needs_approval until a human decides.
Immutable audit	Every mutation appends to agent_job_events. UPDATE and DELETE are rejected at the storage layer.
Scheduling & loops	Cron/interval schedules and bounded loops — a loop must declare how it stops (count, deadline, or "until the queue is clear") or it's refused. Every scheduled job is stamped with what created it.
Encrypted secrets	Credentials encrypt by default (AES-256-GCM) — never silently written to .env in the clear. Auto-provisioned on Windows; explicit master password elsewhere.
Embedded store	No Supabase? An embedded SQLite store (~/.mco/local.db) takes over — the free edition is the full product.
Enterprise connectors	Ingest ServiceNow incidents and Dynatrace problems as jobs; act back with auditable, gated platform actions.
Console GUI	Zero-build web UI at /console — job board, approval queue, audit drawer, and "Ask for something": say what you want, check the drawn plan, approve once; plus plain-words Helpers (health light, confirm-first "Fix it"), Schedules ("Every weekday at 2 AM") and Settings pages.

---

Quick start

mco start             # start the gateway in the background (logs to ~/.mco/logs/gateway.log)
mco stop              # stop it
mco restart           # stop + start
mco serve             # foreground alternative (terminals, systemd, Docker)
mco service install   # run as a boot-persistent OS service (Task Scheduler / systemd / launchd)
mco doctor            # end-to-end install diagnosis
mco upgrade           # apply schema migrations (LocalStore needs none)
mco status            # config health check
mco setup             # guided walkthrough or settings menu
mco setup --guided    # hand-held, Enter at every prompt = working Local-Only install
mco setup --menu      # jump to one setting and get out
mco send codex -t "Summarize repo" -m "..."   # drop a job into a dropbox
mco listen --role codex --instance worker-1   # start a worker
mco audit <job_id>    # inspect a job's full history
mco approve <job_id>  # approve a gate
mco gui               # open the console in your browser
mco schedule init     # start declarative schedules & bounded loops
mco launch <name>     # fire a named launcher (job, workflow, app, or URL) now

Open http://127.0.0.1:18789/console in your browser, paste your access token (shown at startup, or in ~/.mco/.env), and click Connect — or just run mco gui. For the live workflow canvas, mco gui --flow.

---

Drumline — shared memory

In a marching band, the drumline keeps everyone in step. Here it does the same for agents: what one learns, every agent knows.

=== SHARED CONTEXT (Drumline) ===
- [handoff] Job outcome: Triage P-99 (claude-w1)
  Root cause: runaway cron. Disabled job foo.
- [fact] Prod DB read-only on Sundays (joe)
  Maintenance window 02:00-06:00 UTC.
=== END SHARED CONTEXT ===

• mco_remember / mco_recall — agents write facts and decisions
• Workers get relevant entries injected into their prompt before execution
• Works fully offline in the free Local-Only edition (SQLite, no vector DB)

Full spec: docs/DRUMLINE.md

---

Editions

	Community	Team	Enterprise
Drumline shared memory	✓	✓	✓
Job board, approvals, audit	✓	✓	✓
Console GUI & Ask for something	✓	✓	✓
Embedded SQLite (zero cloud)	✓	✓	✓
Multi-machine / Supabase	—	✓	✓
Multi-org isolation + scoped-token RBAC	—	✓	✓
Docker + any-cloud deploy	—	✓	✓
ServiceNow & Dynatrace connectors	—	—	✓
SSO via your reverse proxy (trusted headers)	—	—	✓
Pilot program	—	—	open an issue

One codebase, no separate builds: mco edition shows the active edition (inferred from your config, or pinned with MCO_EDITION). Details, scope vocabulary, and SSO setup: docs/ENTERPRISE.md.

---

Docs

• docs/INSTALL.md — easy Windows install + first run + troubleshooting
• docs/SETUP.md — full multi-agent setup: Supabase schema, agent registration, MCP wiring
• docs/DRUMLINE.md — shared memory: how it works, how to use it
• docs/GOVERNANCE.md — approval gates, audit trail, workflow DSL
• docs/SCHEDULING.md — launchers, cron/interval schedules, bounded loops
• docs/INTEGRATIONS.md — ServiceNow, Dynatrace, webhooks
• docs/ENTERPRISE.md — editions, scoped-token RBAC, SSO delegation
• docs/SDK.md — write a custom agent/worker in fifteen lines
• docs/AIRGAP.md — fully offline install (zero data leaves your network)
• docs/DEPLOYMENT.md — Docker, any-cloud, multi-tenancy

---

Observability

• /metrics — Prometheus exposition: jobs by status, approval queue depth, agents registered/online, kill-switch and database state. Open like /healthz by default; set MCO_METRICS_TOKEN to require a bearer token when the gateway is network-exposed.
• /healthz — unauthenticated liveness/readiness for load balancers. Right after Uvicorn prints running, /healthz and /console can 500 for ~10s (asyncio backend import). Retry until 200; do not treat the first 500 as death.
• MCO_LOG_JSON=true — one JSON object per log line for Loki / Datadog / CloudWatch ingestion.

---

Security

BitCadence binds to 127.0.0.1 by default — only your machine can reach it. Before exposing it on a network:

• Set a token. mco setup generates MCO_LOCAL_TOKEN; every request and WebSocket must present it. Binding to 0.0.0.0 without a token is unsafe.
• Keep the shell executor off. The standalone worker can run a shell command carried in a job, but only when you opt in with MCO_ENABLE_SHELL_EXECUTOR=1. Leave it unset unless you fully trust everyone who can post jobs; prefer typed executors (register_executor) instead.
• Credentials encrypt by default. Anything credential-shaped (API keys, tokens, passwords) goes to the AES-256-GCM secret store (~/.mco/secrets.enc), never silently to plaintext .env. On Windows the store is auto-provisioned (key held by Credential Manager); elsewhere set a master password via mco setup --menu → Security. Plaintext is only ever a deliberate, visible opt-out. Either way, keep secrets out of git.

Found a vulnerability? Email [email protected] rather than opening a public issue.

---

License

Free for personal and noncommercial use under the Prosperity Public License 3.0.0. Businesses get a free 30-day trial, then a commercial license: see COMMERCIAL-LICENSE.md. Releases up to and including 0.5.0rc1 were MIT and stay MIT for anyone who received them. Copyright (c) 2026 Batoncadence LLC.