zuka

Git hosting for agents. One Rust binary — bare repositories, SSH and HTTP git, a REST API, MCP, and CI. No database, no Docker, no external services.

Status   Complete. M0–M7 shipped: standalone and multi-tenant both work.
Tests    253 unit · 59 live (real git, ssh and MCP against a real server)
Gate     cargo fmt --check · clippy -D warnings · cargo test · deno task test:live

Named for the sound of it rather than the meaning: two syllables, a rare opening consonant, one plausible spelling after hearing it once. It sits near Swahili kuzuka — to surface, to emerge — without claiming to be it.

The idea

Agents already know git. What they can't do is the GitHub part.

Claude, Cursor and the rest run git clone, commit and push perfectly well. What stops a non-developer shipping with them is everything bolted on top: creating the repository, orgs and teams, deploy keys, permission matrices, pull requests, review, Actions YAML.

So the split is strict:

Nothing in the API writes to a repository. No commit endpoint, no file endpoint, no ref-moving endpoint. A second write path would mean two homes for the fast-forward rule, two concurrency models and a merge story — git already has all three. The write path is git push.

What's deliberately absent is the point: no organisations, no teams, no pull requests, no review, no issues. The whole model is accounts, repositories, refs, keys and runs.

Install onto a host

sudo zuka setup --standalone --dry-run    # prints every file it would write
sudo zuka setup --standalone

It writes /etc/zuka.env and two systemd units — the service and maintenance separately, because a long repack must not stall requests — then prints the remaining commands rather than running them. Creating users and enabling units are steps someone may reasonably want to do differently.

--domain is optional, and does one thing: it adds a Caddyfile so Caddy obtains and renews TLS for that name, and sets the public URLs advertised in clone URLs. Without it you get a service on 127.0.0.1:8790 with no TLS, which is right behind an existing proxy or for a local trial.

sudo zuka setup --standalone --domain git.example.com

--isolated installs the multi-tenant shape: a control plane that holds no repositories and gives every account its own Incus container. Code, CI and objects for one account never touch another's filesystem. --domain is optional here too and means exactly the same thing — the control plane is the only public listener, so it is the only thing a certificate is for.

sudo zuka setup --isolated
curl -X POST localhost:8790/v1/accounts/alice     # returns immediately

Set a public URL if you have one: a tenant is only reachable through the control plane, so left to itself it advertises its own container address and hands callers a clone URL they cannot use.

Provisioning never blocks a request. The account records intent and a reconciler drives it to ready; a request arriving early gets 429 with a Retry-After. Tenants are stopped when idle and started again on demand.

The tenant binary must be statically linked — the control plane pushes it into a container whose C library is not the host's:

cargo build --release --target x86_64-unknown-linux-musl

Quickstart

Needs git ≥ 2.41 on the host.

cargo build --release
export ZUKA_DATA_DIR=/tmp/zuka && mkdir -p "$ZUKA_DATA_DIR"

TOKEN=$(./target/release/zuka token alice --scopes admin)   # shown once
./target/release/zuka
# [boot] listening on http://127.0.0.1:8790
# [ssh]  listening on ssh://127.0.0.1:2222

Create and push

curl -X POST localhost:8790/v1/repos \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"site"}'

git clone "http://x-access-token:$TOKEN@127.0.0.1:8790/alice/site.git"
cd site && echo hello > README.md
git add . && git commit -m "first" && git push origin HEAD:refs/heads/main

The git username is ignored; the password is your token.

Use SSH instead

./target/release/zuka key alice ~/.ssh/id_ed25519.pub --title laptop
git clone ssh://git@127.0.0.1:2222/alice/site.git

--read-only makes a key clone-only; --repos a,b confines it.

Read without cloning

A="Authorization: Bearer $TOKEN"; R=localhost:8790/v1/repos/alice/site
curl -H "$A" $R/refs
curl -H "$A" "$R/tree/src?ref=refs/heads/main"
curl -H "$A" "$R/raw/README.md"
curl -H "$A" "$R/search?q=TODO"
curl -H "$A" "$R/blame/src/main.rs"
curl -H "$A" "$R/compare?base=<sha>&head=<sha>"

The ref is always a query parameter, never a path segment — feature/login and src/main.rs both contain slashes, so /raw/{ref}/{path} has no unique parse.

Turn on CI

ZUKA_CI_ENABLED=1 ./target/release/zuka

# .zuka.toml, in the repository
[run]
steps = ["cargo fmt --check", "cargo test"]
timeout_secs = 600
branches = ["refs/heads/main"]   # optional; omit to run everywhere

Push, then curl -H "$A" $R/runs and $R/runs/{id}/logs.

For agents — MCP

POST /mcp     JSON-RPC 2.0: initialize · ping · tools/list · tools/call

The intended session: repo_create → key_add → plain git clone/commit/push → run_list. There is no tool that writes to a repository, and initialize says so, so a model doesn't go hunting for one.

A tool failure that's the caller's fault comes back as a tool result with isError: true, not a JSON-RPC error — the model should see it and adapt, not have the call look broken.

Administration — the part git can't do

Discovery — read without cloning

CI

API

Full contract: openapi.json, also served at /openapi.json.

Errors on /v1 and /mcp are RFC 9457 application/problem+json with a stable type URI — discriminate on type, never on detail. The git paths answer in text/plain instead, because git prints the body straight at the user.

Lists return {items, truncated}. There is no cursor, and none is claimed.

CLI

zuka                                   serve
zuka setup --standalone|--isolated     install onto this host [--domain d] [--dry-run]
zuka jobs                              maintenance daemon (own service unit)
zuka gc | sweep | fsck [--repair]      one-shot maintenance
zuka token <account> [--scopes s] [--repos r] [--days n] [--no-expiry]
zuka key   <account> <path.pub> [--title t] [--read-only] [--repos r]
zuka version

Scopes: repo:read, repo:write, admin, ci. Tokens expire in 90 days unless you pass --days or opt out with --no-expiry, which warns. Credentials added while the server runs take effect without a restart.

fsck exits non-zero on an orphan so a timer notices. It reports a repository with no metadata but never deletes one — repair only removes records that describe nothing.

Configuration

Everything has a working default; nothing is required.

ZUKA_ME_URL is parsed and then refuses to boot — hosted auth isn't implemented, and accepting a security-relevant setting while ignoring it is worse than not accepting it.

Maintenance

Run zuka jobs as a second service unit — a long repack must not stall request handling.

[Unit]
Description=zuka maintenance
After=zuka.service
[Service]
ExecStart=/usr/local/bin/zuka jobs
EnvironmentFile=/etc/zuka.env
User=zuka
Restart=always
[Install]
WantedBy=multi-user.target

It garbage-collects (git's own auto-gc is disabled on every repo, so a repack never fires inside a push), sweeps deleted repositories and old runs, and fscks.

What makes GC safe against a live clone is the grace window, not a lock — a lock couldn't span the two processes. upload-pack can reference an object between resolving and streaming it, so nothing younger than GC_PRUNE_GRACE is pruned. A test clones a 12 MB repo while GC runs and checks the result byte for byte.

Worth stating plainly: a committed secret stays fetchable by sha until GC prunes it. Force-pushing past it moves the ref, not the object.

Security

Each of these has a test that fails if it regresses. Several are here because an earlier version got them wrong.

Names can't escape the data directory. Ref names go through gix-validate, never a hand-rolled check — ../../config is a command-execution primitive via core.pager and core.sshCommand. Tree paths reject any .git component after Unicode normalisation, case folding, HFS-ignorable-codepoint stripping and trailing dot/space removal.

Names are case-folded. Alice/Site and alice/site are one resource. Comparing the raw path segment once let a case-variant account reach another account's repository on a case-insensitive filesystem while passing the ownership check.

An unreadable repository is 404, not 403. 403 enumerates private repos. Confinement applies to destruction too: a token scoped to one repo can't delete another.

Rewriting is allowed; protection is opt-in. rebase and --amend are ordinary git and blocking them protects nobody when there's one agent and no reviewer — git's reflog is the recovery path. Set protected_refs on the branch something deploys from; it's then enforced server-side over HTTP and SSH, which matters because --force bypasses the client check. One Rust function; the hook is a one-line exec into the binary.

SSH runs git and nothing else. No shell, no pty, no subsystem. Three services: upload-pack, receive-pack, upload-archive. The exec string is parsed, never shelled, so git-upload-pack '/a/b.git'; id is a parse error. The account comes from which registered key matched, never the SSH username. Only GIT_PROTOCOL crosses into the child.

Only three endpoints route under .git. The dumb protocol isn't served. A duplicated service parameter is refused — this server would take the first and the CGI the last, so a duplicate would let the authorization decision and the running service disagree.

Import can't reach the local network. The one place a caller-supplied URL is fetched. Checked in two stages: shape (scheme, credentials) then every address the host resolves to — checking the hostname alone is defeated by a name that resolves to 169.254.169.254.

Credentials are hashed, scoped, expiring and 0600. Token comparison has no early return. Public keys match on raw bytes; authorized_keys option prefixes like command= are refused.

Deletes are recoverable. Soft-deleted to tmp/deleted/, swept on retention.

Nothing buffers a pack.

                          before      after
200 MB push, server RSS   ~360 MB      5 MB
4 concurrent clones       1508 MB      5 MB

The child is killed by process group on disconnect — kill_on_drop reaches only the direct child, and pack-objects is a grandchild that otherwise kept running for seconds after the client left.

Multi-tenant isolation

In --isolated, each account gets its own Incus container, unprivileged and with nesting off. The control plane holds no repositories: a push through it lands in the account's container and nowhere on the host.

A tenant is told who is calling by an Ed25519 assertion the control plane signs, not a shared secret. That matters because a tenant runs the account's own CI, which is arbitrary code — anything symmetric in there would forge every other tenant. The private key never leaves the control plane; tenants hold only the public half, which forges nothing.

The assertion authenticates one request, not an identity: single-use nonce, 30-second window, bound to the method and path. It is deliberately not bound to the body, because a push is a multi-gigabyte pack the proxy streams — the nonce is what stops replay.

Verified on a real host rather than asserted, in infra/README.md: CI inside a tenant reports uname -n = zuka-alice, and a second account gets 404 on the first's repository and an empty repo list.

CI is not a security boundary in standalone

Steps run as the service user with rlimits, a scrubbed environment, a process-group kill on timeout and a bounded log — but no container and no network namespace. Anyone who can push can run code as that user. CI is off by default and the boot log says so.

A step allowlist was considered and rejected: sh -c defeats it in one character. Enforcement is at the OS or it isn't enforcement. Multi-tenant isolation is M6 and isn't built.

Renaming it

The name lives in exactly one file. src/brand.rs derives the env prefix, data directory, problem-type URIs, auth realm, git config namespace, CI filename and hook shim from CARGO_PKG_NAME.

Renaming is one line in Cargo.toml plus the openapi.json title — verified by actually doing it. A unit test walks src/ and fails if the name appears as a literal anywhere outside brand.rs; it has already caught a hardcoded auth realm.

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test                 # 204 unit tests
deno task test:live        # 59 live tests: spawns the binary, drives real git and ssh

The live suite is the real proof — unit tests cover units, but only a real clone and push exercise the wire protocol. It runs in CI rather than self-skipping there.

src/
├── brand.rs       the one place the product name appears
├── config.rs      Config::from_env(); fails boot on a bad value
├── error.rs       Error -> RFC 9457 problem+json
├── core/          domain operations shared by every facade
├── git/
│   ├── exec.rs      the only place this service invokes git
│   ├── validate.rs  security controls: names, refs, paths
│   ├── store.rs     repositories, hooks, ref rules
│   ├── discover.rs  the read core, shared by REST and MCP
│   ├── transport.rs streaming CGI bridge
│   └── import.rs    SSRF-guarded cloning
├── http/          routing, limits, responses, auth, rate limiting
├── api/           REST facade
├── mcp/           MCP facade
├── ssh/           SSH server and exec-command parser
├── ci/            spec, run store, runner, executor
├── control/       accounts, provisioning, reconciler, streaming proxy
├── setup.rs       systemd units, Caddyfile, environment file
├── jobs/          gc, sweep, fsck
├── account/       identity, tokens, SSH keys
└── store/         metadata, quotas, change-aware file cache

Two rules worth knowing before changing anything:

• git is the only writer. No endpoint or tool modifies repository contents.
• Facades translate; they don't decide. Authorization lives on Identity, git rules in git/, shared operations in core/. api/ and mcp/ reshape payloads and nothing else — they had drifted copies of repo create and delete once, and those copies had already diverged in four ways.

More: SPEC.md · ROADMAP.md · AGENTS.md