🚀 Getting Started

Get AgentRegistry up and running in under 5 minutes.

Prerequisites

  • Bun >= 1.0 (recommended runtime)
  • macOS, Linux, or WSL2
  • Node.js >= 18 (alternative runtime)
# Install Bun if you haven't already curl -fsSL https://bun.sh/install | bash

Installation

# Clone the repository git clone https://github.com/GiuseppeScottoLavina/AgentRegistry.git cd agentregistry # Install dependencies (minimal) bun install

Starting the Server

Quick Start

# Start the server bun run start # Or with hot-reload for development bun run dev # Custom port bun run src/server.ts --port 4874

The server will start on http://localhost:4873 by default.

Client Configuration

Point your npm/bun client to the local registry:

NPM

npm config set registry http://localhost:4873

Bun

# Add to bunfig.toml echo 'registry = "http://localhost:4873"' >> bunfig.toml

Per-Project (.npmrc)

echo "registry=http://localhost:4873" > .npmrc

💡 Tip

Using per-project .npmrc is recommended for team projects to ensure everyone uses the same registry.

⚠️ Bun Users - Important Workaround

Bun performs client-side auth validation before contacting the server. Add a dummy token:

echo "//localhost:4873/:_authToken=agentregistry-no-auth-needed" >> ~/.npmrc

AgentRegistry ignores this token - it's only to bypass Bun's local check. Alternatively, use npm publish instead.

Daemon Mode

Run AgentRegistry as a background service with automatic restart on crash.

CLI Commands

# 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

macOS Auto-Start (launchd)

# Install as system service (auto-start on boot) npm run install-service # Remove service npm run uninstall-service

Daemon Files

File Location
PID file ~/.agentregistry/agentregistry.pid
Logs ~/.agentregistry/logs/agentregistry.log
launchd plist ~/Library/LaunchAgents/com.agentregistry.daemon.plist

Developer Tools

Scaffold New Packages

Create a ready-to-publish TypeScript package:

agentregistry create my-pkg

Release Helper

Bump version and publish in one command:

agentregistry release patch # or: minor, major

Resilient Publish

If you encounter EPERM errors due to corrupted local cache, use the resilient publish command:

agentregistry publish

Diagnostics

Check for environment issues (permissions, connectivity):

agentregistry doctor

System Backup

Create a full snapshot (database + storage):

agentregistry backup agentregistry restore <file.zip>

Testing

# Run all 656 tests (100% pass rate) bun test

Tests include:

  • Security scanner validation
  • Admin panel endpoints
  • Column sorting functionality
  • IP allowlist rules
  • End-to-end registry operations