AgentForge

AgentForge is a Next.js dashboard for managing and visualizing multi-agent workflows, executions, costs, guardrails, and evaluations.

Deployment sample (GitHub Pages)

• Dashboard sample URL (this repository): https://twomathematicians-code.github.io/AgentForge/
• For forks, use: https://<your-github-username>.github.io/<your-repo-name>/
• Open the link to validate deployment availability and basic page rendering.
• If the page is unavailable, confirm GitHub Pages is enabled for this repository and re-deploy.

Folder and file structure

AgentForge/
├── README.md
├── package.json
├── next.config.ts
├── tsconfig.json
├── tailwind.config.ts
├── eslint.config.mjs
├── postcss.config.mjs
├── Caddyfile
├── .zscripts/                    # local helper scripts (dev/start/build)
├── src/
│   ├── app/                      # Next.js app router pages and API routes
│   │   ├── api/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/               # UI and feature components
│   │   ├── agents/
│   │   ├── costs/
│   │   ├── dashboard/
│   │   ├── evaluations/
│   │   ├── guardrails/
│   │   ├── layout/
│   │   ├── settings/
│   │   ├── ui/
│   │   └── workflows/
│   ├── hooks/
│   └── lib/                      # shared types, store, db, utilities
├── prisma/
│   └── schema.prisma
├── db/
│   └── custom.db
├── public/                       # static assets
├── examples/
│   └── websocket/
│       ├── frontend.tsx
│       └── server.ts
├── mini-services/
├── skills/                       # reusable skill packs and assets
└── download/                     # generated reports and research assets

Prerequisites

• Node.js 20+
• npm
• Bun (only needed if you use npm run start for production)

Run locally

1. Install dependencies:

   npm install

2. Set up environment variables in .env:

   DATABASE_URL="file:./prisma/dev.db"

3. Create/update the SQLite schema:

   npm run db:push

4. Start the app:

   npm run dev

5. Open:

   http://localhost:3000
   

The app auto-seeds demo data on first load via POST /api/seed.

Try the sample locally (WebSocket example)

1. Run the app:

   npm run dev

2. In another terminal, run the sample WebSocket server:

   npx tsx examples/websocket/server.ts

3. Use the sample frontend component from:

   examples/websocket/frontend.tsx
   

Deploy with Docker

The recommended way to run AgentForge in production is with the included Dockerfile and docker-compose.yml.

Prerequisites

• Docker 24+ and Docker Compose v2
• A server or VM with at least 512 MB RAM

Quick start

# 1. Clone the repo
git clone https://github.com/twomathematicians-code/AgentForge.git
cd AgentForge

# 2. (Optional) Copy and customise environment variables
cp .env.example .env

# 3. Build and start the container
docker compose up -d --build

# 4. Open the app
open http://localhost:3000

On first start the entrypoint copies the pre-seeded baseline database into the named volume db_data, so the dashboard is immediately populated with demo data.

Environment variables

Variable	Default	Description
DATABASE_URL	file:/app/db/custom.db	SQLite path inside the container
PORT	3000	TCP port the server listens on
HOSTNAME	0.0.0.0	Bind address

See .env.example for a ready-to-copy template.

Persistent data

The SQLite database is stored in Docker named volume db_data and survives container restarts and image rebuilds.

# Inspect the volume
docker volume inspect agentforge_db_data

# Manual backup (keep last 7 copies in ./backups)
bash .zscripts/backup-db.sh

Apply schema changes

After pulling an update that changes prisma/schema.prisma, run:

docker compose exec app sh -c "bunx prisma db push --skip-generate"

HTTPS with Caddy

Uncomment the caddy service in docker-compose.yml, create a Caddyfile.production with your domain, and expose ports 80/443:

yourdomain.com {
    reverse_proxy app:3000
}

Then restart with docker compose up -d.

Restart policy

The restart: unless-stopped policy in docker-compose.yml ensures the app recovers automatically after server reboots or unexpected crashes.

---

Useful scripts

• npm run dev — start development server
• npm run lint — run ESLint
• npm run build — create production build
• npm run start — run production server (this npm script executes bun, so Bun must be installed)
• npm run db:push — push Prisma schema to DB
• npm run db:generate — generate Prisma client
• npm run db:migrate — run Prisma migrations in dev
• npm run db:reset — reset database
• bash .zscripts/backup-db.sh — backup SQLite database (with rotation)