How it works¶

Junk Net is three layers, each doing one job:

A user never sees any of this. They see an S3 endpoint and a pair of access keys, and use it like any other object store.

The big picture¶

graph TB
    subgraph You
        C[S3 client<br>rclone / AWS CLI / SDK]
    end

    C -->|HTTPS, S3 API| G[Gateway node<br>public endpoint]

    subgraph Nebula mesh — encrypted overlay network
        G <--> N1
        G <--> N2
        G <--> N3
        N1[Node: old ThinkPad<br>Home A] <--> N2[Node: old MacBook<br>Home B]
        N2 <--> N3[Node: old Dell<br>Home C]
        N1 <--> N3
    end

    L[Lighthouse<br>small public host] -.NAT traversal
    coordination.-> N1
    L -.-> N2
    L -.-> N3
    L -.-> G

Every laptop runs the same small stack: Linux, the nebula daemon, and the garage daemon — both as hardened systemd services. Nodes find and talk to each other only over the mesh; Garage's ports are never exposed to a home network or the public internet.

Life of an object¶

Here's what happens when you upload holiday-photos.zip:

1. You PUT the object to the S3 endpoint with your access keys.

2. Garage chunks it. The object is split into blocks (1 MiB by default), each identified by its hash. Blocks are compressed with zstd.

3. Garage places three copies of every block, using the cluster layout to pick three nodes in three different zones. In Junk Net, a zone is a household — so your photos survive not just a dead disk, but a whole house losing power, internet, or existence.

4. Metadata is replicated too. Which blocks make up which object, bucket listings, access keys — all stored on three nodes, kept consistent with quorum reads and writes (2 of 3 must agree).

5. You GET it back from any gateway; Garage fetches blocks from whichever replicas are alive and reassembles the object.

The upshot: any single node can vanish at any moment — unplugged, stolen, dropped in a bathtub — and nothing is lost. When a node stays gone, Garage re-replicates its blocks onto other machines to get back to three copies.

Design decisions that matter¶

A zone is a household. Garage lets you tag each node with a zone and guarantees replicas land in distinct zones. Junk Net uses this to turn "three copies" into "three copies in three different buildings" — which is the difference between surviving a disk failure and surviving a burglary.

The mesh is the only network. Garage nodes authenticate to each other with a shared RPC secret, but in Junk Net they also can't even reach each other except through Nebula, which requires a certificate signed by the project CA. Two independent locks.

Old laptops are a feature, not a compromise. Laptops idle at 10–25 W, have built-in batteries that ride out power blips, and are the single most commonly retired form factor. Garage weights each node by its disk size, so a 2012 MacBook with 500 GB and a netbook with 120 GB can serve in the same cluster, each pulling their own weight.

Boring tools, deliberately. Debian, systemd, Garage, Nebula. Every piece is open source, documented, and debuggable by a curious volunteer at a kitchen table. No Kubernetes, no blockchain, nothing that needs a team to babysit.

Dig deeper¶