open.storage is an open-source Git storage backend, wire-compatible with code.storage (Pierre Computer Company). These docs follow the Diátaxis layout: tutorials, how-to guides, reference, and explanation.
New here? Start with the README quickstart.
- README quickstarts: local mode in 60 seconds, two replicas with Docker Compose, and one S3 bucket (experimental).
Try and deploy
- Try with Docker only
- Deploy a two-replica stack with Docker Compose
- Deploy to production
- Deploy the AWS EC2 reference (Terraform)
- Migrate to open.storage
Operate
- Operate the storage lifecycle: repack, quotas, sweeping
- Run the zero-infrastructure mode (s3wal, experimental)
- Back up and restore a stopped S3WAL node
Maintain the project
| Page | Covers |
|---|---|
| Configuration | Every OPENSTORAGE_* variable, defaults, and validation |
| Metrics | The opt-in Prometheus listener and every metric it exposes |
| CLI | openstorage commands and flags |
| HTTP API | Endpoint catalog, scopes, and the status-code contract |
| Authentication | Customer-signed JWTs, claims, scopes, and ref policies |
| Webhooks | Endpoint management, delivery headers, signatures, and event payloads |
| Testing | Test lanes, conventions, fuzzing, and benchmarks |
| Page | Explains |
|---|---|
| Wire compatibility | What matches code.storage, and the known deviations |
| The storage engine | Immutable packs, ref compare-and-swap, garbage collection, and s3wal |
| Domain model | Entities, ref namespaces, and the invariants a backend must uphold |
| Git protocol and namespaces | Git smart HTTP, remote URLs, LFS, and refs over Git |
| Streaming commit protocols | NDJSON commits from file operations or patches, and restore commits |
| Directory | Contents |
|---|---|
adr/ |
Architecture decision records (ADR-1 to ADR-48). Historical and individually addressable. |
archive/ |
The original implementation roadmap and per-phase notes (archive/phases/08 to 16). Historical: for current behavior, prefer reference and explanation pages. Recorded evidence paths and upstream names are unchanged. |
upstream/ |
Verbatim copies of the vendor's OpenAPI spec and docs, kept for compatibility audits. |
Contributors: start with CONTRIBUTING and the testing reference.
Six pages specify the code.storage API surface precisely enough to build a compatible
backend: domain model,
authentication, HTTP API,
streaming commit protocols,
Git protocol and namespaces, and
webhooks. A compatible backend drops in through the SDKs'
apiBaseUrl / storageBaseUrl overrides, with no client code changes.
Each claim was extracted independently from three SDKs and cross-checked against the vendor's docs:
| Source | Defines |
|---|---|
sdk/packages/code-storage-typescript |
Wire formats, JWT claims, NDJSON streaming, webhooks |
sdk/packages/code-storage-python |
Same surface; confirms wire formats |
sdk/packages/code-storage-go |
Same surface; confirms wire formats |
just-code-storage (real consumer) |
Semantics clients rely on: sync, conflicts, status codes |
upstream/openapi.yaml (official) |
Full endpoint catalog, including paths the SDKs do not use |
upstream/getting-started/, upstream/guides/ (official) |
Auth model, webhooks, LFS, and Git operations |
All three SDKs implement the same wire surface (endpoints, claims, chunk sizes, signature scheme), which gives high confidence in the extracted spec.
The official spec defines two path styles for the same operations:
| Style | Example | Repository comes from |
|---|---|---|
v1 (/api/v1/...) — used by all three SDKs |
GET /api/v1/repos/commits |
The JWT repo claim |
Named-repo (/api/repos/{repo_name}/...) — newer |
GET /api/repos/{repo_name}/commits |
The path; the JWT still needs a matching repo claim |
Implement v1 first for SDK compatibility. The named-repo style is a thin routing layer over the same handlers.