Forge Agent

The open agent runtime

Self-hosted AI agent daemon with multi-platform bridges and MCP-compatible plugin system.

---

What is Forge Agent?

Forge Agent is a persistent, always-on background process (daemon) that sits on your machine and routes messages between messaging platforms and large language models. Think of it as your own self-hosted AI assistant that works across Telegram, Discord, Slack, and more.

[Telegram] ──WebSocket──────────┐
[Discord]  ──WebSocket──────────┤
[Slack]    ──WebSocket──────────► Gateway Daemon (ws://127.0.0.1:18789)
[WhatsApp] ──Long Poll──────────┤         ↓
[CLI]      ──stdin───────────────┘    Agent Runtime
                                          ↓
                                   LLM (Claude / GPT / DeepSeek)
                                          ↓
                                   Execute skill + respond

Features

• Always-on daemon — Runs as a background process via PM2 or systemd
• Multi-platform bridges — Telegram, Discord, Slack, WhatsApp, CLI
• MCP-compatible skills — Install plugins that follow the Model Context Protocol
• Multiple LLM support — Claude (primary), OpenAI, DeepSeek, local models
• Conversation memory — SQLite-backed persistent context across sessions
• Event-driven — WebSocket gateway at ws://127.0.0.1:18789
• Self-hosted — Your data stays on your machine

Quick Start

# Clone
git clone https://github.com/forge-dev-studio/forge-agent.git
cd forge-agent

# Install
npm install

# Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your API keys and platform tokens

# Run
npm start

# Or run as a managed daemon
npm run pm2:start

Configuration

# config.yaml
agent:
  name: "forge"
  gateway_port: 18789

llm:
  provider: "claude"           # claude | openai | deepseek
  model: "claude-sonnet-4-6"
  api_key: "${ANTHROPIC_API_KEY}"

bridges:
  telegram:
    enabled: false
    token: "${TELEGRAM_BOT_TOKEN}"
  discord:
    enabled: false
    token: "${DISCORD_BOT_TOKEN}"
  cli:
    enabled: true

memory:
  provider: "sqlite"
  path: "./data/memory.db"

skills:
  directory: "./skills"

Architecture

forge-agent/
├── src/
│   ├── index.js              # Entry point — starts gateway + bridges
│   ├── gateway/
│   │   └── server.js         # WebSocket gateway server
│   ├── bridges/
│   │   ├── cli.js            # Terminal/stdin bridge
│   │   ├── telegram.js       # Telegram bot bridge
│   │   └── discord.js        # Discord bot bridge
│   ├── llm/
│   │   ├── router.js         # Routes to configured LLM provider
│   │   ├── claude.js         # Anthropic Claude adapter
│   │   └── openai.js         # OpenAI adapter
│   ├── memory/
│   │   └── sqlite.js         # Conversation persistence
│   ├── skills/
│   │   └── loader.js         # MCP skill discovery + loading
│   └── config.js             # YAML config loader
├── skills/                   # User-installed skills directory
├── data/                     # SQLite DB + local state
├── config.yaml               # User configuration
├── ecosystem.config.js       # PM2 process manager config
└── Dockerfile                # Container deployment

Skills / Plugins

Forge Agent uses MCP-compatible skill definitions. Drop a skill into the skills/ directory:

{
  "name": "weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name" }
    },
    "required": ["location"]
  }
}

Part of the Forge Ecosystem

Forge Agent is the open-source foundation of the Forge platform:

Product	Description	Status
Forge Agent	Open-source agent runtime (you are here)	Free / OSS
Forge Vault	Multi-tenant managed agent platform	$99–999/mo
Forge Voice	AI voice receptionist	Per minute
Forge Desk	Managed virtual desktop	Per seat
Forge Studio	AI-powered dev environment	Coming soon

Learn more at forgedev.studio

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

---

Built by Forge Development Studio LLC