Skip to main content

​
Overview

Forge uses environment variables for configuration. Set these in your shell, .env file, or deployment platform.
Never commit secrets! Add .env to your .gitignore and use environment-specific configuration for production.

​
Core Configuration

​
Server Configuration

​
HOST
string
default:"127.0.0.1"
The host address for the Forge backend server
HOST=0.0.0.0  # Listen on all interfaces
​
BACKEND_PORT
number
default:"auto-assigned"
Port for the backend API server. Auto-assigned by scripts/setup-dev-environment.js in development
BACKEND_PORT=8080
​
FRONTEND_PORT
number
default:"3000"
Port for the frontend development server
FRONTEND_PORT=3000

​
GitHub Integration

​
OAuth Configuration

​
GITHUB_CLIENT_ID
string
GitHub OAuth App Client ID for custom authentication
GITHUB_CLIENT_ID=Iv1.1234567890abcdef
Not required for basic usage. Forge includes default OAuth credentials for development. Set this only if you want to use your own GitHub OAuth App.
​
GITHUB_CLIENT_SECRET
string
GitHub OAuth App Client Secret (production only)
GITHUB_CLIENT_SECRET=your_secret_here
Never commit this! Use secret management services in production (AWS Secrets Manager, HashiCorp Vault, etc.)

​
Creating Your Own GitHub OAuth App

If you want to use your own GitHub OAuth credentials:
1

Create OAuth App

Go to GitHub Developer Settings → OAuth Apps → New OAuth App
2

Configure App

  • Application name: “My Forge Instance”
  • Homepage URL: http://localhost:3000
  • Authorization callback URL: http://localhost:3000/auth/github/callback
3

Get Credentials

After creating, copy the Client ID and generate a Client Secret
4

Set Environment Variables

export GITHUB_CLIENT_ID=your_client_id
export GITHUB_CLIENT_SECRET=your_client_secret

​
Analytics & Monitoring

​
POSTHOG_API_KEY
string
PostHog API key for analytics (optional)
POSTHOG_API_KEY=phc_1234567890abcdef
Forge includes optional PostHog integration for usage analytics. This is completely optional and disabled by default.

​
Development & Debugging

​
DISABLE_WORKTREE_ORPHAN_CLEANUP
boolean
default:"false"
Disable automatic cleanup of orphaned git worktrees (debug mode)
DISABLE_WORKTREE_ORPHAN_CLEANUP=1
Only use this for debugging worktree issues. Leaving it enabled will accumulate orphaned worktrees over time.
​
RUST_LOG
string
default:"info"
Rust logging level for backend debugging
RUST_LOG=debug      # Detailed logs
RUST_LOG=info       # Normal logs (default)
RUST_LOG=warn       # Warnings only
RUST_LOG=error      # Errors only
​
RUST_BACKTRACE
string
Enable Rust backtraces for debugging
RUST_BACKTRACE=1       # Basic backtraces
RUST_BACKTRACE=full    # Full backtraces with all details

​
Database Configuration

Forge uses SQLite by default. The database is automatically created and seeded from dev_assets_seed/ on first run.
​
DATABASE_URL
string
SQLite database path (advanced use only)
DATABASE_URL=sqlite:./my-custom-forge.db
Changing this requires manual database setup. Use the default unless you know what you’re doing.

​
Using .env Files

Create a .env file in your project root:
.env
# Server Configuration
HOST=127.0.0.1
BACKEND_PORT=8080
FRONTEND_PORT=3000

# GitHub OAuth (optional)
GITHUB_CLIENT_ID=your_client_id_here

# Analytics (optional)
# POSTHOG_API_KEY=your_key_here

# Development
RUST_LOG=info
Multiple environments? Use .env.development, .env.production, etc., and load them with tools like dotenv or deployment platform features.

​
Environment-Specific Configuration

​
Development

.env.development
HOST=127.0.0.1
FRONTEND_PORT=3000
RUST_LOG=debug
DISABLE_WORKTREE_ORPHAN_CLEANUP=1

​
Production

.env.production
HOST=0.0.0.0
BACKEND_PORT=8080
FRONTEND_PORT=80
RUST_LOG=warn

# Use secret management for these
GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}

​
CI/CD

.env.ci
RUST_LOG=error
RUST_BACKTRACE=1
# Minimal config for testing

​
Verification

Check your configuration is working: 
# Start Forge
automagik-forge

# Should see output like:
# ✓ Backend running on http://127.0.0.1:8080
# ✓ Frontend running on http://localhost:3000
# ✓ GitHub OAuth: Using default credentials

​
Troubleshooting

Change BACKEND_PORT or FRONTEND_PORT:
FRONTEND_PORT=3001 automagik-forge
  1. Check GITHUB_CLIENT_ID is set correctly
  2. Verify OAuth callback URL matches your GitHub App settings
  3. Try using default credentials (remove GITHUB_CLIENT_ID)
Remove the database and let Forge recreate it:
rm -rf dev_assets/
automagik-forge

​
Security Best Practices

Never Commit Secrets

Add .env to .gitignore immediately
.gitignore
.env
.env.*
!.env.example

Use Secret Management

In production, use services like:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Kubernetes Secrets
  • Platform-specific solutions

Rotate Credentials

Regularly rotate OAuth secrets and API keys

Principle of Least Privilege

Grant minimal permissions to GitHub OAuth apps

​
Next Steps

LLM Configuration

Configure AI coding agents

GitHub OAuth Setup

Deep dive into GitHub integration

Project Structure

Understand Forge’s file organization