graycore

# Graycore Graycore is an open-source stack for building software with AI agents — self-hosted, MIT-licensed, and wired to the AI subscription you already pay for. Everything rests on one pairing: an **agent** and its **app**. You create an agent; it builds and owns an app. The agent is durable — files, skills, and memory that survive every session — and the app is whatever you need to exist: a tool for yourself, an automation for your business, a product you sell. Private by default, always connected to its agent, yours entirely. Think Replit or Lovable, but agent-native and on your own machine: no platform between you and your software, no second AI bill, nothing you build living on someone else's servers. The goal is an open ecosystem of apps — open-source and paid, built by humans and agents together — on a foundation sound enough for any agentic app, any agent, any software. ## How it works A Graycore workspace is a **capability host**: files served behind exactly one wire tool, `execute`. Capability grows by declaring files — agents, apps, skills, toolkits, Types — never by adding tools; the engine owns mechanism (storage, type enforcement, sandbox, governance), the workspace owns material. The model-facing surface (`/mcp`) never grows; the human-facing surface (`/api`) feeds a dashboard that renders the workspace and its apps live. Full model: [docs/vision.md](docs/vision.md). > Status: orientation (`ground()`) is currently paused while it is redesigned — scope is narrowed to `execute` + executor wiring. Restoring it is one env var (`GRAYCORE_GROUNDING_INDEX=1`); every call site stays valid. What ships *into* every new workspace lives in [`seed/`](seed/) — runtime product, not docs: [`seed/AGENTS.md`](seed/AGENTS.md) is the typed default agent a fresh workspace boots as. ## Map | Path | What lives there | | --- | --- | | [`code/`](code/) | Engine source — npm workspace; every dev command runs from here | | [`code/packages/graycore/`](code/packages/graycore/) | The SDK (`@graycore/sdk`): runtime, storage, typed index, governance, sandbox dispatch — start at [`mcp-server.ts`](code/packages/graycore/mcp-server.ts) | | [`code/packages/node/`](code/packages/node/) | The shipping engine (`graycore` on npm): CLI, stdio/HTTP serving, multi-workspace host | | [`app/`](app/) | Dashboard — browser chat + apps over `/api`; `app/server` (BFF) + `app/web` (React) | | [`backend/`](backend/) | Effect backend, including the cross-core delegation server `@graycore/intercore` | | [`seed/`](seed/) | The tree `graycore init` copies into every new workspace | | [`docs/`](docs/) | [vision](docs/vision.md) · [intercore](docs/intercore.md) · [deployment](docs/deployment.md) | ## Working on the engine ```bash cd code && npm install && npm run ci ``` That command is the gate — green before a change is done. (Known noise: 3 macOS realpath failures in `vcs-toolkit.test.ts`; 5s loopback-bind timeouts can flake on a loaded machine.) **The code is the source of truth**: conventions are enforced by the gate's own configs, not prose. Rules the compiler cannot enforce: - Effect only inside named adapter modules; never regex error prose to recover structure — use the one exhaustive mapper. - Cancellation and timeouts are distinct planes; thread `AbortSignal`. - `seed/` ships verbatim into strangers' workspaces: no person, host, port, or outside path, ever. - Never weaken a gate or a source type to make a test green. Tests are a regression net for the product surface: drive a real MCP client, HTTP request, or toolkit dispatch and assert observable behavior. Every test must fail on a realistic bug; deleting obsolete tests is expected. ## Deploying ```bash cd code && npm install && npm run build -w graycore # build the CLI first (Node >= 24 + build-essential python3) graycore deploy init --name <name> --workspace-root <path> --source-root <checkout> --components both graycore deploy apply --name <name> ``` `--components both` (the default) deploys engine + dashboard together — a dashboard with no engine looks healthy while every app surface renders empty. For a verified foreground stack during development use `graycore up --dashboard`. Full lifecycle — plan, update, status, logs, doctor, health-gated rollback: [docs/deployment.md](docs/deployment.md). ## Collaborating `main` is the source of truth; branch as `<agent>/<topic>` from fresh `origin/main`. Never `git reset --hard` or `git clean -fdx` in a tree that may hold work you did not write — integrate with `git fetch && git merge origin/main`.