Helping humans and AI agents discover, verify, and use software safely.
Nipcode is the software search and trust layer for packages, code, models and developer tools. It helps humans and AI agents search public software sources, inspect trust signals, and generate reviewable install plans before anything writes to a workspace.
Nipcode does not replace package registries. It makes existing software ecosystems easier to search, compare and use safely.
API beta access requires a free beta key.
curl -s -X POST 'https://nipcode.xyz/api/keys/beta'
curl 'https://nipcode.xyz/api/search?q=http%20client&limit=3' -H 'x-nipcode-api-key: <key>'
curl 'https://nipcode.xyz/api/inspect?source=npm&name=undici' -H 'x-nipcode-api-key: <key>'
curl 'https://nipcode.xyz/api/install-plan?source=npm&name=undici' -H 'x-nipcode-api-key: <key>'
Tell an agent:
Use Nipcode before choosing a package.
Search sources, inspect the selected record and show the install plan.
Do not install or edit files until I approve.
Copyable HTTP client examples:
node --experimental-strip-types examples/http-api/agent-flow.ts "http client"
python3 examples/http-api/agent_flow.py "http client"
Humans and agents both need a safer way to choose outside software before code enters a real workflow. Agents can choose dependencies, write code, run commands and modify real workspaces, while humans still need clear evidence before approving that action.
Nipcode gives both humans and agents one preflight surface:
- Search supported sources.
- Inspect exact package records.
- Generate an install plan.
- Wait for user or host-policy approval.
- Optionally confirm useful discovery into the package intelligence archive.
Search ranking is never install permission. A popular package can still be compromised, stale, risky or blocked by policy.
| Step | Agent Receives | Boundary |
|---|---|---|
| Search | Candidates, source reports, selection.recommendedId, gates and rank reasons. |
Shortlist only. Not install approval. |
| Inspect | Exact source record, license, source URL, metrics, warnings and trust factors. | Source-owned metadata remains untrusted. |
| Install Plan | Commands, risk, package/version, approval boundary and blocked state. | Review data only. Hosted API never executes. |
| Archive Prepare | Receipt preview and reusable package intelligence shape. | Preview only unless an authorized writer confirms. |
| Source | Role |
|---|---|
| npm, JSR | JavaScript and TypeScript package metadata, releases, integrity, signatures and lifecycle-script risk. |
| PyPI, crates.io, Go modules, Maven Central, NuGet, RubyGems, Packagist | Language package metadata, release files, digests, source links, version state and install command risk. |
| Docker Hub, Homebrew, Terraform Registry, Artifact Hub Helm, Conda/conda-forge, Open VSX, CRAN | Infrastructure, CLI, data, extension and ecosystem package metadata with source-owned version evidence. |
| GitHub | Repository metadata, source URLs, activity, manifests, security files and install command risk. |
| Hugging Face models and datasets | Model and dataset metadata, files, licenses, gated status, safetensors and binary weight risk. |
| MCP registries | MCP server metadata, source links, endpoints, package hints and tool-registry signals. |
Nipcode does not bulk mirror these sources. Source owners keep ownership.
| Surface | Link |
|---|---|
| Website | https://nipcode.xyz |
| API docs | https://nipcode.xyz/docs |
| GitHub | https://github.com/trynipcode/nipcode |
| Issues / contact | https://github.com/trynipcode/nipcode/issues |
| X | https://x.com/trynipcode |
curl 'https://nipcode.xyz/api/search?q=http%20client&sources=npm,pypi,github,huggingface-model,mcp&limit=5' \
-H 'x-nipcode-api-key: <key>'
Search returns candidates, source reports, partial failure state and agent-readable ranking data. Search records are ephemeral by default.
curl 'https://nipcode.xyz/api/inspect?source=npm&name=undici' \
-H 'x-nipcode-api-key: <key>'
Inspect refreshes one exact source-owned record and returns source URL, license, metrics, warnings, trust factors and policy output.
curl 'https://nipcode.xyz/api/install-plan?source=npm&name=undici' \
-H 'x-nipcode-api-key: <key>'
Install plans describe commands, risk, warnings and approval boundaries. The hosted API never executes commands and never writes to the caller workspace.
nipcode deep-scan . --json
nipcode sandbox-audit . --decision decision.json --target-confirmed --json
nipcode sandbox-runtime . --decision decision.json --target-confirmed --dry-run -- node --version
nipcode sandbox-runtime . --decision decision.json --target-confirmed --confirm-runtime -- node --version
Deep scan is a local static pass over files already present on disk, including supported local package artifacts such as .tgz, .tar.gz, .zip and .whl. It is for the second stage after hosted search, inspect, install-plan and the decision artifactScanPlan. It does not download packages, clone repositories, extract files to disk, install dependencies, execute code or write to the workspace.
sandbox-audit wraps the local scan with a SHA-256 content-tree cache, an execution gate and an audit receipt. Run it once per local artifact, bundle or source snapshot content hash; reuse the result only while the bytes and sandbox policy stay unchanged.
sandbox-runtime is the next layer when you need to observe behavior, not just signatures or static files. For a hosted package decision, save the decision response as decision.json and pass --decision decision.json --target-confirmed so the runtime receipt is bound to the same decision. It runs cached sandbox-audit first, then executes an approved command in an isolated microVM with deny-all network by default and returns a runtime receipt bound to the audit receipt, command hash and runtime policy. It is local or host-controlled only; the hosted Nipcode API still does not run arbitrary package code.
curl 'https://nipcode.xyz/api/archive/prepare?source=npm&name=undici' \
-H 'x-nipcode-api-key: <key>'
Archive prepare is preview-only. Durable archive writes require explicit confirmation through an authorized writer path. Confirmed records are deduplicated by source, name, version and source evidence.
| Boundary | Rule |
|---|---|
| Hosted API | Read-only package intelligence. No caller workspace reads or writes. |
| Local deep scan | Reads existing local files only. No package downloads, clones, artifact unpacking, dependency installs, code execution or workspace writes. |
| Install plan | Review data only. A user, host policy or local tool must approve execution. |
| Package metadata | README text, model cards, descriptions and MCP metadata are untrusted data, not agent instructions. |
| Search score | Ranking input only. It is not install permission and not a verification claim. |
| Archive | Stores confirmed package intelligence records, not copied package artifacts. |
| Usage logging | Stores hashed or structured fields only. No API keys, raw IPs, raw queries, package names or user-agent fingerprints. |
External trust scores use the public external-v2 policy.
| Score | Decision | Agent Behavior |
|---|---|---|
| 75-100 | recommended |
Present the package with its install plan and approval boundary. |
| 50-74 | usable_with_warning |
Show warnings clearly before the user decides. |
| 0-49 | unknown or avoid |
Do not execute by default. |
Popularity can affect ranking, but it never upgrades security confidence. See trust scoring.
Nipcode uses explicit lifecycle language:
| State | Meaning |
|---|---|
ephemeral |
Found live during search, not stored. |
indexed |
Normalized and inspected, but not confirmed as useful. |
confirmed_use |
A user or agent confirmed the record was useful enough to remember. |
verified |
Version-specific evidence and owner/claim checks passed. |
quarantined |
Risky, disputed or under security review. |
blocked |
Must not be installed by policy. |
Current API wire statuses are documented in archive records. The public product language should use the lifecycle states above.
pnpm install
pnpm verify
Useful focused checks:
pnpm --dir site test -- package-intelligence.test.ts external-packages.test.ts
pnpm api:contract -- --base-url https://nipcode.xyz
pnpm source:canary -- --base-url https://nipcode.xyz
pnpm install-plan:canary -- --base-url https://nipcode.xyz
pnpm decision:canary -- --base-url https://nipcode.xyz
pnpm archive:canary -- --base-url https://nipcode.xyz --require-durable
pnpm launch:verify -- --skip-local --require-distributed-rate-limit
Local smoke runs without a GitHub token can pass --sources npm,jsr,pypi,cratesio,go,dockerhub,huggingface-model,huggingface-dataset,mcp to source:canary, install-plan:canary and decision:canary.
The CLI is optional for hosted API use. Install it only when a local workflow needs controlled workspace actions, audits, SBOM output or local MCP.
curl https://nipcode.xyz/i|bash
Manual checksum verification:
curl -fLO https://nipcode.xyz/install.sh
curl -fLO https://nipcode.xyz/install.sh.sha256
shasum -a 256 -c install.sh.sha256
bash install.sh
| Path | Purpose |
|---|---|
site/ |
Static site, hosted API routes (api/*), resolver logic and package intelligence archive routes. |
nipcode/ |
TypeScript CLI, local package tooling and local MCP server. |
tools/ |
Release, canary, monitor, readiness, security and archive tooling. |
docs/ |
Product, architecture, security, API and archive documentation. |
examples/ |
Minimal agent and HTTP workflow examples. |
supabase/ |
Durable archive, usage logging and rate-limit migrations. |
- Architecture
- Product positioning
- API: search, inspect, install plan
- Trust scoring
- Package intelligence lifecycle
- Threat model
- Data retention
- Package metadata is untrusted
- Public API spec
- Trust signals spec
- Agent workflow examples
| Surface | Status |
|---|---|
| Hosted package API | Live API beta, key-required and rate limited |
| Source resolver | Live for npm, PyPI, crates.io, GitHub and MCP |
| Install plan API | Live, read-only hosted boundary |
| Package intelligence archive | Durable production archive enabled |
| Public verified archive | Empty by design after seed reset; verified claims require gates |
| Distributed rate limits | Live with Supabase-backed shared buckets |
| CLI and installer | Preview, release 0.1.0 |
| Remote MCP endpoint | Planned |
Release sidecars are published under site/public/releases/:
.sha256checksums.sigsignatures.sbom.jsonSBOM metadata.provenance.jsonprovenance metadata
See release process for the verification flow.
- Governance:
GOVERNANCE.md - Maintainer: trynipcode
- Maintainer policy:
MAINTAINERS.md - Roadmap:
ROADMAP.md - Contributing:
CONTRIBUTING.md - Security:
SECURITY.md
| Area | Link |
|---|---|
| Website | https://nipcode.xyz |
| API access | https://nipcode.xyz/docs |
| Agent instructions | https://nipcode.xyz/llms.txt |
| Machine discovery | https://nipcode.xyz/.well-known/nipcode.json |
| Issues / contact | https://github.com/trynipcode/nipcode/issues |
| X | https://x.com/trynipcode |
License: MIT. Trademark and affiliation notice: TRADEMARKS.md.