Configuration Commands - Automagik Suite Documentation

Overview

Forge configuration is managed through a combination of:

Configuration file: .forge/config.json
Environment variables: Runtime settings
Web UI settings: Visual configuration interface

Configuration File

Location: .forge/config.json

{
  "project_id": "uuid",
  "name": "Project Name",
  "repository": {
    "type": "git",
    "remote": "https://github.com/owner/repo.git",
    "default_branch": "main"
  },
  "github": {
    "enabled": false,
    "owner": "",
    "repo": "",
    "client_id": "",
    "token_encrypted": ""
  },
  "worktrees": {
    "enabled": true,
    "base_path": "./.forge/worktrees",
    "cleanup_on_exit": true,
    "max_concurrent": 5,
    "branch_prefix": "forge/task-",
    "auto_delete_merged": true
  },
  "executors": {
    "default": "claude-code",
    "enabled": ["claude-code", "cursor-cli", "gemini", "codex"]
  },
  "preferences": {
    "auto_cleanup_worktrees": true,
    "stream_logs": true,
    "theme": "dark"
  }
}

Environment Variables

Configure Forge behavior via environment variables:

Server Configuration

# Backend server port (auto-assigned if not set)
export BACKEND_PORT=5000

# Frontend server port
export FRONTEND_PORT=3000

# Server host address
export HOST=127.0.0.1

# Or bind to all interfaces
export HOST=0.0.0.0

GitHub OAuth

# GitHub OAuth App Client ID
export GITHUB_CLIENT_ID=your_github_oauth_app_id

# Optionally set in .env file
echo "GITHUB_CLIENT_ID=your_id" >> .env

AI Agent API Keys

# Claude Code (Anthropic)
export ANTHROPIC_API_KEY=sk-ant-...

# Gemini (Google AI)
export GOOGLE_AI_API_KEY=AIza...

# OpenAI Codex
export OPENAI_API_KEY=sk-...

# These are used by executors when running tasks

Analytics (Optional)

# PostHog analytics key
export POSTHOG_API_KEY=phc_...

Debug Options

# Enable debug logging
export RUST_LOG=debug

# Disable worktree cleanup (for debugging)
export DISABLE_WORKTREE_ORPHAN_CLEANUP=1

# Verbose execution logs
export FORGE_DEBUG=1

Configuration via Web UI

Access settings at http://localhost:3000/settings

General Settings

Project Info
Executors
Worktrees
GitHub

Project Name
Project ID (read-only)
Repository URL
Default Branch

Executor Configuration

Configure each AI agent in .forge/config.json:

Claude Code

{
  "executors": {
    "claude-code": {
      "enabled": true,
      "api_key_env": "ANTHROPIC_API_KEY",
      "model": "claude-3-5-sonnet-20241022",
      "max_tokens": 8192,
      "temperature": 0.7,
      "timeout": 300000
    }
  }
}

Cursor CLI

{
  "executors": {
    "cursor-cli": {
      "enabled": true,
      "cli_path": "/usr/local/bin/cursor",
      "args": ["--headless"],
      "timeout": 300000
    }
  }
}

Gemini

{
  "executors": {
    "gemini": {
      "enabled": true,
      "api_key_env": "GOOGLE_AI_API_KEY",
      "model": "gemini-2.0-flash-exp",
      "temperature": 0.7,
      "timeout": 300000
    }
  }
}

OpenAI Codex

{
  "executors": {
    "codex": {
      "enabled": true,
      "api_key_env": "OPENAI_API_KEY",
      "model": "gpt-4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "timeout": 300000
    }
  }
}

Open Source Agents

{
  "executors": {
    "opencode": {
      "enabled": true,
      "endpoint": "http://localhost:11434",
      "model": "codellama:latest"
    },
    "qwen-code": {
      "enabled": true,
      "endpoint": "http://localhost:11434",
      "model": "qwen-coder:latest"
    }
  }
}

Worktree Configuration

Fine-tune git worktree behavior:

{
  "worktrees": {
    // Enable git worktree isolation
    "enabled": true,

    // Where to create worktrees
    "base_path": "./.forge/worktrees",

    // Clean up when Forge exits
    "cleanup_on_exit": true,

    // Maximum simultaneous worktrees
    "max_concurrent": 5,

    // Branch name format: forge/task-{task-id}
    "branch_prefix": "forge/task-",

    // Auto-delete worktrees after merge
    "auto_delete_merged": true,

    // Keep worktrees for failed tasks
    "keep_on_failure": false,

    // Orphan cleanup interval (seconds)
    "cleanup_interval": 3600
  }
}

GitHub OAuth Configuration

Create GitHub OAuth App

Go to GitHub Settings

Navigate to: https://github.com/settings/developers

New OAuth App

Click “New OAuth App”Settings:

Application name: “Automagik Forge”
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/auth/callback

Get Client ID

Copy the Client ID from the OAuth app page

Set Environment Variable

export GITHUB_CLIENT_ID=your_client_id_here

# Or add to .env file
echo "GITHUB_CLIENT_ID=your_client_id_here" >> .env

Restart Forge

automagik-forge

GitHub authentication will now be available in Settings → GitHub

Configuration Validation

Validate your configuration:

# Start Forge and check logs
automagik-forge

# Look for configuration warnings:
# ✅ Configuration loaded successfully
# ⚠️  Missing GitHub OAuth configuration
# ⚠️  No API keys found for executors
# ❌ Invalid worktree path

# Check configuration file syntax
cat .forge/config.json | jq .

# Verify environment variables
env | grep -E 'FORGE|BACKEND|FRONTEND|ANTHROPIC|GOOGLE|OPENAI'

Configuration Backup

Manual Backup

# Backup configuration
cp .forge/config.json .forge/config.backup.json

# Backup entire .forge directory
tar -czf forge-backup.tar.gz .forge/

# Restore from backup
tar -xzf forge-backup.tar.gz

Export via API

# Export project configuration
curl http://localhost:5000/api/projects/{project-id}/export > config-backup.json

# Import configuration
curl -X POST http://localhost:5000/api/projects/import \
  -H "Content-Type: application/json" \
  -d @config-backup.json

Configuration Migration

From v0.3.x to v0.4.x

# Backup old config
cp .forge/config.json .forge/config.v3.backup.json

# Update structure (handled automatically on startup)
automagik-forge

# Verify migration
cat .forge/config.json | jq .

Key changes:

Added preferences section
New executor configuration format
Enhanced worktree settings

Advanced Configuration

Custom Executor

Add a custom AI agent executor:

{
  "executors": {
    "custom-agent": {
      "enabled": true,
      "type": "http",
      "endpoint": "http://localhost:8887/api/execute",
      "headers": {
        "Authorization": "Bearer ${CUSTOM_AGENT_TOKEN}"
      },
      "timeout": 600000
    }
  }
}

Proxy Configuration

Route executor requests through a proxy:

# HTTP proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# No proxy for localhost
export NO_PROXY=localhost,127.0.0.1

Rate Limiting

Configure executor rate limits:

{
  "executors": {
    "claude-code": {
      "rate_limit": {
        "requests_per_minute": 50,
        "tokens_per_minute": 100000
      }
    }
  }
}

Security Best Practices

Never commit these files:

.forge/config.json (may contain tokens)
.env (contains API keys)
.forge/db.sqlite (project data)

Add to .gitignore:

.forge/
.env

Secure API Keys

# Use environment variables, not config file
export ANTHROPIC_API_KEY=sk-ant-...

# Or use a secrets manager
# AWS Secrets Manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id forge/anthropic-key \
  --query SecretString \
  --output text)

# 1Password CLI
export ANTHROPIC_API_KEY=$(op read "op://Personal/Anthropic API Key/credential")

File Permissions

# Restrict config file permissions
chmod 600 .forge/config.json

# Restrict .forge directory
chmod 700 .forge/

Troubleshooting Configuration

Configuration not loading

# Check file exists
ls -la .forge/config.json

# Validate JSON syntax
cat .forge/config.json | jq .

# Check permissions
ls -l .forge/config.json

# View Forge logs
automagik-forge 2>&1 | grep -i config

Executor not working

# Verify API key is set
echo $ANTHROPIC_API_KEY

# Check executor enabled in config
cat .forge/config.json | jq '.executors'

# Test API key manually
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/messages

GitHub OAuth failing

# Verify client ID
echo $GITHUB_CLIENT_ID

# Check OAuth app settings on GitHub
# Callback URL must match: http://localhost:3000/auth/callback

# Clear cached tokens
rm .forge/github-token.enc

Port conflicts

# Find what's using the port
lsof -i :3000

# Use different ports
automagik-forge --port 3001 --backend-port 5001

Next Steps

Environment Variables

Complete environment variable reference

GitHub OAuth

Detailed GitHub integration setup

LLM Configuration

Configure AI agents and models

Troubleshooting

Common configuration issues

​Overview

​Configuration File

​Environment Variables

​Server Configuration

​GitHub OAuth

​AI Agent API Keys

​Analytics (Optional)

​Debug Options

​Configuration via Web UI

​General Settings

​Executor Configuration

​Claude Code

​Cursor CLI

​Gemini

​OpenAI Codex

​Open Source Agents

​Worktree Configuration

​GitHub OAuth Configuration

​Create GitHub OAuth App

​Configuration Validation

​Configuration Backup

​Manual Backup

​Export via API

​Configuration Migration

​From v0.3.x to v0.4.x

​Advanced Configuration

​Custom Executor

​Proxy Configuration

​Rate Limiting

​Security Best Practices

​Secure API Keys

​File Permissions

​Troubleshooting Configuration

​Next Steps

Environment Variables

GitHub OAuth

LLM Configuration

Troubleshooting

Overview

Configuration File

Environment Variables

Server Configuration

GitHub OAuth

AI Agent API Keys

Analytics (Optional)

Debug Options

Configuration via Web UI

General Settings

Executor Configuration

Claude Code

Cursor CLI

Gemini

OpenAI Codex

Open Source Agents

Worktree Configuration

GitHub OAuth Configuration

Create GitHub OAuth App

Configuration Validation

Configuration Backup

Manual Backup

Export via API

Configuration Migration

From v0.3.x to v0.4.x

Advanced Configuration

Custom Executor

Proxy Configuration

Rate Limiting

Security Best Practices

Secure API Keys

File Permissions

Troubleshooting Configuration

Next Steps