Server

The Server configuration is managed via empire/server/config.yaml.

Once launched, Empire checks for user write permissions on paths specified in config.yaml. If the current user does not have write permissions on these paths, ~/.empire will be set as fallback parent directory and the configuration file will be updated as well. If empire-priv.key and empire-chain.pem are not found in ~/.local/share/empire directory, self-signed certs will be generated.

User Config Overrides

To customize settings without modifying config.yaml, create a config.user.yaml file in the same directory as the base config (e.g. ~/.config/empire/config.user.yaml). This file only needs to contain the settings you want to override — everything else falls through to the base config.

For example, to override the API port and database type:

api:
  port: 8443
database:
  use: mysql
  mysql:
    password: my_secret_password

The config priority order (first wins):

1. Environment variables (EMPIRE_*, e.g. EMPIRE_API__PORT=8443)

2. .env file

3. config.user.yaml (user overrides)

4. config.yaml (base defaults)

Nested settings are deep-merged: overriding database.mysql.password in config.user.yaml does not affect sibling fields like database.mysql.username. Lists are replaced entirely rather than appended.

If using --config /path/to/config.yaml, Empire looks for config.user.yaml in the same directory as the specified config file.

• suppress-self-cert-warning - Suppress the http warnings when launching an Empire instance that uses a self-signed cert.

• obfuscation - Settings for the obfuscation subsystem.

  • timeout - Maximum time in seconds allowed for a single PowerShell obfuscation subprocess. Large modules like PowerView (~4000 lines) and Invoke-Mimikatz (~12000 lines) may exceed the default on resource-constrained environments (e.g. single-CPU containers). Set to 0 to disable the timeout entirely. Also settable via the EMPIRE_OBFUSCATION__TIMEOUT environment variable.

obfuscation:
  # Default: 300
  timeout: 600

• api - Configure the RESTful API.

ip - The IP address to bind the API and Starkiller to. port - The port to bind the API and Starkiller to. secure - Enable HTTPS for the API and Starkiller. Browsers will not work with self-signed certs. Uses .key and .pem file from empire/server/data

api:
  ip: 0.0.0.0
  port: 1337
  secure: false

• database - Configure Empire's database. Empire utilizes MySQL by default for high performance database operations. It can be configured to use sqlite for more lightweight implementations if required For more info on the database, see the Database section.

MySQL supports customizing the default url, username, password, database name, and connection pool settings. By default these are set to

database:
  use: mysql
  mysql:
    url: localhost:3306
    username: empire_user
    password: empire_password
    database_name: empire
    pool_size: 10        # base connections kept open
    max_overflow: 15     # extra connections allowed under load
    pool_pre_ping: true  # detect stale connections before use
    pool_recycle: 3600   # recycle connections after N seconds

The connection pool defaults (25 total connections) handle typical deployments. For heavier workloads with many concurrent agents, increase pool_size and max_overflow.

If using SQLite the database location is customizable with the default setting:

database:
  use: sqlite
  sqlite:
    location: empire/server/data/empire.db

The defaults block defines the properties that are initially loaded into the database when it is first created. These include the staging key, default user and password, obfuscation settings, and default bypasses.

database:
  defaults:
    # staging key will first look at OS environment variables, then here.
    # If empty, will be prompted (like Empire <3.7).
    staging-key: RANDOM
    username: empireadmin
    password: password123
    # The default configuration for global obfuscation.
    obfuscation:
      - language: powershell
        enabled: false
        command: "Token\\All\\1"
        module: "invoke-obfuscation"
        preobfuscatable: true
      - language: csharp
        enabled: false
        command: ""
        module: "confuser"
        preobfuscatable: false
    keyword_obfuscation:
      - Invoke-Empire
      - Invoke-Mimikatz
    bypasses:
      - mattifestation
      - etw
    ip_allow_list: []
    ip_deny_list: []

• empire_compiler - Configure the Empire Compiler module. This block manages settings for the Empire Compiler, which is responsible for handling C# compilation tasks.

repo: The GitHub repository in owner/name format (e.g. BC-SECURITY/Empire-Compiler). ref: The release tag to download (e.g. v0.4.4). Empire queries the GitHub Releases API to find the matching platform asset. directory: (optional) Path to a local compiler directory. When set, Empire uses this directory directly instead of downloading from GitHub. Useful for testing local builds.

empire_compiler:
  repo: BC-SECURITY/Empire-Compiler
  ref: v0.4.4
  # Uncomment to use a local compiler build instead of downloading:
  # directory: /path/to/local/EmpireCompiler

• plugins - Config related to plugins auto_start - boolean, whether the plugin should start automatically. If this is not set, Empire will defer to the plugin's own configuration. auto_execute - run an execute command on the plugin at startup. If this is not set, Empire will defer to the plugin's own configuration.

plugins:
  # Auto-execute plugin with defined settings
  basic_reporting:
    auto_start: true
    auto_execute:
      enabled: true
      options:
        report: all

• plugin_marketplace - This points the server to where Empire should look for additional available plugins to install. This defaults to the BC Security plugin marketplace but can point to a private marketplace as well. name - the display name for the marketplace in Empire git_url - git project to pull plugins from

plugin_marketplace:
  registries:
    - name: BC-SECURITY
      git_url: [e-mail]:BC-SECURITY/Empire-Plugin-Registry-Sponsors.git
      ref: main
      file: registry.yaml

• directories - Control where Empire should read and write specific data.

directories:
  downloads: downloads

• logging - See Logging for more information on logging configuration.

• submodules - Control if submodules will be auto updated on startup.

submodules:
  auto_update: true