> For the complete documentation index, see [llms.txt](https://docs.forgee.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forgee.xyz/forge.md). # Forge Forge is an autonomous AI coding agent. You describe what you want, and Forge writes the code, runs it, and commits it to GitHub. It is open source, so you can self-host it for free with your own model key, or use the hosted version and pay per use with $FORGE. There are two surfaces: 1. A Telegram bot, where every topic is its own isolated workspace. 2. A web app, where you connect a wallet and chat with Forge in the browser. *** ## Two ways to use Forge ### Self-host (free) Clone the open-source repo and run it with your own model provider key. You pay your provider directly and nothing else. This is the full agent, including GitHub commits and live previews. ### Hosted (pay per use) Use the hosted web app and Telegram bot without setting anything up. You connect a Solana wallet, deposit $FORGE, and pay only for what you use. No subscription. *** ## Self-hosting ### Requirements * Node.js 18 or newer * A Telegram bot token (from @BotFather) * A MongoDB database (MongoDB Atlas works) * A GitHub token with repo scope * A model provider key (DeepSeek by default, or any OpenAI-compatible provider) ### Setup 1. Clone the repository. 2. Copy the example env file and fill it in: ```bash cp .env.example .env ``` 3. Install dependencies and start: ```bash npm install npm start ``` ### Environment variables | Variable | Required | Where to get it | | --------------------- | ---------------- | --------------------------------------------- | | `TELEGRAM_BOT_TOKEN` | yes | @BotFather | | `ALLOWED_TELEGRAM_ID` | yes | @userinfobot (only this user can use the bot) | | `MONGODB_URI` | yes | MongoDB Atlas or any MongoDB instance | | `GITHUB_TOKEN` | yes | github.com/settings/tokens (repo scope) | | `GITHUB_USERNAME` | yes | your GitHub username | | `DEEPSEEK_API_KEY` | default provider | platform.deepseek.com | | `TAVILY_API_KEY` | optional | web search | | `GROQ_API_KEY` | optional | image and vision input | ### Switching AI providers Forge talks to any OpenAI-compatible chat-completions API. It defaults to DeepSeek. To use another provider, set these: ```bash AI_BASE_URL=https://api.openai.com/v1 AI_API_KEY=your_provider_key AI_MODEL_SNAP=gpt-4o-mini AI_MODEL_THINK=gpt-4o AI_MODEL_NUKE=o3 ``` Examples of base URLs: | Provider | Base URL | | ------------------ | ------------------------------ | | DeepSeek (default) | `https://api.deepseek.com/v1` | | OpenAI | `https://api.openai.com/v1` | | OpenRouter | `https://openrouter.ai/api/v1` | | Together | `https://api.together.xyz/v1` | | Ollama (local) | `http://localhost:11434/v1` | `AI_API_KEY` falls back to `DEEPSEEK_API_KEY` if it is not set, so existing setups keep working. ### Telegram setup 1. Create a Telegram group. 2. In group settings, enable Topics (Forum mode). 3. Add your bot to the group and make it an admin. Each topic becomes its own isolated workspace with its own linked repo, history, and reasoning mode. *** ## Using Forge ### How it works 1. Create a topic (Telegram) or open the web app. 2. Describe what you want in plain language, or paste an error to debug. 3. Link a GitHub repo and Forge reads your codebase first. 4. Forge writes the code, validates it, opens a live preview, and commits to your repo. ### Reasoning modes Forge has three modes you can switch between based on task complexity: | Mode | Use | | ----- | ------------------ | | Snap | fast, default | | Think | real reasoning | | Nuke | heaviest reasoning | ### Agent mode In the Telegram bot, `/agent ` runs autonomous multi-step execution. Forge plans the task into steps, writes each one, and commits after every step, running on its own. ### Skills You can teach Forge domain expertise or design systems. Skills are applied automatically when relevant, or invoked manually. ``` /skill add then send the instruction text or an uploaded file /skill add one-liner form /skill list list skills /skill link auto-fire on a file extension or keyword ``` ### Telegram commands | Command | What it does | | ---------------------------- | -------------------------------- | | `/agent ` | autonomous multi-step execution | | `/status` | show the current topic session | | `/stop` | halt whatever the bot is doing | | `/clear` | reset the topic | | `/show ` | view a file from the linked repo | | `/web ` | force a web search | | `/mode snap, think, or nuke` | change reasoning mode | | `/preview new` | start a live preview | | `/revert` | undo the last commit | | `/skill` | manage skills | | `/help` | show usage | *** ## The hosted web app ### Connect your wallet Open the app and connect your Solana wallet (Phantom, Solflare, or Backpack). Signing in creates your account. Your chat history is tied to this account. ### Deposit $FORGE Deposit $FORGE into your account balance. You are billed only when the agent runs, drawn from this balance. ### Chat Describe what you want, switch reasoning modes, and copy code straight from the chat. Your conversations are saved and survive a refresh, tied to your wallet. *** ## The $FORGE token ### Pay per use There are no flat monthly fees for idle AI. You deposit $FORGE, and every prompt draws from your balance based on real usage. Pricing is set in USD under the hood and paid in $FORGE, so a price swing does not change what a query actually costs. ### Deflation A share of every charge is bought back and burned, so real usage drives the token. ### Why a token at all Forge is open source, so anyone can self-host for free with their own key. Most people will not want to run their own bot, so the hosted version runs on $FORGE. The token is the access and payment layer for the hosted product, not a side feature bolted on. ### Ticker $FORGE, on Solana. *** ## Architecture Forge follows an open-core model. * The open-source repo is the engine. Self-hosters run it directly with their own keys, for free. * The hosted product imports the engine as a dependency and adds accounts, wallets, billing, and the web app on top. This means there is one engine with two consumers: self-hosters run it directly, and the hosted service wraps it. The engine never contains any billing, wallet, or token logic. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.forgee.xyz/forge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.