github-clone

Public

Open-source GitHub clone: git repos, pull requests, issues, wiki, AI workspace, CLI and MCP. MIT.

Harakumo1 commitUpdated 11 days ago2 downloads

Loading the docs…

Loading the files…

READMEREADME.mdView source

Nucleus

A self-hostable code platform: git repositories, an AI workspace that writes straight into them, live previews, and the collaboration tools around them — issues, pull requests, discussions, a wiki and project boards — plus a CLI and an MCP server so your terminal and your AI assistant can work in the same repositories. Next.js 16 + MongoDB.

Harakumo's hosted code home, nucleus.harakumo.com, grew out of this project and is a separate service.

Features

Repositories

Public and private git repositories with branches, commit history, a file browser and editor, Markdown READMEs, stars and forks.
Private means private: every repository route goes through one server-side permission check (src/lib/authz.ts), with read / write / admin roles for collaborators.
Pull requests with diffs and merges, issues, discussions, a wiki, project boards, insights, and a security page that flags committed .env files.
Organizations that group repositories and people under one name.
Encrypted repository secrets (AES-256-GCM, with a key separate from the session key).
Download any repository as a ZIP.

AI (bring your own Anthropic and/or xAI key)

An AI workspace (/chat) and a per-repository assistant that write real files into the repository — Claude or Grok, chosen per request.
Architecture analysis: the AI reads the whole codebase and explains how it fits together.
AI agents you can "hire" onto a repository, with a task board and activity feed, and actions that run them on commits made in the web app, on new issues, or on demand.
AI-generated project presentations, exportable to PDF.

Live previews

Static sites (a repository with an index.html) are served straight from the repository, sandboxed away from the Nucleus origin.
Projects with a package.json run inside the visitor's browser (WebContainer), so a preview costs the server nothing.
Python, Ruby, Go, Java, Rust, PHP and Flutter projects run in a short-lived Docker container when the server has a Docker socket.

CLI and MCP

nucleus CLI: login, init, push, pull, sync (merges other people's changes and asks before overwriting), clone, list, status.
An MCP server so Claude Desktop, Claude Code or any MCP client can list, read and write repositories and issues with exactly the signed-in user's access.

Operations

Every push can be snapshotted to any S3-compatible bucket, and a repository missing from disk is restored from its snapshot on first use — so Nucleus survives hosts that wipe the filesystem on restart.
Per-user rate limits and quotas on the expensive paths (AI, previews, pushes).
Refuses to start in production without its required secrets.

How code is stored

Repositories are real git repositories (written with isomorphic-git) on the server's disk under NUCLEUS_REPOS_DIR. You work with them through the web app, the nucleus CLI, or the MCP server. Plain git clone / git push over HTTP is not supported yet.

Rate limits and per-repository write locks live in the server's memory, so run one instance.

Quick start (development)

Requirements: Node 22 and a MongoDB database.

npm installcp .env.example .env.local     # set MONGODB_URI and AUTH_SECRET at leastnpm run dev

Open http://localhost:3000, create an account, and create a repository. Repositories are written to ./repos unless NUCLEUS_REPOS_DIR is set.

Script	What it does
`npm run dev`	Development server
`npm run typecheck`	`tsc --noEmit` — run it before building (the build skips its own type check)
`npm run build` / `npm start`	Production build and server (`PORT`, default 3000)
`npm run lint`	ESLint
`npm test`	Push-integrity, OTP, path-traversal and durability tests
`npm run backup` / `npm run backup:list`	Snapshot every repository to the bucket / list the snapshots

Configuration

Everything is configured with environment variables; .env.example documents each one.

Variable	Required	Purpose
`MONGODB_URI`	Yes	MongoDB connection string (include the database name)
`AUTH_SECRET`	Yes	Signs sessions and CLI/MCP tokens
`SECRETS_ENCRYPTION_KEY`	Production	Encrypts repository secrets at rest
`AUTH_URL`	Production	Public URL of the server
`ANTHROPIC_API_KEY`, `XAI_API_KEY`	For AI	At least one, for the AI features
`HARAKUMO_API_KEY`	Recommended	Sends verification and password-reset emails through Harakumo Mail
`STORAGE_ENDPOINT`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY`	Recommended	S3-compatible bucket for repository backups
`NUCLEUS_REPOS_DIR`	Production	Where repositories live on disk (a persistent volume)
`TRUST_PROXY`	Behind a proxy	Read client IPs from `X-Forwarded-For` for rate limits
`CONTACT_EMAIL`	No	Address shown on `/contact` (empty by default)
`DOCKER_SOCKET_PATH`, `NUCLEUS_PREVIEW_HOST`	No	Container previews

CLI

The CLI lives in cli/ and talks to any Nucleus server.

npm link                                    # from this repository: puts `nucleus` on your PATHnucleus login --server https://your-nucleus-hostcd my-projectnucleus init                                # link this folder to a repositorynucleus push -m "First version"nucleus sync -m "My changes"                # the safe everyday command when others work on it too

Full reference: cli/README.md.

MCP server

claude mcp add nucleus -- node /absolute/path/to/nucleus/cli/mcp/server.mjs

It reuses the token from nucleus login (or NUCLEUS_TOKEN + NUCLEUS_URL). Tools: list_repos, list_files, read_file, write_files, create_repo, list_issues, create_issue. Details: cli/mcp/README.md.

Self-hosting with Docker

cp .env.example .env.production   # fill it indocker compose up --build         # http://localhost:3000, repositories on a named volume

or on any server:

docker build -t nucleus .docker run -d -p 3000:3000 --env-file .env.production \  -v nucleus-repos:/app/repos --restart unless-stopped nucleus

Put a reverse proxy in front for TLS and set TRUST_PROXY=true. The full guide — durability, security settings, troubleshooting — is in DEPLOYING.md.

Run Nucleus on Harakumo

Nucleus is open source (MIT) and is listed on Nucleus, Harakumo's code home. Its verification and password-reset emails already go through Harakumo Mail (src/lib/mail.ts, one HARAKUMO_API_KEY).

Nucleus is a Node server, so on Harakumo it runs as a server app (Pro plan and up), not a static site.

Create a project at harakumo.com/dashboard → Projects → New project.
Create an API key (Settings → API keys) and add it to the project's environment as HARAKUMO_API_KEY. Turn on Mail for the project, or password reset codes cannot be sent.
Add the rest of the environment (Project → Environment), from .env.example:
- MONGODB_URI — a MongoDB database. MongoDB is required for now.
- AUTH_SECRET and SECRETS_ENCRYPTION_KEY — two different openssl rand -base64 32 values. Keep a copy of the second one: losing it makes stored secrets unreadable.
- AUTH_URL — the project's public URL.
- STORAGE_* — an S3-compatible bucket. Required here, not optional: a server app's disk is not kept between deploys, and Nucleus restores each repository from its last snapshot after a redeploy.
- TRUST_PROXY=true, plus ANTHROPIC_API_KEY / XAI_API_KEY for the AI features.
Deploy from this folder with the CLI, or ask your AI assistant with the Harakumo connector:
```
npm i -g @harakumo/cliharakumo login --key <your API key>harakumo deploy <project id> .
```
Every deploy is saved as a commit in the project's private Nucleus repo.

Notes:

Container previews need a Docker socket, which a server app does not have; Nucleus reports them as unavailable. Static and in-browser previews work.
Run one instance (see How code is stored).

Tests

npm test

The OTP test starts an in-memory MongoDB (mongodb-memory-server), which downloads a MongoDB binary on its first run.

Project layout

src/app/        pages and API routes (src/app/api/repos/... is the repository API)src/lib/        git storage, permissions, AI, mail, backups, rate limitssrc/models/     Mongoose modelscli/            the `nucleus` CLI and its MCP serverscripts/        backup-all-repos.mjstests/          security and durability tests

License

MIT — see LICENSE.