Configuration

Every FORGE project is driven by a single configuration file — forge.yaml — located at the root of your project. This file defines your application name, technology choices, authentication method, supported languages, providers, and domain routing. FORGE reads this file during code generation, migrations, and deployment.

forge.yaml Reference

Here is a complete forge.yaml with all available fields:

# =============================================================================
# FORGE Project Configuration
# =============================================================================

# Project identity
name: myapp                     # Application name (lowercase, no spaces)
version: 1.0.0                  # Your application version

# Technology stack
backend: rust                   # Backend framework: rust | laravel | fastapi | node
frontend: nextjs                # Frontend framework: nextjs | nuxtjs | angular | vanilla
template: base                  # Template: base | crm | helpdesk | invoicing

# Authentication
auth:
  method: email_password        # email_password | mobile_otp | mobile_password
  jwt:
    access_ttl: 15m             # Access token lifetime
    refresh_ttl: 7d             # Refresh token lifetime
  password:
    min_length: 8               # Minimum password length
    require_uppercase: true     # Require at least one uppercase letter
    require_number: true        # Require at least one digit

# Languages
languages:
  - code: en
    name: English
    direction: ltr
  - code: ar
    name: العربية
    direction: rtl
default_language: en            # Must match one of the language codes above

# Provider configuration
providers:
  sms:
    driver: twilio              # twilio | vonage | unifonic | mock
  email:
    driver: smtp                # smtp | mailgun | sendgrid | ses | mock
  storage:
    driver: local               # local | s3 | minio | gcs
  payments:
    driver: stripe              # stripe | paddle | moyasar | mock

# Domain routing
domains:
  web: myapp.test               # Public website domain
  admin: admin.myapp.test       # Admin dashboard domain
  api: api.myapp.test           # API server domain

Configuration Sections

Project Identity

Field	Type	Required	Description
name	string	Yes	Project name used for directories, database names, and domain prefixes. Must be lowercase with no spaces.
version	string	No	Your application version. Follows semver. Defaults to 1.0.0.

The name field is immutable after generation

Changing the project name after generation will not rename databases, directories, or domain entries. Choose your name carefully before running forge new.

Technology Stack

Field	Type	Default	Options
backend	string	rust	rust, laravel, fastapi, node
frontend	string	nextjs	nextjs, nuxtjs, angular, vanilla
template	string	base	base, crm, helpdesk, invoicing

The backend and frontend fields determine which template directory FORGE uses during code generation. The template field selects which feature modules are included.

Authentication

The auth.method field controls which authentication flow is generated:

Method	Description	Requires
email_password	Traditional email + password login with email verification	Email provider
mobile_otp	Mobile number login with one-time password via SMS	SMS provider
mobile_password	Mobile number + password login with SMS verification	SMS provider

Changing the auth method after generation

You can change the auth method by updating forge.yaml and running forge upgrade:apply. FORGE will regenerate the affected authentication handlers, frontend forms, and database migrations.

Languages

The languages array defines all supported locales. Each entry requires:

Field	Type	Description
code	string	ISO 639-1 language code (e.g., en, ar, fr)
name	string	Human-readable language name
direction	string	Text direction: ltr or rtl

The default_language field must match one of the defined language codes. It determines:

• The default locale for new users
• The fallback locale when a translation is missing
• The language used during database seeding

languages:
  - code: en
    name: English
    direction: ltr
  - code: ar
    name: العربية
    direction: rtl
  - code: fr
    name: Français
    direction: ltr
default_language: en

Adding languages after project creation

Use the CLI to add languages dynamically:

forge lang:add fr --name="Français" --direction=ltr

This updates forge.yaml, generates translation seeders, and adds the locale to the frontend language switcher.

Providers

Providers are pluggable service integrations. Each provider type has a driver field that selects the implementation:

providers:
  sms:
    driver: twilio
  email:
    driver: smtp
  storage:
    driver: local
  payments:
    driver: stripe

Available drivers for each provider type:

Provider	Drivers	Default
SMS	twilio, vonage, unifonic, mock	mock
Email	smtp, mailgun, sendgrid, ses, mock	mock
Storage	local, s3, minio, gcs	local
Payments	stripe, paddle, moyasar, mock	mock

Provider credentials are stored in environment variables

The forge.yaml file only specifies which driver to use. API keys, secrets, and connection details are stored in .env files. See the Environment Variables section below.

Domain Routing

The domains section maps each application to its local development domain:

domains:
  web: myapp.test               # → apps/web (Next.js)
  admin: admin.myapp.test       # → apps/admin (Next.js)
  api: api.myapp.test           # → apps/api (Rust)

Caddy uses these domains to route incoming HTTPS requests to the correct application server. FORGE automatically configures the Caddyfile and /etc/hosts entries during project creation.

Environment Variables

FORGE respects several environment variables that control CLI behavior and project configuration.

CLI Environment Variables

Variable	Default	Description
FORGE_PATH	~/.forge	Directory where FORGE stores global configuration and templates
FORGE_TEMPLATES_PATH	~/.forge/templates	Override the default template search path
FORGE_NO_COLOR	false	Disable colored output in the terminal
FORGE_VERBOSE	false	Enable verbose logging for debugging
FORGE_ENCRYPTION_KEY	—	Key used to encrypt sensitive values in forge.yaml

Application Environment Variables

Each generated application includes .env and .env.example files. Key variables include:

API (.env)

# Database
DATABASE_URL=postgresql://forge:forge@localhost:5432/myapp
DATABASE_MAX_CONNECTIONS=10

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-secret-key-here
JWT_ACCESS_TTL=900          # 15 minutes in seconds
JWT_REFRESH_TTL=604800      # 7 days in seconds

# Storage
STORAGE_DRIVER=local
STORAGE_PATH=./uploads
# S3_BUCKET=my-bucket
# S3_REGION=us-east-1
# S3_ACCESS_KEY=...
# S3_SECRET_KEY=...

# SMS (if using SMS auth)
# SMS_DRIVER=twilio
# TWILIO_ACCOUNT_SID=...
# TWILIO_AUTH_TOKEN=...
# TWILIO_FROM_NUMBER=...

# Email
# EMAIL_DRIVER=smtp
# SMTP_HOST=smtp.mailtrap.io
# SMTP_PORT=587
# SMTP_USERNAME=...
# SMTP_PASSWORD=...
# EMAIL_FROM=noreply@myapp.test

# Encryption
ENCRYPTION_KEY=your-encryption-key

Web & Admin (.env.local)

# API connection
NEXT_PUBLIC_API_URL=https://api.myapp.test
NEXT_PUBLIC_APP_NAME=MyApp
NEXT_PUBLIC_DEFAULT_LOCALE=en

# Internal API URL (server-side, bypasses Caddy)
API_INTERNAL_URL=http://localhost:3000

Never commit .env files to version control

The .env files contain secrets (JWT keys, API tokens, database credentials). FORGE generates a .gitignore that excludes these files. Always use .env.example as the committed reference.

The FORGE_ENCRYPTION_KEY Variable

FORGE can encrypt sensitive provider credentials stored in forge.yaml. When set, values marked with the encrypted: prefix are decrypted at runtime:

providers:
  sms:
    driver: twilio
    account_sid: "encrypted:abc123..."   # Decrypted using FORGE_ENCRYPTION_KEY

Generate a new encryption key:

forge secrets:generate-key

Encrypt a value:

forge secrets:encrypt "my-secret-value"

Decrypt a value:

forge secrets:decrypt "enc:v1:abc123..."

Next Steps

• Directory Structure — Understand the generated project layout
• Quick Start — Create and launch your first application
• Provider Pattern — Learn how providers are configured and swapped