Forge Documentation

Requirements

Step 1 — Get a VPS

A VPS (Virtual Private Server) is a remote computer you rent. Your AI agent runs here — not on your laptop. This means it's available 24/7 from any device, and your local machine stays clean.

Step 2 — Connect to Your Server

SSH (Secure Shell) lets you type commands on your remote server from your own computer. Think of it as a remote control for your VPS.

ssh root@YOUR_SERVER_IP

ssh root@YOUR_SERVER_IP

You're connected when you see a prompt like:

root@ubuntu:~#

Step 3 — Deploy Forge

Three commands. The script handles everything else.

apt update && apt install -y git
git clone https://github.com/HodgeLuke/forge-dev.git
cd forge-dev && bash deploy.sh

The script will ask for:

The script runs 11 automated steps. Each shows a green ✓ on success. On completion, you'll see:

✓ FORGE DEPLOYMENT COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Your Agent
  URL: https://agent.yourdomain.com
  Password: [auto-generated]
Security Layers Active
  ✓ Cloudflare Tunnel
  ✓ Zero Trust Access
  ✓ OpenCode server password
  ✓ UFW firewall
  ✓ fail2ban + kernel hardening

Step 4 — Access Your Agent

1. Open the URL from the deployment output in any browser
2. Cloudflare Zero Trust asks for your email — enter the email you configured
3. Check your inbox for a verification code and enter it
4. The OpenCode interface asks for a password — enter the generated password
5. You're in. Your AI coding agent is live.

MCP Server Configuration

MCP (Model Context Protocol) connects your agent to external tools and services. Forge ships with 7 pre-configured servers:

Cloudflare servers use OAuth — the agent will prompt you to authorize in your browser on first use. GitHub, Supabase, and Brave Search use API tokens configured during setup.

Agent Templates

Four pre-built agent templates ship in the agents/ folder:

Use them by referencing @agent-name in your OpenCode session. Each template contains standing instructions, scope boundaries, and output format rules.

Creating a Cloudflare API Token

1. Go to dash.cloudflare.com/profile/api-tokens
2. Click Create Token
3. Click "Get started with a custom token" (bottom option)
4. Add these permissions:
   • Account → D1 → Edit
   • Account → Cloudflare Workers Scripts → Edit
   • Account → Cloudflare Tunnel → Edit
   • Account → Access: Apps and Policies → Edit
   • Zone → DNS → Edit
5. Account Resources: Include → your account
6. Zone Resources: Include → your domain (or All zones)
7. Click Continue → Create Token
8. Copy immediately — Cloudflare only shows it once

Useful Commands

# Check agent status
systemctl status opencode

# Check tunnel status
systemctl status cloudflared

# View agent logs (live stream)
journalctl -u opencode -f

# Restart the agent
systemctl restart opencode

# Restart the tunnel
systemctl restart cloudflared

# View your credentials
cat /root/.forge-credentials

# Terminal access (bypasses browser)
OPENCODE_SERVER_PASSWORD='YOUR_PASS' opencode attach http://127.0.0.1:4096

Troubleshooting

Error 1033 — Cloudflare Tunnel error

The tunnel isn't connected. Check its status:

systemctl status cloudflared
journalctl -u cloudflared -n 20

If you see "Unauthorized" — the API token may have been rotated since deployment. Re-run bash deploy.sh with a fresh token.

Permission denied when cloning the repo

Either you haven't accepted the GitHub invitation (check email from HodgeLuke), or you're using your GitHub password instead of a Personal Access Token. GitHub requires tokens for command-line access — create one at github.com → Settings → Developer settings → Personal access tokens.

Zero Trust keeps asking for email

The WebSocket/Zero Trust cookie conflict. In your Cloudflare dashboard → Zero Trust → Settings → enable "Binding Cookie" and set "SameSite Attribute" to "None."

Agent is slow or unresponsive

systemctl restart opencode
journalctl -u opencode -f

Most common cause: no LLM API key configured. OpenCode needs at least one provider key (OpenAI, Anthropic, Google, etc.) to function. Configure it in the OpenCode settings once you're logged in.

Security Model

Forge implements 5 layers of defense-in-depth, addressing CVE-2026-22812 (CVSS 8.8, unauthenticated RCE) and CVE-2026-22813 (CVSS 9.6, XSS-to-RCE). Every layer is automated by the deployment script.