hanami

KO | EN

gitlite — search

#javascript #ai #typescript #golang #go #machine-learning #linux #docker #java #windows #vue #awesome-list #ios #open-source

(★ 12)

No description available.

hanami Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hanami

A self-hosted **Blossom server with a UI on top**: and a generic client for
*any* Blossom server. One Go binary: run your own content-addressed blob store
for a trusted group of npubs, and browse your blobs across every server you
declare, from a server-rendered interface.

Sibling to [torii](https://github.com/Letdown2491) ("a relay with a UI on top"):
same shape, same sumi-e identity, same stances, **keyless** (your nsec never
touches the daemon), private-by-default, thin, dependency-light, ~zero JS.

It is a Go rewrite of [Bloom](https://github.com/Letdown2491/bloom), a TypeScript
Blossom client, rebuilt in Go for a single static binary, native crypto, and
consistency with the Go-based infrastructure in the same ecosystem. Because it
targets the same on-relay formats, it stays interoperable with Bloom: the same
`bloom-folder:` folder lists, the same private-list format, and byte-for-byte-
compatible private-blob encryption, so your folders and files move between the
two without conversion. The Go packages carry `// Ports …ts` attributions to
their Bloom origins.

## What it does

- **Built-in Blossom server**: built on `khatru/blossom`, the same
  production-proven Blossom module [haven](https://github.com/barrydeen/haven) uses,
  over a content-addressed filesystem store, gated to a trusted allowlist of npubs.
  Passes the [blossom-compliance](https://github.com/hzrd149/blossom-compliance)
  suite clean; see [BUD support](#bud-support) for exactly what's implemented.
- **Keyless sign-in**: a NIP-07 browser extension (Alby, nos2x, …) or a NIP-46
  bunker; your key never touches the daemon. Any whitelisted npub can sign in,
  the `owner_npub` is the admin. The session **persists** across restarts and
  reconnects without re-approval.
- **Multi-member**: whitelist several npubs, each with an isolated space (their
  own files, folders, and settings; identical uploads are not deduped across
  members). The owner admin section adds/removes members, sets per-member storage
  quotas, and removes with keep-or-purge of their files. Deletion is refcounted,
  so removing a shared blob never affects another member's copy.
- **Cross-server library**: lists your blobs across every server in your
  `kind-10063` list, deduped by hash, each showing **where it lives** (local
  and/or how many servers), corrected with HEAD-verified placement. The built-in
  store is folded in in-process.
- **Encrypted drive**: files and folders are one encrypted event kind (`30630`),
  private by default, so relays and Blossom servers hold only opaque ciphertext and
  never learn your folder structure. Id-based parents make folder move and rename
  O(1) (no per-file rewrite); folders carry a color and emoji. Create, move, rename,
  merge (unioning same-named subfolders), download a folder's public files as a zip,
  and recursively delete, all as node edits, with drill-down navigation and
  folder-tree pickers. The library is defined by this drive index rather than
  reassembled from separate events; a one-way, non-destructive **Bloom Migration**
  imports a legacy library, and an **Unindexed** view surfaces blobs not yet in the
  drive so nothing looks lost. The drive key and nodes, which otherwise live only on
  relays, are kept in a durable local store (and backed up to peers): reads are served
  from that local store first, so the library paints instantly even right after a restart,
  and the relays are reconciled in the background, with any relay that dropped an event
  re-seeded from the local copy, so a relay prune or loss can't take the index or your
  private-file keys with it. The drive is the default storage model:
  a fresh instance starts on an empty drive, and a pre-drive library is brought in via
  a one-time, non-destructive Bloom import. **Private files** additionally encrypt the blob with a per-file key
  before upload (Blossom only ever stores ciphertext); decrypt-and-serve with Range
  support for media seeking.
- **Settings follow your account** (NIP-78): layout, sort, upload and share
  defaults, wallpaper, pinned favorites, and Blossom-server display names sync
  through an encrypted app-data record keyed to your npub, so a new device inherits
  them after sign-in. A per-account toggle keeps them device-local instead. Pin any
  file or folder to a dedicated Pinned section in the sidebar.
- **Upload / delete / bulk actions**: store on the built-in server and
  replicate to your declared servers via your signer, with an optional
  downscale-on-upload that caps a large image's longest edge before it's stored
  (off by default; Settings → Uploads); multi-select for batch delete, copy,
  move, and zip download.
- **Share links**: mint a link to a file, or a whole folder, that anyone can view
  in a browser, or restrict it to a specific npub (they sign in with that Nostr
  key). Server-mediated so it can actually expire or be revoked: for a private
  file hanami records the key at creation and `/s/<id>` decrypts-and-serves (so
  Blossom and relays still only ever see ciphertext); a public file is proxied
  as-is; a folder share is a browsable snapshot of its subtree. A "Shared" view in
  the sidebar lists every link with its audience, expiry, and age, and revokes any. A
  Settings → Sharing pane holds the instance controls (public-read toggle, a
  master switch) and per-folder "don't allow sharing". Works while your instance
  is online at a public URL.
- **Durability**: keep every file on at least N locations. Placement is
  HEAD-verified (BUD-12 marks `/list` optional and servers under-report it) and
  trusted as the source of truth, kept fresh by a background scrub that runs by
  default, so the "x of y synced" status and per-server sidebar counts are right
  without a manual repair; a check-&-repair panel tops up under-replicated files.
- **Federation peers**: a private backup tier of your own other instances, kept
  out of your public kind:10063 list. Each instance has a persistent node key and,
  in the background (no sign-in, no signer prompts), streams a copy of its blobs to
  every peer it has a URL for, staying the sole bridge (a peer never learns your
  public servers, so it's NAT/Tailscale-friendly), private files replicate as
  ciphertext. A peer's node key authorizes its backups on its own, so the member
  list stays humans-only. Settings → Peers manages them, with live backup status.
- **Inline preview**: images (proxied, resized thumbnails) and text / Markdown
  / code, rendered with an owned CommonMark-subset renderer (no extra
  dependencies). Videos get grid posters captured client-side (no ffmpeg) and
  cached locally, with a play badge; public posters are shared by hash, private
  ones cached per-owner.
- **Music player**: play an audio file and it keeps playing while you browse
  folders, open Settings, or search. The folder you played from becomes the queue
  (or the search result, or all your audio if you came from Kinds), with previous,
  next and auto-advance in whatever sort order you are viewing. Media keys and the
  lock screen work. Encrypted tracks held on this server stream and scrub without
  downloading first.
- **Make it yours**: name your Blossom servers (they show throughout the UI
  instead of bare hostnames, stored as a NIP-78 event that follows your npub) and
  set any image as the desktop wallpaper behind the window.

## Run

**Download a release binary** for your platform (Linux, macOS, or Windows;
amd64/arm64) from the [Releases page](https://github.com/Letdown2491/hanami/releases),
verify it against `SHA256SUMS`, then:

```sh
cp config.example.toml config.toml     # then set owner_npub to your npub (you become the admin)
./hanami -config config.toml           # → http://127.0.0.1:8787
```

Or run from source (requires Go ≥ 1.26, no separate build step):

```sh
cp config.example.toml config.toml     # then set owner_npub to your npub
go run ./cmd/hanami                     # → http://127.0.0.1:8787
```

Open <http://127.0.0.1:8787> and sign in with your NIP-07 browser extension or a
`bunker://…` URI. The `owner_npub` is the admin and is always a member; add more
npubs to `members` to let others in.

**New to Nostr?** You need a key and a signer that holds it. Create one with a browser
extension ([Alby](https://getalby.com), nos2x) or a bunker signer
([Signet](https://github.com/letdown2491/signet), Amber on Android), copy your `npub1…`
into `owner_npub`, and sign in with that same signer. hanami never sees your secret key.

## Docker

Pull the pre-built image (published to GitHub Container Registry on every release,
multi-arch linux/amd64 + linux/arm64):

```sh
cp config.docker.toml.example config.docker.toml   # add your owner_npub; keep data_dir = "/data"
docker run -d --name hanami \
  -p 127.0.0.1:8787:8787 \
  -v hanami-data:/data \
  -v "$PWD/config.docker.toml:/etc/hanami/config.toml:ro" \
  ghcr.io/letdown2491/hanami:latest         # or pin a version, e.g. :0.13.0
```

Open <http://127.0.0.1:8787>. The image runs as a non-root user and stores blobs +
the index in the `hanami-data` volume.

Or build from source with Compose (handy for local hacking):

```sh
cp config.docker.toml.example config.docker.toml   # add your npub
docker compose up -d --build                       # → http://127.0.0.1:8787
```

Both bind to loopback by default. Publish it wider (a LAN or Tailscale IP) only
behind a TLS reverse proxy, see [`DEPLOY.md`](DEPLOY.md).

On first boot the log may warn that the dashboard is served over plaintext HTTP. With the
loopback-published port above that is expected and safe: hanami can't see the host-side
`-p 127.0.0.1:…` mapping, only its own `0.0.0.0` bind inside the container. It matters only
if you publish the container to a non-loopback address without a TLS proxy.

## Config (`config.toml`)

```toml
listen_addr = "127.0.0.1:8787"
data_dir = ".data"
service_url = "http://127.0.0.1:8787"
owner_npub = "npub1youownernpub…"   # the instance admin (manages members + quotas)
members = []                         # whitelisted npubs; each gets an isolated space
allow_public_reads = true
redundancy_target = 3
# scrub_interval_min = 180           # background durability scrub default; 0/unset = default, negative = off (owner can change it live in Settings)
# max_blob_size = 100000000          # per-upload byte cap (default 100 MB)
# max_concurrent_uploads = 8         # cap on in-flight ingestions (peak memory ≈ this × max_blob_size); lower it on a small host
# restrict_servers_to_public = false # true = reject member server URLs on loopback/LAN/CGNAT (public instances)
# request_timeout_sec = 1800         # whole-request read+write deadline; 0/unset = 30 min, negative = off (rely on your reverse proxy)
# bootstrap_relays = ["wss://relay.primal.net", "wss://purplepag.es", "wss://nos.lol"]  # relays used only to find a user's NIP-65 relay list; set to ones your host can reach
# nip11_icon_url = "https://cdn.example/icon.png"    # image URL advertised in the public NIP-11 doc (defaults to a CDN so directory crawlers don't hit your server)
# nip11_banner_url = "https://cdn.example/banner.jpg"

# Federation peers (private backup tier; also addable live in Settings → Peers):
# peer_quota = 10000000000            # global cap (bytes, 10 GB here) on what a peer may back up here; 0 = unlimited
# [[peers]]
# url   = "https://backup.example"    # where this instance backs up to (outbound)
# npub  = "npub1peernodekey…"         # the peer's node key, whose backups we accept (inbound)
# name  = "Backup box"                # optional label
# quota = 5000000000                  # optional per-peer inbound cap (bytes, 5 GB here); overrides peer_quota
```

- **`owner_npub`**: the instance admin. Always a member, and the only key that can
  manage the whitelist and per-member storage quotas (Settings → Members).
- **`members`**: the whitelisted npubs. Each can sign into the dashboard with its
  own isolated space and upload/delete/list on the built-in Blossom server over
  the wire (BUD-11). Empty = owner-only.
- **`allow_public_reads`**: when `false`, `GET /<sha>` is member-gated too
  (a fully private instance). Blobs are content-addressed, so public reads are
  the common default.
- **`redundancy_target`**: keep each file on at least this many locations
  (built-in store + declared servers); drives the durability status and repair.
- **`[[peers]]`**: federation peers, a private backup tier of your own other
  instances, out of the public kind:10063 list. Each entry has a `url` this
  instance backs up to and/or an `npub` (the peer's node key) whose backups this
  instance accepts; `name` is optional. Config peers are pinned; more can be added
  live in Settings → Peers. This instance's own node key (shown there) is what a
  peer whitelists to accept your backups. A peer's inbound backups can be capped:
  `peer_quota` sets a global default (bytes; 0 = unlimited) and a per-peer `quota`
  overrides it (also editable in Settings → Peers).
  - The node key itself lives in **`<data_dir>/instance_key`** (0600),
    auto-generated on first launch. To use a specific identity instead, write it
    there before first launch as either raw hex or a bech32 `nsec1…`. The same
    key can drive a FIPS mesh transport (`FIPS_NSEC`); hanami accepts any peer
    URL, including a `<npub>.fips` host (those are auto-allowed, no
    `allowed_hosts` entry needed).
- **`scrub_interval_min`**: how often the background durability scrub HEAD-verifies
  placement and tops up under-replicated files (keeps the "synced" counts fresh
  without a manual repair). `0`/unset uses a sensible default; a negative value
  disables it. This is only the seed default: the owner can change the interval,
  or turn it off, live in Settings > Storage (persisted, no restart).
- **`bootstrap_relays`**: the relays used only to find a signed-in user's NIP-65
  relay list (kind:10002); once found, reads go to the user's own relays, and a
  user's discovered servers/relays persist across restarts. Set this to relays
  your host can actually reach that hold your list, so discovery doesn't depend on
  hardcoded relays that may be dead or unreachable from where hanami runs. Unset
  uses a built-in default.
- **`nip11_icon_url`** / **`nip11_banner_url`**: the image URLs advertised in the
  public **NIP-11** relay document (what relay-directory crawlers like nostr.watch
  read). These default to a **CDN**, not your own server, so those crawlers don't
  put traffic on your instance. Set them to your own CDN if you want custom
  directory branding, or to your `service_url` + `/icon` / `/banner` if you'd
  rather self-host and accept the crawler traffic. (The sign-in card always shows
  the built-in hanami banner, served same-origin as its CSP requires.)
- **`nip11_contact`**: the administrative contact advertised in the NIP-11
  document. Validators flag a document without one, so this defaults to your owner
  npub, which that document already publishes in its `pubkey` field. Set an email
  or URI (`mailto:you@example.com`) to publish that instead.
- **`request_timeout_sec`**: a finite whole-request read+write deadline so no
  reverse proxy is strictly required to bound a slow client. `0`/unset is 30
  minutes (generous for a large upload/download on a slow link); a negative value
  disables it to rely on your reverse proxy.
- For a public instance set `allowed_hosts` and `trusted_proxies` and put it
  behind a TLS-terminating reverse proxy, see
  [deploy/PUBLIC-DEPLOYMENT.md](deploy/PUBLIC-DEPLOYMENT.md). Otherwise bind to
  loopback and reach it over Tailscale/Tor.

## Reaching a peer over FIPS (optional)

A peer needs a URL you can reach. If both instances are behind NAT with no
public address, [FIPS](https://fips.network) (a separate mesh daemon, never
bundled) can give each a stable `<npub>.fips` address to back up over. hanami
just speaks HTTP to that hostname; FIPS does the routing at the OS layer.

The trick is that **one identity drives both**: hanami's node key is the FIPS
node identity, so `<npub>.fips` is the same npub your peers already authorize.
On each box:

1. **Install FIPS** ([github.com/jmcorgan/fips](https://github.com/jmcorgan/fips))
   and point it at hanami's key. FIPS's `node.identity.nsec` config field accepts
   raw hex and always overrides its auto-generated `fips.key`, and hanami's key is
   hex, so in `/etc/fips/fips.yaml`:

```yaml
   node:
     identity:
       nsec: "<paste the contents of your hanami data_dir/instance_key>"
   ```

`chmod 600 /etc/fips/fips.yaml` (it now holds a secret) and restart FIPS.
   Confirm `fipsctl show status | jq .npub` matches the node key shown in
   Settings → Peers.
2. **Bind hanami to the mesh**: `listen_addr = "[::]:8443"`. `.fips` hosts are
   auto-allowed, so no `allowed_hosts` entry is needed.
3. **Add the peer** in Settings → Peers with URL `http://<their-npub>.fips:8443`
   and authorize its node key: the normal peer flow, just over a `.fips` URL.
   FIPS handles discovery (a Nostr relay for internet peers, or mDNS on a LAN).

A containerized sidecar starter (identity injected from hanami's key file) is in
[deploy/fips-sidecar/](deploy/fips-sidecar/): experimental, verify against your
FIPS release.

## BUD support

hanami passes the [blossom-compliance](https://github.com/hzrd149/blossom-compliance)
suite clean: no warnings, no failures, and the only skips are optional features it
reports honestly instead of faking.

| BUD | Status | Notes |
| --- | --- | --- |
| **01** Server basics | Yes | `GET`/`HEAD /<sha256>[.ext]`, range requests, CORS, `X-Reason`. `Sunset` is parsed as a client but never emitted: hanami doesn't expire blobs. |
| **02** Upload | Yes | `PUT /upload` + blob descriptors. A declared `X-SHA-256` is verified against the bytes (409 on mismatch). |
| **03** User server list | Yes | Reads and writes `kind:10063`, priority-ordered, and heals retrieval across the list. |
| **04** Mirror | Yes | `PUT /mirror` inbound, SSRF-screened (metadata and link-local denied, post-resolution, redirects re-validated; private ranges too under `restrict_servers_to_public`) and size-bounded, hash-verified against the token's `x` tag; also mirrors outbound to your other servers. |
| **05** Media | Yes, identity | `PUT`/`HEAD /media` store the original bytes unchanged. hanami transcodes nothing, so the unchanged sha in the descriptor is the honest signal that nothing was optimized. This wire endpoint strips no EXIF; the dashboard's own upload path has an optional metadata stripper. |
| **06** Upload requirements | Yes | `HEAD /upload` answers truthfully before you send bytes: 411, 400, 401/403, or 413 when the size cap or your quota can't hold it. |
| **07** Paid upload/download | n/a | hanami never charges for uploads or reads, so there is nothing to pay. |
| **08** NIP-94 metadata | Yes | Upload, media, and mirror descriptors carry a `nip94` field (`url`, `m`, `x`, `size`) for clients that build a NIP-94 event from an upload. hanami publishes no standalone `kind:1063` events of its own. |
| **09** Blob report | No | `PUT /report` answers 501. hanami has no moderation queue, and pretending to accept reports is worse than refusing. |
| **10** `blossom:` URI | Yes | The view modal offers a `blossom:<sha>?as=…&xs=…&sz=…` link alongside the direct URL. |
| **11** Nostr authorization | Yes | `kind:24242` tokens, per-verb `t` tags, `x`/`server` scoping. A token naming a server this instance doesn't answer to is rejected as a replay. |
| **12** Blob management | Yes | `GET /list/<pubkey>` with `cursor`+`limit` pagination, plus `since`/`until`/`offset`; `DELETE` requires the token to name the blob. |

One caveat that the score doesn't show: hanami is **members-only**, so compliance means a
whitelisted npub's client works, not that any stranger's client can upload. An
unwhitelisted client gets a truthful 403, which is why running the suite against a live
instance without whitelisting its test key scores about 33% by design.

## Test

```sh
go test ./...          # unit + in-process integration (client ↔ server, bunker ↔ relay)
go test -race ./...    # data-race check (hanami's own code)
```

The crypto is vector-verified: private-blob and passphrase-envelope decryption
run against golden vectors produced by WebCrypto, and NIP-44 runs the official
paulmillr/nip44 reference set, so the on-wire formats stay byte-compatible with
existing data.

See [CHANGELOG.md](CHANGELOG.md) for notable changes.

## Contributing & security

Contributions and bug reports are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security vulnerabilities privately, see [SECURITY.md](SECURITY.md), not as a public issue.

## License

hanami

hanami Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hanami

hanami Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README