Agent Configuration - FlatRun Docs

The FlatRun Agent is configured through a YAML file. By default, it looks for configuration in these locations (in order):

/etc/flatrun/config.yml
~/.config/flatrun/config.yml
/opt/flatrun/config.yml
./config.yml (current directory)

You can also specify a config file with the --config flag.

Complete Configuration Reference

# Path where deployments are stored
deployments_path: /var/flatrun/deployments

# Docker socket connection
docker_socket: unix:///var/run/docker.sock

# API server configuration
api:
  host: 0.0.0.0           # Listen address
  port: 8090              # Listen port
  enable_cors: true       # Enable CORS headers
  allowed_origins:        # Allowed CORS origins
    - http://localhost:5173
    - https://your-domain.com

# Authentication
auth:
  enabled: true           # Require authentication
  api_keys:               # Valid API keys
    - "your-api-key-here"
  jwt_secret: "random-secret-string"  # JWT signing secret

# Domain configuration
domain:
  default_domain: ""      # Default domain for auto-subdomains
  auto_subdomain: false   # Auto-generate subdomains
  auto_ssl: false         # Auto-provision SSL certificates
  subdomain_style: words  # Style: words, hex, short

# Nginx integration
nginx:
  enabled: false          # Enable Nginx management
  image: nginx:alpine     # Docker image
  container_name: nginx   # Container name
  config_path: ""         # Config directory (auto if empty)
  reload_command: "nginx -s reload"
  external: false         # Use external Nginx

# SSL/Certbot configuration
certbot:
  enabled: false          # Enable SSL automation
  image: certbot/certbot  # Docker image
  email: admin@example.com  # Let's Encrypt email
  staging: true           # Use staging environment
  certs_path: ""          # Certificates directory
  webroot_path: ""        # Webroot for validation
  dns_provider: ""        # DNS provider for DNS-01

# Logging
logging:
  level: info             # debug, info, warn, error
  format: json            # json or text

# Health checking
health:
  check_interval: 30s     # Check interval
  metrics_retention: 24h  # Metrics history

# Infrastructure services
infrastructure:
  default_proxy_network: proxy
  default_database_network: database

  database:
    enabled: false
    type: mysql           # mysql, mariadb, postgres
    container: ""         # Container name
    host: ""              # External host
    port: 3306
    root_user: root
    root_password: ""

  redis:
    enabled: false
    container: ""
    host: ""
    port: 6379
    password: ""

Configuration Sections

Deployments Path

The deployments_path specifies where FlatRun stores and discovers deployments. Each subdirectory containing a docker-compose.yml is treated as a deployment.

deployments_path: /var/flatrun/deployments

API Configuration

Configure the REST API server:

Option	Default	Description
`api.host`	`0.0.0.0`	IP address to bind to
`api.port`	`8080`	Port number
`api.enable_cors`	`false`	Enable CORS headers
`api.allowed_origins`	`[]`	List of allowed origins

Authentication

FlatRun supports API key and JWT authentication:

Option	Description
`auth.enabled`	Require authentication for API requests
`auth.api_keys`	List of valid API keys for login
`auth.jwt_secret`	Secret key for signing JWT tokens

Security: Always generate strong, random values for API keys and JWT secrets. Use openssl rand -base64 32 to generate secure values.

Domain Configuration

Configure automatic subdomain and domain handling:

Option	Description
`domain.default_domain`	Base domain for auto-generated subdomains
`domain.auto_subdomain`	Automatically generate subdomains for new deployments
`domain.auto_ssl`	Automatically provision SSL for new domains
`domain.subdomain_style`	Generation style: `words`, `hex`, or `short`

Logging

Configure logging output:

Option	Values	Description
`logging.level`	`debug`, `info`, `warn`, `error`	Minimum log level
`logging.format`	`json`, `text`	Log output format

Environment Variables

Configuration values can reference environment variables using ${VAR_NAME} syntax:

auth:
  jwt_secret: ${JWT_SECRET}

infrastructure:
  database:
    root_password: ${MYSQL_ROOT_PASSWORD}

Minimal Configuration

The simplest configuration to get started:

deployments_path: /var/flatrun/deployments

api:
  port: 8090

auth:
  enabled: true
  api_keys:
    - "your-secure-key"
  jwt_secret: "your-jwt-secret"

Production Configuration

A more complete configuration for production use:

deployments_path: /var/flatrun/deployments

api:
  host: 127.0.0.1  # Only local access, use reverse proxy
  port: 8090
  enable_cors: true
  allowed_origins:
    - https://dashboard.example.com

auth:
  enabled: true
  api_keys:
    - ${FLATRUN_API_KEY}
  jwt_secret: ${JWT_SECRET}

domain:
  default_domain: apps.example.com
  auto_subdomain: true
  auto_ssl: true
  subdomain_style: words

nginx:
  enabled: true
  external: true  # Using existing Nginx

certbot:
  enabled: true
  email: admin@example.com
  staging: false  # Production certificates

logging:
  level: info
  format: json

infrastructure:
  database:
    enabled: true
    type: mysql
    container: flatrun-mysql
    root_password: ${MYSQL_ROOT_PASSWORD}