Home

ocid: Local-First, Peer-to-Peer OCI Image Distribution¶

ocid (pronounced "oh-seed") lets you push, pull, and share container images directly between peers — no central registry required. Every node runs its own loopback OCI registry that standard tooling (podman, docker, oras) talks to unchanged, while peers exchange signed, content-addressed releases directly.

🚀 Quick Start¶

1. Install ocid¶

1# From source (recommended)
2git clone https://github.com/safonas/ocid
3cd ocid
4just bin  # Build binaries to ./bin/
5
6# Or via Homebrew (macOS/Linux)
7brew install safonas/tap/ocid

2. Start the Daemon¶

1ocid

This starts the daemon with: - OCI registry on 127.0.0.1:5050 - Embedded iroh endpoint (QUIC, hole-punching, relays) - Gossip and blob store for P2P distribution

3. Push an Image¶

1# Build and push an image to your local ocid registry
2podman build -t localhost:5050/myapp:1.0 .
3podman push localhost:5050/myapp:1.0

4. Share with a Peer¶

On Node A (publisher):

1# Get a connection ticket for Node B
2ocictl ticket | pbcopy

On Node B (consumer):

1# Connect to Node A using the ticket
2ocictl connect <ticket>
3
4# Follow Node A's releases
5ocictl follow <NodeA-PublisherId>

Now, Node B will automatically replicate all new releases from Node A!

🎯 Why ocid?¶

Problems with Centralized Registries¶

Use Cases¶

🏗️ Architecture¶

ocid is built on iroh, a Rust library for peer-to-peer networking with QUIC, hole-punching, and relays. The architecture is designed to be simple, secure, and efficient:

flowchart TB
    subgraph host["Your Machine"]
        podman["podman / docker / oras"] -->|HTTP /v2| registry["OCI Registry<br/>127.0.0.1:5050"]
        ocictl["ocictl (CLI)"] -->|HTTP /_ocid| control["Control API"]
        ocitop["ocitop (TUI)"] -->|SSE| control
    end

    registry --> daemon["ocid Daemon"]
    control --> daemon

    daemon --> gossip["iroh-gossip"]
    daemon --> blobs["iroh-blobs"]
    daemon --> endpoint["iroh Endpoint<br/>QUIC + NAT Traversal"]

    endpoint <--> peer1["Peer 1"]
    endpoint <--> peer2["Peer 2"]

    %% Styling
    classDef host fill:#e6f3ff,stroke:#333
    classDef daemon fill:#fff2cc,stroke:#333
    classDef p2p fill:#ffd966,stroke:#333

    class podman,ocictl,ocitop,registry,control host
    class daemon,gossip,blobs,endpoint daemon
    class peer1,peer2 p2p

Key Components¶

📦 Features¶

✅ Core Features¶

• OCI v2 Compatibility: Works with podman, docker, oras, crane, etc.
• Peer-to-Peer Distribution: Direct sync between peers using iroh.
• Signed Releases: Every release is signed with the publisher’s Ed25519 key.
• Content-Addressed Blobs: Blobs are addressed by SHA256 (OCI) and BLAKE3 (iroh).
• Retention Policies: follow, seed, pin with last:N, full, or tags modes.
• DNS Publisher Names: Use domain names (e.g., images.example.com) for publishers.
• mDNS Discovery: Automatically discover other ocid nodes on your LAN.
• Relay Support: NAT traversal via iroh relays (optional).
• TLS Support: Self-signed certificates for transport encryption.

🚧 Coming Soon¶

• Multi-key Publishers: Support for delegation (Radicle-style).
• Signed Tombstones: Propagated deletion (opt-in).
• Registry Authentication: Authenticate pushes (optional).
• Bandwidth Limits: Rate limiting for peers.
• IPv6 Support: Full IPv6 compatibility.

📖 Documentation¶

🤝 Community¶

• GitHub: safonas/ocid
• Discussions: GitHub Discussions
• Issues: GitHub Issues
• Matrix: #ocid:matrix.org (coming soon)

📜 License¶

ocid is licensed under the GPL-3.0-or-later license. See LICENSE for details.

🙏 Acknowledgments¶

ocid stands on the shoulders of giants:

• iroh: Peer-to-peer networking with QUIC, hole-punching, and relays.
• Radicle: Inspiration for the local-first, peer-to-peer model.
• OCI Distribution Spec: Standard for container images.
• Rust: The programming language that makes ocid fast and safe.