If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ipfs/kubo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 8 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ipfs/kubo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ipfs/kubo.

What it runs against: a local clone of ipfs/kubo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ipfs/kubo | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ipfs/kubo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ipfs/kubo.git
#   cd kubo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ipfs/kubo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ipfs/kubo(\\.git)?\\b" \\
  && ok "origin remote is ipfs/kubo" \\
  || miss "origin remote is not ipfs/kubo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/ipfs/kubo/daemon.go" \\
  && ok "cmd/ipfs/kubo/daemon.go" \\
  || miss "missing critical file: cmd/ipfs/kubo/daemon.go"
test -f "client/rpc/api.go" \\
  && ok "client/rpc/api.go" \\
  || miss "missing critical file: client/rpc/api.go"
test -f "blocks/blockstoreutil/remove.go" \\
  && ok "blocks/blockstoreutil/remove.go" \\
  || miss "missing critical file: blocks/blockstoreutil/remove.go"
test -f "GNUmakefile" \\
  && ok "GNUmakefile" \\
  || miss "missing critical file: GNUmakefile"
test -f ".github/workflows/gotest.yml" \\
  && ok ".github/workflows/gotest.yml" \\
  || miss "missing critical file: .github/workflows/gotest.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ipfs/kubo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Kubo is the reference Go implementation of IPFS (InterPlanetary File System), a peer-to-peer distributed file system that replaces traditional centralized web servers. It provides content-addressed storage using Content Identifiers (CIDs), runs as a network daemon with mDNS/DHT discovery, and serves content via HTTP Gateways while supporting verifiable data transfer through Bitswap and trustless HTTP protocols. Kubo follows a monolithic structure: the main daemon code likely lives in cmd/ipfs/, core node logic in a root-level package structure, with examples/kubo-as-a-library/ demonstrating library usage. Assets (init documentation, UI assets) reside in assets/, configuration and CI pipelines occupy .github/workflows/, and comprehensive testing spans unit tests (gotest), integration tests (sharness.yml using shell scripts), and conformance tests (gateway-conformance.yml).

IPFS node operators, distributed systems engineers, and developers building decentralized applications who need a production-grade peer-to-peer file sharing and storage system. Contributors range from core IPFS protocol maintainers to application developers integrating IPFS into their systems via the CLI, HTTP RPC API, or Go library.

Kubo is production-ready and actively maintained. The repository shows comprehensive CI/CD coverage (15+ GitHub workflows including conformance testing, platform builds, and security analysis), a mature release process with semantic versioning, and recent development activity. It's the most widely deployed IPFS implementation with extensive test coverage via gobuild.yml, gotest.yml, and sharness.yml.

The dependency tree is substantial (100+ transitive dependencies visible in go.mod including cryptographic libraries, storage backends like pebble, and libp2p networking stack), but actively maintained with dependabot automation. Risk factors include the complexity of distributed systems code and protocol changes requiring coordination across the IPFS ecosystem; however, the extensive test matrix (gobuild across platforms, gateway-conformance.yml, interop testing) mitigates this. Single large repo structure means changes affect the entire codebase.

The project shows active development with workflows for generated PRs (generated-pr.yml), automated dependency updates (dependabot.yml), and recent additions of gateway conformance testing and delegated routing support (documented in docs/delegated-routing.md). Multiple parallel efforts are visible: platform compatibility (build-platforms.yml), security hardening (codeql-analysis.yml), spell-checking (spellcheck.yml), and test migrations (test-migrations.yml).

Clone the repo and initialize: git clone https://github.com/ipfs/kubo && cd kubo. Build the daemon: make build. Run it: ./cmd/ipfs/ipfs daemon. The Makefile and GNUmakefile define build targets; check CONTRIBUTING.md for development setup. The project supports Go 1.26.2+ as evidenced by the example go.mod.

Daily commands: For daemon mode: make build && ./cmd/ipfs/ipfs daemon (listens on /ip4/127.0.0.1/tcp/5001 for API by default). For CLI operations once running: ipfs add <file>, ipfs get <cid>, ipfs pin add <cid>. Development: make test runs Go tests via gobuild.yml patterns. Full CI invocation: make lint && make test && make check.

• cmd/ipfs/kubo/daemon.go — Entry point for the IPFS daemon—controls initialization, configuration loading, and lifecycle management that every contributor working on core functionality must understand.
• client/rpc/api.go — Primary RPC API interface that exposes all IPFS commands to external clients; foundational for understanding how the daemon communicates with users.
• blocks/blockstoreutil/remove.go — Core blockstore utility for managing content blocks; critical for anyone working on data persistence, garbage collection, or pinning.
• GNUmakefile — Build and test orchestration; required reading for understanding the development workflow, CI/CD triggers, and how to run the full test suite.
• .github/workflows/gotest.yml — Test automation pipeline that validates all Go code; essential for understanding test expectations and continuous integration patterns.
• CONTRIBUTING.md — Contributor guidelines, code review expectations, and PR process; mandatory for anyone submitting changes to the repository.
• go.mod — Module dependencies and versioning (inferred from description); defines all external libraries and their versions that the codebase relies on.

• RPC API (client/rpc/api.go) (HTTP, JSON, multipart form data) — Routes HTTP requests to command handlers, parses multipart uploads, serializes responses, and validates input
  • Failure mode: Request parsing fails → 400 Bad Request; handler panics → 500 Internal Server Error; missing CID → 404 Not Found
• Daemon (cmd/ipfs/kubo/daemon.go) (Go context, signal handlers, IPFS config files) — Initializes core node, loads config, starts HTTP listener, manages graceful shutdown, and coordinates startup migrations
  • Failure mode: Config missing → panic; port in use → fail to bind listener; migration error → refuse startup
• Blockstore (blocks/blockstoreutil/remove.go) (Embedded key-value store, file I/O, CID indexing) — Handles persistent storage of content blocks, garbage collection, and block deletion with pinning constraints
  • Failure mode: Disk full → write fails; corruption → integrity check fails; pinned block deletion → constraint violation error
• libp2p Network (via go-libp2p dependency) — undefined

Add a new RPC command handler

1. Create a new file in client/rpc/ named after your command (e.g., client/rpc/mycmd.go) (client/rpc/mycmd.go)
2. Implement handler function following the pattern in client/rpc/block.go (parse args, call core logic, return serialized response) (client/rpc/block.go)
3. Register the handler in client/rpc/api.go by adding a route in the API initialization (client/rpc/api.go)
4. Add tests in client/rpc/api_test.go to verify your command works end-to-end (client/rpc/api_test.go)
5. Document the command in assets/init-doc/ for user-facing help (assets/init-doc/help)

Modify daemon initialization or configuration

1. Edit cmd/ipfs/kubo/daemon.go to add new initialization steps or config loading logic (cmd/ipfs/kubo/daemon.go)
2. If config needs migration, add migration rules in cmd/ipfs/kubo/add_migrations.go (cmd/ipfs/kubo/add_migrations.go)
3. Update GNUmakefile test targets if your change requires new test fixtures (GNUmakefile)
4. Add integration tests in .github/workflows/sharness.yml if testing against live IPFS behavior (.github/workflows/sharness.yml)

Extend blockstore or storage behavior

1. Modify or extend blocks/blockstoreutil/remove.go for garbage collection and deletion logic (blocks/blockstoreutil/remove.go)
2. Update relevant RPC handlers (e.g., client/rpc/pin.go) if storage behavior affects pinning (client/rpc/pin.go)
3. Add unit tests alongside your changes and verify with 'make test' (defined in GNUmakefile) (GNUmakefile)

• Go — Performance-critical daemon with heavy I/O; Go's goroutines and static compilation enable efficient peer-to-peer networking at scale.
• HTTP RPC API — Language-agnostic interface allowing any client (JavaScript, Python, Rust, etc.) to control the IPFS node via standard HTTP.
• libp2p (go-libp2p) — Modular peer-to-peer networking library providing multi-address support, transport negotiation, and protocol multiplexing for decentralized communication.
• Content-addressed blocks — Core IPFS abstraction; immutable content hashing ensures data integrity and enables deduplication across the network.
• Docker — Simplified deployment and testing; isolated environments reduce dependency conflicts and enable reproducible node setups.

• Monolithic daemon vs. microservices

  • Why: IPFS requires tight coupling between block storage, DHT lookups, and pinning; splitting into services would add latency and complexity.
  • Consequence: Single point of failure per node, but simplifies deployment and reduces network overhead.

• HTTP RPC over native binary protocol

  • Why: HTTP enables browser and lightweight client support; REST is familiar to most developers.
  • Consequence: Slightly higher overhead than raw libp2p, but massive gain in accessibility and ecosystem compatibility.

• Embedded documentation (assets/init-doc) vs. external wiki

  • Why: Ensures documentation is versioned with code and always available offline.
  • Consequence: Requires binary to distribute docs; changes require releases instead of wiki edits.

• Real-time consensus across IPFS network nodes—Kubo is a single autonomous node, not a distributed consensus system.
• Support for encrypted private data on public DHT—IPFS assumes content is publicly addressable by default.
• SQL database engine—Kubo uses key-value blockstores, not relational databases.
• Platform abstraction beyond Go's standard library—Windows/macOS/Linux supported via Go, but Kubo is not a cross-language framework.

Configuration state defaults to ~/.ipfs/ on Linux/Mac and %APPDATA%/ipfs/ on Windows; if tests fail mysteriously, check for stale daemon state. The IPFS daemon must be explicitly started (ipfs daemon) before CLI operations like ipfs add work—there's no background service by default. Building requires Go 1.26.2+; older versions will fail. Makefile invokes GNUmakefile which may not work on non-GNU make systems (use gmake on BSD). The example module at examples/kubo-as-a-library uses a replace directive pointing to the workspace root—don't copy it as-is without adjusting the path. Port 5001 (API) and 4001 (swarm) are default and may conflict on developer machines.

• Content Identifier (CID) — Kubo's entire data model revolves around CIDs—cryptographic hashes that uniquely identify immutable content; essential to understand for file operations and deduplication
• Distributed Hash Table (DHT) — Kubo's Amino DHT enables peer discovery and content location without centralized servers; critical for understanding how nodes find each other and retrieve content
• UnixFS — Kubo's opinionated file system abstraction that converts POSIX directories and permissions into content-addressed DAGs; necessary for understanding how files are stored and retrieved
• Bitswap Protocol — Kubo's data exchange protocol for requesting and trading blocks between peers; understanding it is essential for performance tuning and network debugging
• Directed Acyclic Graph (DAG) — IPFS data structures are immutable DAGs; Kubo's core relies on DAG operations for content linking and traversal
• Trustless HTTP Gateway — Kubo implements verifiable content retrieval via HTTP without trusting the gateway operator; combines CIDs with cryptographic proofs for browser access
• HTTP Routing V1 (Delegated Routing) — Kubo's modern routing alternative to DHT queries; allows nodes to delegate content location lookups to external services, reducing network overhead

• ipfs/boxo — Core IPFS protocol libraries (v0.39.1+) that Kubo depends on; contains DAG, IPLD, UnixFS, and Bitswap implementations
• libp2p/go-libp2p — Peer-to-peer networking stack (v0.48.0) used by Kubo for mDNS, DHT, and swarm communication
• ipfs/js-ipfs — JavaScript implementation of IPFS providing feature parity across ecosystems; alternative for browser/Node.js environments
• ipfs/ipfs-webui — Web-based UI for Kubo node management; paired with the daemon for user-friendly node control
• protocol-labs/probelab — Topology analysis and monitoring of the IPFS network used by Kubo; provides observability for production deployments

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for kubo-as-a-library example

The examples/kubo-as-a-library directory has a go.mod file but there's no corresponding test coverage in the visible CI workflows. This example is critical for users embedding Kubo as a library. Adding comprehensive integration tests would catch breaking changes early and provide developers with working examples of library usage patterns.

• [ ] Create examples/kubo-as-a-library/main_test.go with tests for core library operations (node initialization, adding/getting content, DHT operations)
• [ ] Add a new GitHub Actions workflow file .github/workflows/example-library-test.yml to run these tests on every PR
• [ ] Document tested scenarios in examples/kubo-as-a-library/README.md (if missing)

Add missing spell-check and lint rules for Go code comments

The repo has .cspell.yml and .golangci.yml configured, but based on the extensive Go codebase, there may be gaps in enforcing code comment quality and consistency. This improves code maintainability and documentation for future contributors. The spellcheck workflow exists but may need tuning for Go-specific comment patterns.

• [ ] Audit .golangci.yml to ensure comment-related linters (like godot for sentence endings) are enabled and configured
• [ ] Review .cspell.yml and add Go-specific dictionary entries for common IPFS/P2P terminology (libp2p, DHT, CID, etc.)
• [ ] Run the spellcheck workflow locally against all Go files and fix any identified comment issues in core packages

Create end-to-end migration test workflow for datastore upgrades

The .github/workflows/test-migrations.yml workflow exists but appears minimal. Given that Kubo is a critical infrastructure tool with persistent datastores, there's likely a need for more comprehensive migration testing. A better-documented and expanded migration test suite would catch datastore compatibility regressions that could break user deployments.

• [ ] Expand .github/workflows/test-migrations.yml to test migrations across multiple IPFS versions (e.g., v0.20 → current, v0.19 → current)
• [ ] Add test cases in the workflow for different storage backends (flatfs, badger, pebble) if not already covered
• [ ] Create or update documentation in docs/ or CONTRIBUTING.md detailing how to add new migration tests and the testing procedure

• Add integration tests for the HTTP Routing V1 client to increase coverage beyond the server-side tests visible in gateway-conformance.yml—current test matrix doesn't clearly show delegated routing client validation.
• Improve error messages in the CLI (cmd/ipfs/) for common user mistakes like attempting ipfs add when daemon isn't running—currently relying on generic connection-refused errors.
• Extend spell-check configuration (.cspell.yml) to catch IPFS-specific terminology misspellings in code comments and docs, since the current ruleset likely only covers common English words.

• High · Exposed API Port Without Authentication Enforcement — docker-compose.yaml - service 'ipfs' port mapping for 5001. The docker-compose.yaml configuration exposes port 5001 (IPFS API) bound to 127.0.0.1, which limits remote access. However, the configuration lacks explicit authentication enforcement at the application level. The API port includes admin operations and should have strong access controls. Fix: Ensure the IPFS daemon is configured with authentication tokens (API key/JWT) for all admin operations. Review kubo configuration for API authentication settings. Consider using a reverse proxy with authentication in front of the API port.
• High · Swarm Port Exposed to All Interfaces — docker-compose.yaml - service 'ipfs' port mapping for 4001. Port 4001 (IPFS Swarm) is exposed on all network interfaces (0.0.0.0) for both TCP and UDP. While this is necessary for IPFS P2P networking, it creates a potential attack surface for network-based exploits and DDoS attacks. Fix: Implement network-level access controls and firewall rules to restrict Swarm port access to trusted peers only. Consider using IPFS peering configuration to whitelist known peers. Monitor for suspicious connection patterns.
• Medium · Unvetted Transitive Dependencies — go.mod - indirect dependencies section. The go.mod file includes numerous transitive dependencies with versions that appear to be development/pre-release builds (dates in 2026, 2025). Several dependencies lack clear maintenance status: crackcomm/go-gitignore and others in the truncated list. This increases risk of supply chain attacks and unmaintained code vulnerabilities. Fix: Conduct a full audit of all transitive dependencies using 'go mod graph' and vulnerability scanners like 'nancy' or 'govulncheck'. Replace or update unmaintained dependencies. Use dependency scanning in CI/CD pipeline (already present in workflows).
• Medium · Docker Build Cache Without Verification — Dockerfile - RUN with cache mount for /go/pkg/mod. The Dockerfile uses BuildKit cache mounts for Go modules without verifying their integrity. The 'go mod download' step caches modules, but there's no checksum verification visible before the COPY operation. Fix: Ensure 'go mod verify' is run after 'go mod download' to verify module checksums. Add security scanning to the build pipeline. Consider using 'go mod tidy' verification in CI before building.
• Medium · Insufficient IPFS Data Volume Permissions Control — docker-compose.yaml - volume definitions for ipfs_path, ipfs_fuse, ipns_fuse. The docker-compose.yaml mounts ipfs_path:/data/ipfs without specifying volume driver or permission constraints. This could potentially expose sensitive IPFS data or allow privilege escalation if misconfigured. Fix: Explicitly define volume permissions and drivers. Use named volumes with explicit permission settings. Consider using bind mounts with restricted file permissions (700 for sensitive data). Document security implications of FUSE mounts.
• Low · Missing Security Headers Configuration — docker-compose.yaml - HTTP Gateway port 8080. While the HTTP Gateway is exposed on port 8080, there is no visible configuration for security headers (CORS, CSP, X-Frame-Options, etc.) in the provided configuration files. Fix: Configure appropriate HTTP security headers in the IPFS gateway configuration. Review kubo gateway settings for CORS policy, Content-Security-Policy headers, and X-Content-Type-Options. Use a reverse proxy if needed for header injection.
• Low · No Resource Limits Defined — docker-compose.yaml - service 'ipfs' definition. The docker-compose.yaml lacks resource constraints (cpu, memory limits) for the IPFS service, which could allow resource exhaustion attacks or uncontrolled consumption. Fix: Add 'deploy.resources.limits' and 'deploy.resources.reservations' to constrain CPU and memory usage. Set appropriate limits based on expected workload and available resources.
• Low · Restart Policy Could Mask Security Issues — undefined. The 'restart: unless-stopped' policy in docker-compose.yaml could mask persistent security failures by automatically restarting a compromised Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.