🧭 Needle

Needle is IPNI's hard fork of ipfs/someguy, an HTTP Delegated Routing V1 server that proxies requests to the Amino DHT and other delegated routing servers. IPNI runs it publicly at https://delegated-ipfs.dev/routing/v1. At v1.0.0 the config, metrics and image names all changed: the SOMEGUY_ env prefix is now NEEDLE_, metric series moved from someguy_ to needle_, and the image is ghcr.io/ipni/needle.

Build

go build -o needle

Install

go install github.com/ipni/needle@latest

Docker

Automated Docker container releases are available from the Github container registry:

• 🟢 Releases
  • latest always points at the latest stable release
  • vN.N.N point at a specific release tag
• 🟠 Unreleased developer builds
  • main-latest always points at the HEAD of the main branch
  • main-YYYY-DD-MM-GITSHA points at a specific commit from the main branch
• ⚠️ Experimental, unstable builds
  • staging-latest always points at the HEAD of the staging branch
  • staging-YYYY-DD-MM-GITSHA points at a specific commit from the staging branch
  • This tag is used by developers for internal testing, not intended for end users

When using Docker, pass configuration via -e:

$ docker pull ghcr.io/ipni/needle:main-latest
$ docker run --rm -it --net=host ghcr.io/ipni/needle:main-latest

See /docs/environment-variables.md.

Usage

Run needle as a client or as a server.

Server

Start the server with needle start. By default it proxies requests to the IPFS Amino DHT and other Delegated Routing V1 servers.

For more details, run needle start --help.

Client

To query an existing server without running one yourself, use needle ask <subcommand> to look up a provider, peer, or IPNS record.

For more details, run needle ask --help.

AutoConf

Automatic configuration of bootstrap peers and delegated routing endpoints. When enabled (default), Needle replaces the auto placeholder with network-recommended values fetched from a remote URL.

Configuration:

• --autoconf / NEEDLE_AUTOCONF
• --autoconf-url / NEEDLE_AUTOCONF_URL
• --autoconf-refresh / NEEDLE_AUTOCONF_REFRESH

Endpoint flags (default to auto):

• --provider-endpoints / NEEDLE_PROVIDER_ENDPOINTS
• --peer-endpoints / NEEDLE_PEER_ENDPOINTS
• --ipns-endpoints / NEEDLE_IPNS_ENDPOINTS

To use custom endpoints instead of auto:

needle start --ipns-endpoints https://example.com

See environment-variables.md for URL formats and configuration details.

Documentation

• environment-variables.md: all config flags and environment variables
• peer-address-caching.md: how /providers and /peers cache and refresh peer addresses, and the trade-offs behind what needle deliberately does not do
• response-streaming.md: NDJSON streaming contract, the timeout budget, and traps that break streaming
• dnsaddr-resolution.md: why /dnsaddr is resolved before filter-addrs, and how it is bounded
• metrics.md: Prometheus metrics
• tracing.md: OpenTelemetry tracing

Deployment

For self-hosting, run the prebuilt Docker image.

Release

1. Create a PR from branch release-vX.Y.Z against main that:
   1. Updates CHANGELOG.md with entries for the current release
   2. Updates the version.json file
2. Once the release checker creates a draft release, copy-paste the changelog into the draft
3. Merge the PR; the release workflow tags and publishes automatically

License

Dual-licensed under MIT + Apache 2.0