ForkMesh
What is ForkMesh?
ForkMesh is an open-source developer platform for publishing, browsing,
mirroring, discussing, and shipping software without making one hosting
provider the permanent owner of a project.
- Git stays the source of truth. Repository bytes live on
developer-operated hosts; the edge only routes traffic and collaboration
metadata and never stores Git packfiles.
- Every copy counts. Any node can mirror a public repository. Clones are
served from a live, signed, integrity-checked mirror, so a repository stays
reachable when its source host goes offline.
- Collaboration travels with the code. Issues, discussions, pull requests,
reviews, projects, milestones, and releases are signed records stored in the
repository under
.forkmesh/, not only in a hosted database.
ForkMesh is actively developed and its public network is real, but it is not
yet a finished replacement for every centralized forge workflow. The roadmap
and acceptance evidence live in .forkmesh/projects and
.forkmesh/issues.
Quick start
1. Install the desktop node
Install the latest prebuilt desktop release (the installer verifies its
published SHA-256 and places the binary in ~/.local/bin):
curl -fsSL https://forkmesh.com/install.sh | bash
To work on ForkMesh itself, build and launch the desktop app (Qt) from source instead:
git clone https://forkmesh.com/forkmesh/forkmesh
cd forkmesh
./desktop/run.sh
The source build needs Qt 6.4+, CMake 3.16+, OpenSSL development headers, Git,
and a C++17 compiler. Per-distribution package commands are in the
desktop guide.
2. First run
- Launch ForkMesh. A local Ed25519 node identity is created automatically and
the client connects to the default network; no server URL is required.
- Optionally sign in or create an account from Settings to get a portable
public username. The node identity stays on this device.
- Open Repos and choose New repository, Add local repo, or
Fork a repository you found on the mesh.
Getting started walks through these steps, chat,
and your first change in more detail.
3. Get the phone and watch apps
ForkMesh is on the App Store for iPhone and iPad, with an Apple Watch app for
following and steering agents, and on Android as a signed APK. See
ForkMesh apps.
Start your own instance
Run your own ForkMesh, under your own name, on your own server: open
forkmesh.com/start, fill in six short sections
(or upload one settings file), and ForkMesh
connects over SSH, installs everything and shows each step live. It needs a
fresh Debian 13 or Ubuntu 24.04 server with 1 GB RAM and takes about fifteen
minutes.
Or let a coding agent do it. Paste this into Claude Code:
Read https://app.forkmesh.com/forkmesh-agent.md and help me start my own ForkMesh instance. Ask me for anything you need first.
The agent guide also explains how the ForkMesh
team opens pull requests, and Working with coding agents
shows how to keep it in your repository without committing it. The full
walkthrough is Start your own instance.
Usage examples
Clone a public repository with stock Git. The stable URL is served by
whichever eligible mirror is healthy:
git clone https://forkmesh.com/forkmesh/forkmesh
Push a change. A repository created on the web is hosted on the core
nodes and takes git push over HTTPS. Git asks for your account name and the
push credential shown when the repository was created; pushes are
fast-forward only (Hosted repositories):
git remote add forkmesh https://app.forkmesh.com/<owner>/<repo>
git switch -c docs/my-change
git commit -am "docs: explain my change"
git push forkmesh docs/my-change
Open a pull request. In the desktop app, select the branch under
Code → Branches and choose Create PR. For an upstream project, fork it
first and use Pulls → New pull request; the signed request is queued for
the owner even while their node is offline. Agents can open the same signed
record with the MCP tool open_pr_from_branch or the HTTP API
(POST /api/repo/<owner>/<repo>/pulls); keep each one small and independent
(pull request workflow).
Hand work to an agent. Assign an issue to a coding agent from the desktop
app. Agents run in isolated worktrees with live transcripts and diffs, and
finished work becomes a pull request.
The stock Git compatibility matrix lists the
supported clone, fetch, push, partial-clone, bundle, submodule, and
signed-commit workflows and their known limitations.
What works today
- Browse and clone public repositories through a stable URL backed by signed,
integrity-checked mirrors.
- Create signed issues, discussions, pull requests, review conversations,
projects, milestones, and release metadata.
- Run multiple coding agents in isolated worktrees and turn their work into
pull requests.
- Run repository Actions on labeled desktop or server nodes with streaming
logs, artifacts, checks, and release publishing.
- Chat in authenticated, encrypted repository rooms (private channels and
direct messages are end-to-end encrypted between devices), share encrypted
private notes, and use ActivityPub discovery.
- Switch among independent relay instances. Accounts, repository actions, and
agent replies stay bound to the active instance, and the desktop never
silently fails over to a different relay.
- Explore repositories, nodes, agents, and activity in the 3D
ForkMesh World.
- Install creator packages and editor plugins from the Market.
Prove the promise
Use a disposable public repository and follow the short, reversible drill:
- Collaborate with a signed issue,
discussion, review, or pull request.
- Add an independent mirror
and wait until its signed health and repository refs are current.
- Take the source mirror offline
by stopping
forkmesh-mirror-node on the source host.
- Clone again from the same stable
URL and confirm the expected commit, then restart the source.
The product-promise guide covers prerequisites,
expected failures, recovery, and the measurement gate. A mirror is not
described as available until it passes the signed health and integrity checks.
ForkMesh's free-protocol / paid-services contract
keeps the MIT protocol, self-hosting, public read and clone, and portable Git
plus signed collaboration records free; only bounded, replaceable hosted work
is charged for.
Architecture
forkmesh.com / www.forkmesh.com → www landing, marketing, docs, blog
app.forkmesh.com ┐
world.forkmesh.com ┘ → core nodes, each running the app, a replicated
database, and the Go daemon + Git gateway
▲
│ outbound only: signed job leases
runners: agent and Actions jobs
│
independent server mirrors
(Git bytes + signed health)
- app is the Python application, run on CPython by the host shim in
app/host/forkmesh_host/ (docs/host). The core nodes
share a replicated database and serve the static files for app and
world. The app routes clone traffic to a mirror whose signed proof is fresh
and whose refs match an accepted source revision.
- www is a static-asset site, so marketing pages never consume the app's
request budget.
- Core nodes hold the data and run no untrusted code. Runners hold no
core secret and run agent and Actions jobs (docs/RUNNERS.md).
- Mirror servers are Go daemons (or desktop nodes) that hold the Git data
and publish signed health; the cores also host repositories created on the
web (docs/HOSTED_REPOS.md).
- Clients are the web app, the ForkMesh desktop app, and the native iOS
(Swift), watchOS and Android (Kotlin) apps. Phones are mobile nodes with
their own key and Git engine; the watch works through the iPhone. Mirroring
remains a desktop or headless-node job.
The developer view of how these pieces talk is
docs/architecture.md.
The app is also the self-hosting unit: deploy it at an address such as
forkmesh.example.com for the complete Git, account, API, and realtime
surface. World is optional, and self-hosts do not need to reproduce the
marketing site. forkmesh.com/start installs a
complete white-label instance on your server
(docs/INSTANCES.md).
Self-hosting and operations
Run a mirror server
The headless Go service supervises repository synchronization, the public HTTPS
Git gateway, and signed endpoint publication. Production hosts can be created and checked from
the Hosts rail of App → Network → Nodes. For a manual build:
cd server
go test ./...
go build ./cmd/forkmesh-mirror-node
See the mirror-node operations guide for
deployment and recovery.
Deploy the core fleet
The fleet is described by deploy/fleet.toml and driven by
tools/next_*.py; every tool is a dry run unless given --execute:
python3 tools/next_deploy.py all # plan an app release
python3 tools/next_deploy.py all --execute # build, upload, migrate, rolling restart
docs/deploy/README.md maps the tooling and
docs/OPERATIONS.md is the runbook. Keep secrets out of
the repository; never commit them.
The external dependency and observability map
lists every outside service a deployment contacts, what it observes, and what
still works without it; python3 tools/external_dependency_inventory.py check
keeps it complete.
Repository layout
.forkmesh/ portable project records: issues, pulls, projects, workflows, releases
.github/ forge compatibility and repository automation
app/ Git UI, API/relay, accounts, shared migrations; app/host/ runs it on CPython
conformance/ versioned contracts: protocol vectors, stock-Git matrix, shared fixtures
deploy/ fleet file, node renderer, certsync, IDS, systemd units
desktop/ Qt 6 desktop node
changelog/ the one changelog: forkmesh.com/changelog and the apps' What's new
docs/ developer documentation, one home page per subsystem
examples/ example third-party apps (docs/APPS.md)
marketplace/ creator package schema, catalog, packages, and editor plugins
native/ native iOS and watchOS (Swift/SwiftUI) and Android (Kotlin/Compose) apps
office/ Office (2D) code and media
server/ Go mirror daemon, core and runner roles, and server packaging
tools/ maintenance, MCP server, test runners, and security helpers
world/ World backend modules, tests, and 3D client assets
www/ landing site, marketing pages, authored docs, and blog
Build and test
Build and test the component you change before opening a pull request:
| Component | Command |
|---|
Desktop (desktop/) | ./desktop/run.sh test |
App (app/) | python3 tools/run_critical_tests.py worker |
World (world/) | python3 tools/run_critical_tests.py world |
| Browser smoke tests | npm --prefix app/browser_tests test |
Mirror server (server/) | cd server && go test ./... |
Native iOS core (native/ios/) | cd native/ios/ForkMeshCore && swift test |
Native Android core (native/android/) | cd native/android && ./gradlew :core:coreTest |
| Host and fleet | python3 -m pytest app/tests/host app/host/tests_unit deploy/tests |
| Guarded deletes and security contracts | python3 tools/run_critical_tests.py security |
| Git transport changes | python3 tools/git_conformance.py run --protocol-version 2 --output artifacts/git-conformance-v2.json |
CONTRIBUTING.md has the full
requirements and focused-test instructions.
Developer interfaces
The public API page at app.forkmesh.com/api
lists live service statistics and entry points. Representative routes:
GET /api/repositories
GET /api/repo/{owner}/{repo}/tree
GET /api/status
WS /api/repo/{owner}/{repo}/rooms/{room}/ws
GET /api/chat/agent-guestbook
GET /api/chat/agent-guestbook describes how an AI agent posts a short public
greeting; the response carries messageForUser for the agent to relay.
tools/forkmesh_mcp_server.py exposes capability-scoped tools over MCP for
compatible AI clients such as Claude Code (this repository's .mcp.json
already lists it):
- Code: list repositories and tracked files, read bounded text blobs, and
run bounded literal searches at a Git ref. Reads come from Git objects, so
ignored credentials,
.git, and arbitrary server files stay out of reach.
- Issues and pull requests: search issues; create issues, comments,
milestones and projects; read a pull request's diff; and
open_pr_from_branch, which signs the same pull request record the desktop
makes.
- Notes: create, get, list, search, and update signed Markdown. Repository
notes are committed under
.forkmesh/notes; personal notes live in the
ForkMesh application-data directory (override with FORKMESH_MCP_NOTES_DIR).
- Chat: read retained messages and post to
mainnode/forkmesh #general
through the existing encrypted room protocol (override the relay with
FORKMESH_CHAT_ORIGIN).
- Organization tools, signed as the desktop's account: the Tasks page
(create, update, complete, attach work items, soft delete and restore),
CRM contacts and pipeline, and the marketing channel's next post (saved for
the team, never posted).
- Desktop tools, only inside an agent the desktop launched: start other
agents, message them, list runners, notify the user, show windows and
widgets, drive a small browser window, and manage desktop releases.
- Email and expenses:
send_email sends one message through the
configured Zoho Mail account at once, with no confirmation step, and
logs it in the CRM; record_expense needs an admin account.
Access depends on whether the node has published a connector in
Desktop → Settings → MCP. Until it has, the server is open: every tool
works with the authority of the local node key. Once it has, write tools and
the organization, desktop and email tools need the connector's token in
FORKMESH_MCP_TOKEN; code, note, chat, issue and pull reads still work
without it. Publish a connector before giving the server to an agent you do
not fully trust. No MCP tool provides a shell, arbitrary filesystem access,
room keys, infrastructure credentials, code modification, Git pushes or note
deletion. create_release does tag a release and start its workflows.
Security model
- Node and protocol actions use local Ed25519 identities and signed records.
- Public mirror eligibility requires a fresh account-bound signature, a healthy
direct HTTPS endpoint, allowed status, and an integrity-matching repository
proof.
- The relay stores routing and collaboration data, not Git packfiles.
- Public repository chat uses authenticated shared-key encryption that ForkBot,
MCP, and webhooks can read; private channels and direct messages add
device-to-device encryption.
- Owner-device agent transcripts and steering payloads are hybrid-encrypted;
the hosted platform has no administrative decryption override.
- Legacy Worker-custodied bounty deposits and automatic payouts are frozen.
Current rewards use reviewed, non-custodial signing and externally owned
wallets.
Report vulnerabilities as described in SECURITY.md. Protocol
boundaries are documented in www/docs/security.
Documentation
The hosted documentation is at forkmesh.com/docs.
Mirrors
ForkMesh's own source is published to every one of these; each serves the same
main and tags:
| Mirror | URL | Notes |
|---|
| ForkMesh (stable URL) | https://forkmesh.com/forkmesh/forkmesh | Redirects to whichever eligible mirror is healthy. |
| ForkMesh core nodes | https://app.forkmesh.com/forkmesh/forkmesh | The self-hosted core fleet; the source of truth. |
| GitHub | https://github.com/forkmesh/forkmesh | Read-only copy of main and tags. |
Contributions land on ForkMesh. Pull requests opened on GitHub are reviewed and
reapplied there by hand. The
source publisher keeps every mirror current.
Contributing
Human and AI contributors are both welcome. Start with
CONTRIBUTING.md: keep changes scoped, add the closest
contract or integration test, and run the affected component suite before
opening a pull request. An implementation is not called complete until its
compatibility, security, documentation, observability, and rollout gates match
the claim (definition of done).
Other ways to help: run a node, mirror a project you care about, pick up an
issue, or give an agent a well-bounded task.
License
ForkMesh is released under the terms in LICENSE.
