Environment Variables

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:

Create OAuth App

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

Configure App

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

Get Credentials

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

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

Port already in use

Change BACKEND_PORT or FRONTEND_PORT:

FRONTEND_PORT=3001 automagik-forge

GitHub authentication fails

Check GITHUB_CLIENT_ID is set correctly
Verify OAuth callback URL matches your GitHub App settings
Try using default credentials (remove GITHUB_CLIENT_ID)

Database errors on startup

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

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

Core Configuration

Server Configuration

GitHub Integration

OAuth Configuration

Creating Your Own GitHub OAuth App

Analytics & Monitoring

Development & Debugging

Database Configuration

Using .env Files

Environment-Specific Configuration

Development

Production

CI/CD

Verification

Troubleshooting

Security Best Practices

Never Commit Secrets

Use Secret Management

Rotate Credentials

Principle of Least Privilege

Next Steps

LLM Configuration

GitHub OAuth Setup

Project Structure

​Overview

​Core Configuration

​Server Configuration

​GitHub Integration

​OAuth Configuration

​Creating Your Own GitHub OAuth App

​Analytics & Monitoring

​Development & Debugging

​Database Configuration

​Using .env Files

​Environment-Specific Configuration

​Development

​Production

​CI/CD

​Verification

​Troubleshooting

​Security Best Practices

Never Commit Secrets

Use Secret Management

Rotate Credentials

Principle of Least Privilege

​Next Steps

LLM Configuration

GitHub OAuth Setup

Project Structure

Overview

Core Configuration

Server Configuration

GitHub Integration

OAuth Configuration

Creating Your Own GitHub OAuth App

Analytics & Monitoring

Development & Debugging

Database Configuration

Using .env Files

Environment-Specific Configuration

Development

Production

CI/CD

Verification

Troubleshooting

Security Best Practices

Next Steps