README.md
Rama main · réplica de lectura del repositorio original.
# BitCadence
**Every agent. One beat.**
[](https://github.com/mastalink/BitCadence/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
[](docs/INSTALL.md)
[](CHANGELOG.md)
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](docs/JEV-DECISION-PROVIDER.md).
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](docs/DESKTOP.md).
### macOS / Linux — one command
```bash
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.
```bash
# 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
# 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](docs/INSTALL.md)
### From source / Docker
```bash
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
```
```bash
# 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
```bash
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 (alex)
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](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](https://github.com/mastalink/BitCadence/issues) |
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/ENTERPRISE.md).
---
## Docs
- [docs/INSTALL.md](docs/INSTALL.md) — easy Windows install + first run + troubleshooting
- [docs/SETUP.md](docs/SETUP.md) — full multi-agent setup: Supabase schema, agent registration, MCP wiring
- [docs/DRUMLINE.md](docs/DRUMLINE.md) — shared memory: how it works, how to use it
- [docs/GOVERNANCE.md](docs/GOVERNANCE.md) — approval gates, audit trail, workflow DSL
- [docs/SCHEDULING.md](docs/SCHEDULING.md) — launchers, cron/interval schedules, bounded loops
- [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) — ServiceNow, Dynatrace, webhooks
- [docs/ENTERPRISE.md](docs/ENTERPRISE.md) — editions, scoped-token RBAC, SSO delegation
- [docs/SDK.md](docs/SDK.md) — write a custom agent/worker in fifteen lines
- [docs/AIRGAP.md](docs/AIRGAP.md) — fully offline install (zero data leaves your network)
- [docs/DEPLOYMENT.md](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 **security@bitcadence.ai** rather than opening a
public issue.
---
## License
Free for personal and noncommercial use under the [Prosperity Public License 3.0.0](LICENSE).
Businesses get a free 30-day trial, then a commercial license: see [COMMERCIAL-LICENSE.md](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.