---
status: draft
last_updated: 2026-09-21
---

# alkgitd: Server Binary

## What it is

The assembly point: config parsing, listener setup (TLS/ACME), vault
wiring, the admin surface, and the glue that turns config into running
adapters. The only crate that knows the whole graph (ADR-001). No business
logic lives here.

## Assembly shape

For each listener (http and/or ssh), the binary:

1. Builds the identity provider (per-door; **OQ-08** decides mechanics).
2. Builds the registry (core trait + chosen backing; **OQ-06** decides
   backing) and the storage roots from config.
3. Builds the transport hooks + `Limits` from config (ADR-009 defaults +
   overrides).
4. http door: constructs the alkgit-http router factory (ADR-006) and
   merges via `HttpAdapter::with_extra_routes`; wraps in alktls per
   config; `Arc<HttpAdapter>` per accept task (POC-3 usage note).
5. ssh door: russh listener terminates SSH; alkgit-ssh dispatches the
   exec requests (ssh.md §client compatibility).
6. Vault (alkvault) wired for any credential material; metadata/config
   hold vault references only (convention 4/5).

## Config schema (v1 shape)

Server-facing values (registry backing location, storage roots, per-door
listeners/ports, TLS/ACME, limits overrides, vault path). The schema's
final shape depends on **OQ-06** (backing) and **OQ-08** (identity
config); the skeleton above is the stable frame.

Feature flags (convention 10): `sha256` (passthrough), `acme` (alktls
wiring). Base binary compiles lean; both feature sets verified in CI
(AGENTS.md verification commands).

## Admin API (scope: OQ-07)

- alkcall ops with `Visibility::Internal`, served over an admin-only
  listener — never on the git traffic surface (alk-stack.md §gitea
  lesson; vision threat-model notes).
- Candidate v1 op set (repo create/delete, visibility, ACL grant/revoke)
  and its exact shapes: **OQ-07** — a dedicated session once the identity
  model (OQ-08) exists, since op shapes depend on what identities mean.
- A downstream app may replace this surface entirely (vision
  composability): the ops are alkcall ops, not embedded web endpoints.

## TLS/ACME

- alktls composition: `Connection::from_bidi(TlsStream, alpn)` — the
  POC-1/3-validated alkcall entry shape. The http door rides TLS with
  ALPN `http/1.1`/`h2`. The ssh door is a plain TCP listener
  (stock `git clone ssh://` clients do not do TLS) — russh terminates SSH
  directly on it (ssh.md); alkcall `Connection::from_stream` wraps the
  post-auth stream when the adapter needs alkcall types.
- `acme` feature: alktls ACME state machine wired to config for the http
  listener (alk-stack.md lists this as "likely trivial"; risk note: if the
  wiring surprises, that becomes a research task before alkgitd
  implementation — not silently absorbed).

## Serving loops

- Per-connection accept → `ProtocolHandler::handle` (alkcall ADR-002)
  → adapter dispatch → transport session.
- Server-wide blocking-pool budget for pack generation (ADR-009):
  accepted/rejected at assembly time.
- Graceful shutdown: listener stop + session drain bounded by the
  session wall clock (ADR-009).

## Design Decisions

| ADR | Decision | Summary |
|---|---|---|
| [001](decisions/001-crate-decomposition.md) | Crate decomposition | alkgitd = assembly only |
| [006](decisions/006-http-adapter-composition.md) | Router factory | alkgitd consumes the factory like any embedder |
| [008](decisions/008-registry-resolved-repo-identity.md) | Repo identity | storage roots configured server-side here |
| [009](decisions/009-bounded-resources-budget.md) | Budgets | limits overrides live in config |

## Open Questions

- **OQ-06**: registry backing (deferred(scope)).
- **OQ-07**: admin op set (open — after OQ-08).
- **OQ-08**: identity providers per door (open).

## References

- `docs/research/alk-stack.md` (integration surface, version pins)
- `docs/research/poc3-findings.md` (HttpAdapter usage, extra-routes behavior)
- alkcall ADRs: 002 (ProtocolHandler), 010 (capability injection), 017
  (privilege model)