agentregistry
Advanced tools
📖 Documentation · 🚀 Getting Started · 📡 API Reference
A local NPM registry built for the age of AI coding agents.
Lightweight. Security-first. Blazing fast.
🤖 MCP Ready · 🛡️ Quarantine-First Security · ⚡ 1ms Response Time · 🕸️ Dependency Graph
AI coding agents are transforming software development. Tools like Cursor, Windsurf, and Claude Code can write, test, and publish entire packages autonomously. But there's a critical gap: when AI agents install dependencies, they blindly trust everything from npmjs.org — including packages that contain prompt injection attacks, malicious install scripts, or supply chain exploits designed specifically to compromise AI workflows.
AgentRegistry was born from a simple question: what if your local registry could protect your AI agents the same way a firewall protects your network?
AgentRegistry is a private, local NPM registry that sits between your AI agents and the public npm ecosystem. Every package — whether published locally or fetched from upstream — is security-scanned in real time. Suspicious packages are quarantined and require human approval before any agent can use them. This creates a human-in-the-loop security boundary that prevents supply chain attacks without slowing down your workflow.
llms.txt, OpenAPI spec, structured error responses with AI directives| Pain Point | Traditional Registries | AgentRegistry |
|---|---|---|
| Dependencies | 60+ packages to install | 2 dependencies (tar, acorn) |
| Setup Time | Minutes of configuration | One command: bun run start |
| AI Integration | None | Native MCP, llms.txt, OpenAPI |
| Security | Afterthought (plugins) | Quarantine-first architecture |
| Response Time | 50-200ms | ~1ms (memory-first cache) |
| Admin UI | Static page refreshes | Real-time WebSocket dashboard |
⚠️ Alpha Software (0.1.0) — AgentRegistry is under active development. APIs may change. Contributions and feedback welcome!
# Start the server
bun run start
# Or with hot-reload for development
bun run dev
# Custom port
bun run server.ts --port 4874
AgentRegistry can run as a background daemon with automatic restart on crash.
# Start daemon in background
bun run cli.ts start
# Check status
bun run cli.ts status
# View logs
bun run cli.ts logs
# Stop daemon
bun run cli.ts stop
# Restart
bun run cli.ts restart
# Install as system service (auto-start on boot)
npm run install-service
# Remove service
npm run uninstall-service
| File | Location |
|---|---|
| PID file | ~/.agentregistry/agentregistry.pid |
| Logs | ~/.agentregistry/logs/agentregistry.log |
| launchd plist | ~/Library/LaunchAgents/com.agentregistry.daemon.plist |
Point your npm/bun client to the local registry:
# NPM
npm config set registry http://localhost:4873
# Bun
echo 'registry = "http://localhost:4873"' >> bunfig.toml
# Per-project (.npmrc)
echo "registry=http://localhost:4873" > .npmrc
# Standard npm publish
npm publish
# Or with bun
bun publish
npm install my-package
bun add my-package
npm unpublish my-package@1.0.0
Create a ready-to-publish TypeScript package:
agentregistry create my-pkg
Bump version and publish in one command:
agentregistry release patch
# or minor, major
Check for environment issues (permissions, connectivity):
agentregistry doctor
Visualize your local ecosystem at http://localhost:4873/-/admin (Graph tab).
Create a full snapshot (database + storage):
agentregistry backup
agentregistry restore <file.zip>
| Method | Endpoint | Description |
|---|---|---|
GET | / | List all packages |
GET | /-/ping | Health check |
GET | /{package} | Get package metadata |
GET | /{package}/{version} | Get specific version |
GET | /{package}/-/{tarball}.tgz | Download tarball |
PUT | /{package} | Publish package |
DELETE | /{package}/-/{tarball}/{rev} | Unpublish version |
⚠️ Authentication Required: All admin API endpoints require
X-Admin-Tokenheader. Token is auto-injected in the admin panel UI.
| Method | Endpoint | Description |
|---|---|---|
GET | /-/admin | Admin panel UI (no auth required) |
GET | /-/admin/stats | Server stats (memory, cache, etc.) |
GET | /-/admin/quarantine | List quarantined packages |
DELETE | /-/admin/quarantine | Clear all quarantine |
DELETE | /-/admin/quarantine/{file} | Delete specific file |
POST | /-/admin/quarantine/{file}/approve | Approve and cache |
GET | /-/admin/cache | List cached packages |
DELETE | /-/admin/cache/{name} | Delete package |
POST | /-/admin/cache/{name}/refresh | Force refresh from NPM |
Recommended: Use WebSocket (/-/admin/ws) for all admin operations. The admin panel uses WebSocket automatically.
Access the admin panel at http://localhost:4873/-/admin
Features:
Packages are stored locally in:
storage/packages/ - JSON metadatastorage/tarballs/ - Validated package tarballs (.tgz)storage/quarantine/ - Pending security scan (temporary)storage/backups/ - Timestamped backup copies of all published packages# First, start the server (required for tests)
bun start
# In another terminal, run tests
bun test
⚠️ Some tests (Admin Panel, Agent-First API, Documentation Site) require a running server to pass.
| Category | Tests | Status |
|---|---|---|
| Prompt Injection Scanner | 154 | ✅ |
| Server API | 72 | ✅ |
| Database Module | 54 | ✅ |
| IP Allowlist | 52 | ✅ |
| Admin Panel | 48 | ✅ |
| Security Module | 52 | ✅ |
| CVE Module | 39 | ✅ |
| Helpers & HTTP | 29 | ✅ |
| Validation | 28 | ✅ |
| Documentation Site | 26 | ✅ |
| Agent-First API | 25 | ✅ |
| Metrics Module | 25 | ✅ |
| Services (Cache & Broadcast) | 24 | ✅ |
| Package Allowlist | 21 | ✅ |
| Upstream Module | 18 | ✅ |
| Health Check | 16 | ✅ |
| Daemon | 13 | ✅ |
| Broadcast | 10 | ✅ |
| WebSocket Tests | 10 | ✅ |
| Compression | 9 | ✅ |
| Logger | 9 | ✅ |
| Allowlist | 8 | ✅ |
| CLI | 6 | ✅ |
| Unit Tests | 3 | ✅ |
| AST Scanner | 179 | ✅ |
| Total | 650+ | ✅ |
AgentRegistry automatically maintains itself:
| Feature | Interval | Details |
|---|---|---|
| Log Cleanup | Every 6 hours | Removes request logs >7 days, audit logs >30 days |
| Quarantine Auto-Approve | On startup | Re-scans quarantine, approves packages that now pass |
| Security Alerts | Kept forever | Blocked packages and security events are never deleted |
When a package is blocked by security scan, AgentRegistry returns detailed JSON with:
action_required: "HUMAN INTERVENTION REQUIRED"instructions array for resolution⚠️ LOCALHOST ONLY - This server is hardened for local use only.
| Layer | Protection |
|---|---|
| Network | Binds to 127.0.0.1 only (not 0.0.0.0) |
| Host Check | Rejects requests from non-localhost hosts (403) |
| Input Validation | Strict regex for package names and versions |
| Path Traversal | Blocks ../, null bytes, enforces basename() checks |
| XSS Protection | Output encoding via escapeHtml() on all render paths |
| Length Limits | Package names max 214 chars |
| Security Scanner | Static analysis before caching (~10-50ms) |
| Quarantine | All upstream packages scanned before cache |
All packages fetched from npmjs.org go through security scanning:
npm install lodash
↓
📥 Download from npmjs.org
↓
🔒 Write to storage/quarantine/
↓
🔍 Security scan (~10-50ms)
↓
✅ SAFE → Move to storage/tarballs/ + memory cache
🚨 BLOCKED → Stays in quarantine, returns 403
| Severity | Patterns Detected |
|---|---|
| Critical | eval(), new Function(), `curl |
| High | child_process, exec(), SSH/npmrc access, base64 payloads |
| Medium | File system writes, .env access, prototype pollution |
| Low | process.env access |
The prompt injection scanner uses a research-backed 10-pass analysis pipeline to detect LLM manipulation attempts hidden in package metadata, READMEs, and code comments:
| Pass | Technique | Catches |
|---|---|---|
| 1 | Raw content scan | Literal injection patterns in 5 languages |
| 2 | Unicode normalization + homoglyphs | Cyrillic/Greek/fullwidth character substitution |
| 3 | Leetspeak decode | 1gn0r3 4ll pr3v10us 1nstruct10ns |
| 4 | ROT13 decode | ROT13-encoded payloads |
| 5 | FlipAttack reversal | Character-reversed injection strings |
| 6 | Reconstruction patterns | String.fromCharCode(), reverse().join() |
| 7 | Policy Puppetry | Config format mimicry (INI/JSON/XML/YAML) |
| 8 | MCP injection | Tool description injection, line jumping |
| 9 | Adversarial suffix | GCG-style high-entropy gibberish detection |
| 10 | Invisible characters | Zero-width, tag characters, BiDi overrides |
Cross-field payload splitting: Metadata fields are concatenated and rescanned to catch payloads split across name, description, and keywords.
| Attack Vector | Paper/Source | Detection Method |
|---|---|---|
| Homoglyph substitution | ACL 2025 (42-59% ASR) | NFKD + 75 character mappings |
| Leetspeak obfuscation | HiddenLayer, April 2025 | Digit→letter substitution |
| Policy Puppetry | HiddenLayer, April 2025 | Config format pattern matching |
| FlipAttack | ACL 2025 (98% GPT-4o bypass) | Reverse content scanning |
| GCG adversarial suffixes | Zou et al., 2023 | Shannon entropy + punctuation analysis |
| Payload splitting | OWASP LLM01:2025 | Cross-field concatenation |
| MCP line jumping | MCP security research, 2025 | Tool description pattern matching |
| Invisible Unicode | Unicode Consortium TR36 | Zero-width/tag character detection |
154 prompt injection tests (30 SOTA adversarial) · 100% line coverage · 97% function coverage
⚠️ The AST deep scanner is one approach to complementing regex-based scanning with lightweight AST analysis. Well-tested (179 tests, 99% coverage) and effective within its scope — but not a replacement for dedicated tools like Semgrep or CodeQL. See known limitations →
Opt-in only — never runs automatically. Trigger via CLI (agentregistry scan --deep) or Admin Panel UI ("🔬 Scan" button).
| Pattern | Severity | Detects |
|---|---|---|
eval_family | Critical | eval(), new Function() |
encoded_payload_exec | Critical | eval(atob(...)), encoded execution |
process_spawn | Critical | child_process.exec(), shell commands |
network_exfiltration | Critical | HTTP requests with sensitive data |
dynamic_require | Critical | require(variable) |
computed_member_exec | High | global["ev"+"al"]() |
prototype_pollution | High | __proto__ writes |
timer_obfuscation | Medium | setTimeout("code", 0) |
iife_with_suspicious_args | Medium | Suspicious IIFE arguments |
Includes lightweight constant propagation (tracks const x = "literal" values).
Known limitations: No data-flow, interprocedural, or control-flow analysis. Cannot track values across function boundaries or detect multi-file payloads.
179 tests · 100% function coverage · 99.41% line coverage — Full docs →
/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/istorage/This registry is designed for:
AgentRegistry is optimized for AI agent workflows with full support for modern agent protocols.
| Endpoint | Description |
|---|---|
GET /llms.txt | AI discovery file (like robots.txt for LLMs) |
GET /openapi.json | Full OpenAPI 3.0 specification |
GET /-/capabilities | Tool definitions for AI agents |
AgentRegistry includes a full MCP server for integration with Claude, GPT, and other AI assistants:
# Install and run MCP server
cd mcp-server
bun install
bun run start
Claude Desktop Configuration (claude_desktop_config.json):
{
"mcpServers": {
"agentregistry": {
"command": "bun",
"args": ["run", "/path/to/AgentRegistry/mcp-server/index.ts"]
}
}
}
| Tool | Description |
|---|---|
publish_package | Publish with automatic security scanning |
get_package | Get package metadata |
search_packages | Search local + upstream packages |
get_server_stats | Server health and statistics |
check_quarantine | Check for blocked packages |
tar)| Operation | Time |
|---|---|
| Memory cache hit | ~1ms |
| Disk cache hit | ~3ms |
| Upstream fetch + scan | ~500ms (network) + ~10-50ms (scan) |
Memory cache stores up to 100 tarballs for instant serving.
FAQs
Minimal local NPM registry server for agent-to-agent package sharing
We found that agentregistry demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.