Agent-X

Self-hosted intelligent agent publishing platform. Create, configure, and publish AI agents with multi-provider support, MCP tools, custom skills, workspace IDE, and an OpenAI-compatible API.

Features

• Multi-Provider Support - Connect OpenAI, Anthropic, Gemini, DeepSeek, Qwen, Zhipu, Moonshot with unified management
• Agent Lifecycle - Create, configure, version, and archive agents with share token support
• MCP Integration - Browse marketplace and add custom MCP servers (STDIO/SSE/Streamable HTTP)
• Skills Marketplace - Admin-curated system skills + user custom skills for agents
• Streaming Chat UI - Real-time conversation interface with multi-part message rendering
• Workspace IDE - In-browser file editor with Monaco, file tree, and AI-driven file operations (create, read, update, delete, search, patch)
• OpenAI-Compatible API - Expose agents via /v1/chat/completions endpoint with API key auth
• User Preferences - Theme and language preferences persisted in database, synced across devices on login
• User Management - Admin panel for user CRUD, role/status management, and password reset
• Secure by Default - JWT auth, AES-256-GCM encrypted provider keys, API key management

Tech Stack

Layer	Technology
Backend	NestJS 11, TypeScript, Prisma v7, PostgreSQL 16
Frontend	React 19, Vite 6, Tailwind CSS v4, shadcn/ui, React Router v7
AI	Vercel AI SDK, 7 provider protocols
Editor	Monaco Editor (50+ language syntax highlighting)
State	Zustand v5, TanStack React Query v5, sonner (toast)
Infra	Docker, nginx, Turborepo, pnpm

Quick Start (Docker)

git clone <your-repo-url>
cd agent-x
cp .env.example .env
# Edit .env — set DB_PASSWORD, JWT_SECRET, ENCRYPTION_SECRET
docker compose up -d

Open http://localhost to access the web UI.

Development Setup

Prerequisites

• Node.js 22
• pnpm 9.15.0
• PostgreSQL 16

Install & Run

# Install dependencies
pnpm install

# Configure environment
cp packages/server/.env.example packages/server/.env
# Edit packages/server/.env with your database credentials

# Run database migrations
cd packages/server && npx prisma migrate dev && cd ../..

# Start dev servers (frontend :5173 + backend :3000)
pnpm dev

Useful Commands

pnpm dev            # Start all dev servers
pnpm build          # Build all packages
pnpm test           # Run all tests
pnpm typecheck      # Type check all packages
pnpm lint           # Lint all packages
pnpm format         # Format code with Prettier

# Database
pnpm db:migrate     # Run migrations
pnpm db:generate    # Regenerate Prisma client
pnpm db:studio      # Open Prisma Studio

Project Structure

agent-x/
├── packages/
│   ├── server/          # NestJS backend
│   │   ├── prisma/      # Database schema & migrations
│   │   └── src/modules/ # auth, provider, agent, skill, mcp, chat, workspace, public-chat, preferences, api-key, openai-compat, user, system-config
│   ├── web/             # React frontend
│   │   └── src/
│   │       ├── pages/       # login, register, dashboard/*, chat, shared
│   │       ├── components/  # chat, workspace, agents, shared, auth, ui (shadcn)
│   │       ├── contexts/    # React contexts (workspace API switching)
│   │       ├── hooks/       # React Query hooks
│   │       ├── lib/         # Utilities, transports, schemas
│   │       └── stores/      # Zustand stores
│   └── shared/          # Shared TypeScript types & DTOs
├── docker/              # Dockerfiles & nginx config
├── docker-compose.yml   # Production deployment
└── turbo.json           # Turborepo pipeline

API Overview

All backend routes are prefixed with /api except the OpenAI-compatible endpoint.

Module	Endpoints
Auth	POST /api/auth/register, POST /api/auth/login, POST /api/auth/refresh, GET /api/auth/me
Providers	GET/POST /api/providers, GET/PUT/DELETE /api/providers/:id, POST :id/test, GET :id/models, POST :id/sync-models
Agents	GET/POST /api/agents, GET/PUT/DELETE /api/agents/:id, POST :id/archive, POST :id/unarchive
Agent Versions	POST /api/agents/:id/versions, GET :id/versions, GET :id/versions/:vid
Share Tokens	POST /api/agents/:id/versions/:vid/share-tokens, GET ..., DELETE ...
Agent Bindings	POST/DELETE /api/agents/:id/skills/:skillId, POST/DELETE :id/mcp-servers/:mcpServerId
Skills	GET /api/skills/market, POST/PUT/DELETE /api/skills/market(/:id) (admin), GET/POST /api/skills, GET/PUT/DELETE /api/skills/:id
MCP Servers	GET /api/mcp-servers/market, POST/PUT/DELETE /api/mcp-servers/market(/:id) (admin), GET/POST /api/mcp-servers, GET/PUT/DELETE /api/mcp-servers/:id, POST :id/test
Chat	POST/GET /api/conversations, GET :id/messages, POST :id/chat, GET :id/messages/:mid/stream, GET :id/active-stream, POST :id/messages/:mid/stop, DELETE :id
Workspace	GET/POST /api/conversations/:id/files, POST :id/files/directories, GET/PUT/DELETE :id/files/:fid/*, PATCH :id/files/:fid/rename, directory rename/delete
Public Chat	GET /api/shared/:token/info, POST :token/conversations, GET :token/conversations/:id/messages, POST :token/conversations/:id/chat, stream + workspace endpoints
Preferences	GET /api/preferences, PATCH /api/preferences
API Keys	GET/POST /api/api-keys, DELETE /api/api-keys/:id
Users	GET/POST /api/users (admin), GET /api/users/:id, PATCH :id/role, PATCH :id/status, POST :id/reset-password
System Config	GET/POST /api/system/providers, GET/PUT/DELETE :id, POST :id/test, GET :id/models, GET/PUT /api/system/features/:key, POST /api/system/polish
OpenAI Compat	POST /v1/chat/completions

OpenAI-Compatible API

Expose any published agent as an OpenAI-compatible endpoint:

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer sk-agx-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Environment Variables

Local Development (packages/server/.env)

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	—
JWT_SECRET	JWT signing secret	—
JWT_EXPIRES_IN	Access token expiry	7d
JWT_REFRESH_EXPIRES_IN	Refresh token expiry	30d
ENCRYPTION_SECRET	AES-256-GCM key (32 chars)	—
PORT	Server port	3000
CORS_ORIGIN	Allowed CORS origin	http://localhost:5173
AI_SDK_TELEMETRY	Enable OpenTelemetry tracing	false
WORKSPACE_BASE_DIR	Workspace file storage path	data/workspaces
WORKSPACE_MAX_FILE_SIZE	Max file size in bytes	5242880 (5MB)

Docker Production (.env)

Variable	Description	Default
DB_NAME	Database name	agent_x
DB_USER	Database user	agent_x
DB_PASSWORD	Database password	—
JWT_SECRET	JWT signing secret	—
ENCRYPTION_SECRET	AES-256-GCM key (32 chars)	—
PORT	Exposed web port	80

License

MIT