Configuration Overview

Genbox uses a declarative genbox.yaml file to configure your development environments.

Configuration Philosophy

Genbox follows a declarative-first approach:

Explicit over implicit: You control exactly what happens
$detect for convenience: Opt-in auto-detection where useful
Profiles for variations: Different configs for different workflows
Computed resolution: See exactly what will execute

File Structure


project/
├── genbox.yaml              # Main configuration (commit this)
├── .env.genbox              # Secrets and credentials (gitignore)
└── .genbox/
    ├── detected.yaml        # Auto-detected values (gitignore)
    └── resolved.yaml        # Computed final config (gitignore)

Basic Example


version: 4
 
project:
  name: myapp
  structure: monorepo
 
apps:
  frontend:
    path: ./web
    type: frontend
    port: 3000
    framework: nextjs
 
  backend:
    path: ./api
    type: backend
    port: 3050
    framework: nestjs
 
provides:
  mongodb:
    type: database
    image: mongo:7
    port: 27017
 
profiles:
  quick:
    size: small
    apps: [frontend]
    default_connection: staging
 
  full:
    size: large
    apps: [frontend, backend]
    default_connection: local

Key Sections

genbox.yaml Schema - Complete schema reference
Apps Configuration - Configure your applications
Profiles - Define environment variations
Infrastructure - Database, cache, queue setup

Quick Reference

Section	Purpose
`project`	Project metadata and structure
`apps`	Application definitions
`provides`	Infrastructure services
`environments`	External environment connections
`profiles`	Environment configurations
`defaults`	Default values
`hooks`	Lifecycle hooks
`repos`	Multi-repo configurations

Resolution Order

When creating an environment, values are resolved in this order (highest priority first):

CLI flags (--size large)
Profile settings (profiles.full.size)
Explicit values (apps.api.port: 3050)
$detect markers (auto-detected from project)
Default values (defaults.size)
Schema defaults (built-in fallbacks)

Validation

Always validate your configuration:


# Validate current config
gb validate
 
# See resolved values
gb config show --explain
 
# Compare profiles
gb config diff quick full