Getting Started

Getting Started

**Referenced Files in This Document** - [backend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/package.json) - [frontend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/package.json) - [backend/src/models/migrate.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/migrate.js) - [backend/src/config/index.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/config/index.js) - [agentid_build_plan.md](https://github.com/RunTimeAdmin/AgentID/blob/main/agentid_build_plan.md)

Table of Contents

1. Introduction
2. Prerequisites
3. Installation
4. Configuration
5. Running the Application
6. Verification
7. Next Steps

Introduction

This guide will help you get AgentID up and running on your local machine for development and testing purposes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18.x or higher (Download)
• PostgreSQL 14.x or higher (Download)
• Redis 7.x or higher (Download)
• Git (Download)

Installation

1. Clone the Repository

git clone https://github.com/RunTimeAdmin/AgentID.git
cd AgentID

2. Install Backend Dependencies

cd backend
npm install

3. Install Frontend Dependencies

cd ../frontend
npm install

Configuration

1. Database Setup

Create a PostgreSQL database:

createdb agentid

Or using psql:

psql -U postgres -c "CREATE DATABASE agentid;"

2. Environment Variables

Backend Configuration

Copy the example environment file:

cd backend
cp .env.example .env

Edit .env with your configuration:

PORT=3002
NODE_ENV=development
DATABASE_URL=postgresql://user:password@localhost:5432/agentid
REDIS_URL=redis://localhost:6379
BAGS_API_KEY=your_bags_api_key_here
SAID_GATEWAY_URL=https://said-gateway.example.com
AGENTID_BASE_URL=http://localhost:3002
CORS_ORIGIN=http://localhost:5173
BADGE_CACHE_TTL=60
CHALLENGE_EXPIRY_SECONDS=300

Frontend Configuration

cd frontend
cp .env.example .env

Edit .env:

VITE_API_BASE_URL=http://localhost:3002/api

3. Database Migrations

Run the database migrations to create the required tables:

cd backend
npm run migrate

This will create:

• agent_identities table
• agent_verifications table
• agent_flags table
• Required indexes

Running the Application

Start the Backend

cd backend
npm run dev

The backend API will be available at http://localhost:3002

Start the Frontend

In a new terminal:

cd frontend
npm run dev

The frontend will be available at http://localhost:5173

Start Redis

Ensure Redis is running:

redis-server

Verification

Check Backend Health

curl http://localhost:3002/health

Expected response:

{"status":"ok"}

Test API Endpoints

Register a test agent:

curl -X POST http://localhost:3002/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "pubkey": "test_pubkey_88_chars_long_here",
    "name": "Test Agent",
    "signature": "test_signature",
    "message": "test_message",
    "nonce": "test_nonce"
  }'

Access the Frontend

Open your browser and navigate to http://localhost:5173

You should see the AgentID registry interface.

Next Steps

Now that you have AgentID running:

1. Read the Developer Guide - Learn about the architecture and how to extend the system
2. Review the API Reference - Understand the available endpoints
3. Check the Security Implementation - Learn about authentication and security
4. Explore the Widget Guide - Learn how to embed trust badges

Common Issues

Database Connection Errors

• Verify PostgreSQL is running
• Check DATABASE_URL format
• Ensure database exists

Redis Connection Errors

• Verify Redis is running on the configured port
• Check REDIS_URL format

CORS Errors

• Ensure CORS_ORIGIN matches your frontend URL
• Check that the frontend VITE_API_BASE_URL is correct

Port Already in Use

• Change PORT in backend .env
• Change the dev server port in frontend vite.config.js