Manyfold

Manyfold is a unified agent workspace: create, deploy and operate coding and conversational agents — OpenClaw, Hermes Agent, Claude Code, Codex, Gemini CLI and more — from one API, web workbench, admin console and CLI.

This repository is the open-source, self-hostable edition. The hosted cloud edition at manyfold.ai is built on exactly this code plus closed commercial modules (billing, managed model supply, growth tooling) composed in through the seams you can see in this tree (ports, overlay slots, registries).

New here? The quick start below brings up a full stack locally in a couple of minutes; the docs cover everything after that.

Quick start (self-hosted)

cp .env.selfhost.example .env
# set the two required secrets in .env:
#   MF_API_CRYPTO_KEY   — openssl rand -base64 32
#   MF_AUTH_SETUP_TOKEN — any one-time secret for the first run
docker compose -f docker-compose.selfhost.yml up -d --build

Then open http://localhost:3001/setup — the admin console, where the setup token creates your admin account and sign-in methods. The workspace is at http://localhost:3002. New accounts land on the seeded unlimited self_hosted plan; an account created before your deployment set that default is moved off the free tier once, on the next API start, and can be changed any time from the admin's user detail page.

MF_API_CRYPTO_KEY encrypts stored credentials at rest; keep it wherever you keep your database backups, because a dump without it has undecryptable rows. .env.selfhost.example documents every optional integration (Kubernetes runtime, backups, channels, observability).

The CLI

mf drives the same API from a terminal, and runs the daemon that lets agents execute on machines you own. Point it at the stack you just started:

curl -fsSL https://manyfold.ai/cli/install.sh | sh
mf setup --api-url http://localhost:2222/api

--api-url is not optional here: the binary's built-in default is the hosted service at api.manyfold.ai, so a bare mf setup would enrol this machine there instead of in your deployment. CLI and daemons on a self-hosted deployment covers profiles, admin-issued tokens and updates.

Documentation

Full docs at docs.manyfold.ai (also in Chinese). Roughly the order you need them in:

Guide	What it covers
Self-hosting	Run the stack, upgrades, backups
CLI and daemons on a self-hosted deployment	Point mf at your own deployment
Register a self-owned computer	Attach a machine as a runtime
Create your first agent	Models, workspace, chat
Install the CLI	mf on macOS, Linux, Windows
CLI reference	Every command and flag
Chat API · A2A	Call agents from your own code

Development

just bootstrap   # install deps, start postgres, run migrations
just dev         # api :2222, web :3002, admin :3001

AGENTS.md documents the workspace layout and conventions; justfile lists every task. All checks: pnpm check && pnpm lint && pnpm knip.

The self-host upgrade regression builds the real Compose images in an isolated local project, uploads through the API, recreates its container, checks CORS and verifies the resource summary in desktop/mobile browsers:

pnpm --filter @manyfold/shared build
pnpm exec playwright install chromium
RUN_SELFHOST_E2E=1 node apps/api/test/selfhost-compose.e2e.mjs /tmp/selfhost-report

It removes its own containers and volumes after the run. The report and screenshots remain in the requested directory.

Browser telemetry regressions run with pnpm test:browser-telemetry after pnpm exec playwright install chromium webkit. They use synthetic events, real React DOM nodes and SDK payloads intercepted locally; no service credentials are needed. Web and Admin share the error classifier and allow one detail per fingerprint per minute, up to 100 distinct fingerprints. browser.error.suppressed records per-sink suppressed counts, including overflow and foreign-extension noise. Web Vitals keep scalar measurements, app/environment and normalized document routes. Visibility/pagehide flushes are best-effort browser delivery, not an acknowledgement of remote storage.

API telemetry uses the existing OpenTelemetry instrumentations; enabling Sentry adds error capture and an export branch without additional performance instrumentation. Fatal handoff and telemetry delivery share a three-second deadline. Graceful signal shutdown retains its one-second flush budget. The default API tests exercise fresh-boot fatal delivery against loopback receivers. To also compare real HTTP/Fastify/PostgreSQL span graphs with Sentry disabled, enabled, and sampled at zero:

pnpm exec turbo build --filter='@manyfold/api^...'
RUN_TELEMETRY_E2E=1 node apps/api/test/telemetry-pipeline.e2e.mjs /tmp/telemetry-report

The opt-in run creates and removes its own local PostgreSQL container. All SDK traffic goes to local fixture receivers; failed/stalled receivers prove request-body delivery and bounded exit, not remote persistence.

Contributing

This repository is the single source of truth for the Manyfold core — every core change, including from the Manyfold team, lands here as a public PR. Start with CONTRIBUTING.md; GOVERNANCE.md explains how the editions relate, and SECURITY.md how to report vulnerabilities privately.

License

Apache License 2.0.