Skip to main content

​
Quick Start Guide

This guide will help you install, configure, and run Iris on your local machine. Most features work out of the box without API keys.

​
Prerequisites

Before you begin, ensure you have the following installed:
You can verify your Node.js version by running node --version in your terminal.

​
Installation

1

Clone the Repository

Clone the Iris repository from GitHub:
git clone https://github.com/chinmay505/iris.git
cd iris
This downloads the complete source code to your local machine.
2

Install Dependencies

Install all required npm packages:
npm install
This will install all dependencies defined in package.json:
// source: package.json:11-59
{
  "dependencies": {
    "@hookform/resolvers": "^5.2.2",
    "@radix-ui/react-accordion": "^1.2.12",
    "@radix-ui/react-dialog": "^1.1.15",
    "framer-motion": "^12.23.26",
    "next": "16.1.0",
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "tailwind-merge": "^3.4.0",
    "zod": "^4.2.1"
  }
}
3

Configure Environment Variables

Create a .env file from the example template:
cp .env.example .env
The default configuration enables basic logging and sets sensible defaults:
# source: .env.example:1-11
NEXT_PUBLIC_LOG_LEVEL=0 # 0 = disabled 1 = basic 2 = debug
NODE_ENV=development # development/production

IMGBB_API_KEY= # imgbb used for temporary storing reverse image requests
MAX_IMAGE_SIZE=32000 # in kb default = 32mb which is the max accepted by imgbb unless you have premium.
IMAGE_EXPIRY=600 # in seconds, default 600 = 10 minutes

IPQS_API_KEY= # ipqs used for email analysis

COMPANIESHOUSE_API_KEY= # companies house api for uk company data
You can start using Iris immediately without API keys! Features like domain analysis, username search, SEC EDGAR, and GLEIF lookups work with public APIs.
4

Start the Development Server

Launch Iris in development mode:
npm run dev
You should see output similar to:
▲ Next.js 16.1.0
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.1s
Open your browser to http://localhost:3000
5

Verify Installation

Test that Iris is working correctly:
  1. Domain Analysis (no API key required):
    • Navigate to the Domain tab
    • Enter a domain like example.com
    • Click “Analyze”
    • You should see DNS records, WHOIS data, and SSL information
  2. Username Search (no API key required):
    • Navigate to the Username tab
    • Enter a common username
    • Select sources (WhatsMyName, Sherlock, Maigret)
    • Watch results stream in real-time
If everything works, you’re ready to start using Iris! For enhanced features, continue to the API key setup below.

​
Optional: API Key Setup

While many features work without API keys, you’ll need them for advanced capabilities:

​
ImgBB (Image Uploads)

Required for reverse image search functionality.
1

Create ImgBB Account

  1. Visit https://api.imgbb.com/
  2. Click “Get API Key”
  3. Sign up for a free account
2

Get API Key

  1. Log in to your ImgBB dashboard
  2. Copy your API key
  3. Add to .env:
IMGBB_API_KEY=your_imgbb_api_key_here

​
IPQualityScore (Email Verification)

Required for email reputation and breach checking.
1

Create IPQS Account

  1. Visit https://www.ipqualityscore.com/
  2. Create a free account
  3. Free tier includes 5,000 lookups/month
2

Get API Key

  1. Navigate to your dashboard
  2. Find your API key under “API Settings”
  3. Add to .env:
IPQS_API_KEY=your_ipqs_api_key_here

​
Companies House (UK Company Data)

Required for UK company lookups.
1

Create Developer Account

  1. Visit https://developer.company-information.service.gov.uk/
  2. Create an account
  3. Register a REST application
2

Get API Key

  1. Log in to your developer account
  2. Navigate to “Your applications”
  3. Copy your API key
  4. Add to .env:
COMPANIESHOUSE_API_KEY=your_companies_house_api_key_here

​
Production Build

For production deployment, build an optimized version: 
npm run build
The build process:
  1. Compiles TypeScript to JavaScript
  2. Optimizes React components
  3. Minifies CSS and assets
  4. Generates static pages where possible
Always set NODE_ENV=production in your .env file for production deployments.

​
Common Issues

​
Port 3000 Already in Use

If port 3000 is occupied, specify a different port: 
PORT=3001 npm run dev

​
API Key Not Working

Ensure your .env file:
  • Is in the project root directory
  • Has no spaces around = signs
  • Contains valid API keys (no quotes needed)
  • Is not tracked by git (included in .gitignore)

​
Module Not Found Errors

Delete node_modules and reinstall: 
rm -rf node_modules package-lock.json
npm install

​
Build Errors

Clear Next.js cache and rebuild: 
rm -rf .next
npm run build

​
Understanding the API Structure

Iris uses Next.js App Router with API routes in app/api/. Here’s how a typical endpoint works: 
// source: app/api/email/verify/route.ts:7-28
export async function POST(request: NextRequest) {
    try {
        const body = await request.json();
        const { email } = body;

        if (!email || typeof email !== 'string') {
            return new Response(
                JSON.stringify({ success: false, error: 'Invalid email address' }),
                { status: 400, headers: { 'Content-Type': 'application/json' } }
            );
        }

        // Basic email format validation
        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
        if (!emailRegex.test(email)) {
            return new Response(
                JSON.stringify({ success: false, error: 'Invalid email format' }),
                { status: 400, headers: { 'Content-Type': 'application/json' } }
            );
        }

        const result = await verifyEmail(email.trim().toLowerCase());
        // ...
    }
}
Each API endpoint:
  1. Validates input parameters
  2. Sanitizes and normalizes data
  3. Calls service layer functions
  4. Returns JSON or server-sent events (SSE) streams

​
Development Workflow

1

Make Changes

Edit files in app/, components/, or lib/
2

Hot Reload

Next.js automatically reloads on file changes
3

Check Console

Monitor browser console and terminal for errors
4

Test Features

Manually test affected functionality

​
Next Steps

Configuration Guide

Detailed environment variable documentation

API Reference

Complete API endpoint documentation

Username Search

Search for usernames across platforms

Self-Hosting Guide

Deploy Iris to production environments

Build docs developers (and LLMs) love

Get started for freeTalk to us