Arcade Engine configuration

Arcade Engine’s configuration is a YAML file  with the following sections:

Specify a config file

To start the Arcade Engine, pass a config file with -c or --config:

arcade-engine -c /path/to/config.yaml

Dotenv files

Arcade Engine automatically loads environment variables from .env files in the directory where it was called. Use the -e or--env flag to specify a path:

arcade-engine -e .env.dev -c config.yaml

Secrets

Arcade Engine supports two ways of passing sensitive information like API keys without storing them directly in the config file.

Environment variables:

topic:
  area:
    - id: primary
      vendor:
        api_key: ${env:OPENAI_API_KEY}

External files (useful in cloud setups):

topic:
  area:
    - id: primary
      vendor:
        api_key: ${file:/path/to/secret}

API configuration

HTTP is the supported protocol for Arcade Engine’s API. The following configuration options are available:

• api.development (optional, default: false) - Enable development mode, with more logging and simple worker authentication
• api.host (default: localhost) - Address to which Arcade Engine binds its server (e.g., localhost or 0.0.0.0)
• api.port (default: 9099) - Port to which Arcade Engine binds its server (e.g., 9099 or 8080)
• api.public_host (optional) - External hostname of the API (e.g., my-public-host.com), if it differs from api.host (for example, when Arcade Engine is behind a reverse proxy)
• api.read_timeout (optional, default: 30s) - Timeout for reading data from clients
• api.write_timeout (optional, default: 1m) - Timeout for writing data to clients
• api.idle_timeout (optional, default: 30s) - Timeout for idle connections
• api.max_request_body_size (optional, default: 4Mb) - Maximum request body size

A typical configuration for production looks like:

api:
  development: false
  host: localhost
  port: 9099

When the Arcade Engine is hosted in a container or behind a reverse proxy, set api.public_host to the external hostname of the API:

api:
  development: false
  host: localhost
  port: 9099
  public_host: my-public-host.com

For local development, set api.development = true. In development mode, Arcade Engine does not require worker authentication.

Auth configuration

Arcade Engine manages auth for AI tools and direct API calls. It supports many built-in auth providers, and can also connect to any OAuth 2.0 authorization server.

The auth.providers section defines the providers that users can authorize with. Each provider must have a unique id in the array. There are two ways to configure a provider:

For built-in providers, use the provider_id field to reference the pre-built configuration. For example:

auth:
  providers:
    - id: default-github
      description: The default GitHub provider
      enabled: true
      type: oauth2
      provider_id: github
      client_id: ${env:GITHUB_CLIENT_ID}
      client_secret: ${env:GITHUB_CLIENT_SECRET}

For custom OAuth 2.0 providers, specify the full connection details in the oauth2 sub-section. For full documentation on the custom provider configuration, see the OAuth 2.0 provider configuration page.

You can specify a mix of built-in and custom providers.

Cache configuration

The cache section configures the short-lived cache.

The cache section has the following configuration options:

• api_key_ttl (optional, default: 10s) - The time-to-live for API keys in the cache

Two cache implementations are available:

• in_memory - (default) An in-memory cache implementation suitable for a single-node Arcade Engine deployment.
• redis - A Redis cache implementation suitable for a multi-node Arcade Engine deployment:

cache:
  api_key_ttl: 10s
  redis:
    addr: "localhost:6379"
    password: ""
    db: 0

Security configuration

The security section configures the root encryption keys that the Arcade Engine uses to encrypt and decrypt data at rest. See the storage configuration section below to configure where data is stored.

A typical configuration looks like this:

security:
  root_keys:
    - id: key1
      default: true
      value: ${env:ROOT_KEY_1}
    - id: key2
      value: ${env:ROOT_KEY_2}

Keys should be a long random string of characters. For example:

openssl rand -base64 32

Default root key

When you install Arcade Engine locally, an engine.env file is created with a default root key:

# Encryption keys (change this when deploying to production)
ROOT_KEY_1=default-key-value

This default value can only be used in development mode (see API configuration above).

Storage configuration

The storage section configures the storage backend that the Arcade Engine uses to store persistent data.

There are three storage implementations available:

• in_memory - (default) An in-memory database, suitable for testing.
• sqlite - A SQLite file on disk, suitable for local development:

storage:
  sqlite:
    # Stores DB in ~/.arcade/arcade-engine.sqlite3
    connection_string: "@ARCADE_HOME/arcade-engine.sqlite3"

• postgres - A PostgreSQL database, suitable for production:

storage:
  postgres:
    user: ${env:POSTGRES_USER}
    password: ${env:POSTGRES_PASSWORD}
    host: ${env:POSTGRES_HOST}
    port: ${env:POSTGRES_PORT}
    db: ${env:POSTGRES_DB}
    sslmode: require

Telemetry configuration

Arcade supports logs, metrics, and traces with OpenTelemetry .

If you are using the Arcade Engine locally, you can set the environment field to local. This will only output logs to the console:

telemetry:
  environment: local
  logging:
    # debug, info, warn, error, fatal
    level: debug
    encoding: console

To connect to OpenTelemetry compatible collectors, set the necessary OpenTelemetry environment variables  in the engine.env file. environment and version are fields that are added to the telemetry attributes, which can be filtered on later.

telemetry:
  environment: prod
  logging:
    level: info
    encoding: console

Notes

• The Engine service name is set to arcade_engine
• Traces currently cover the /v1/health endpoints, as well as authentication attempts

Tools configuration

Arcade Engine orchestrates tools that AI models can use. Tools are executed by distributed workers called workers, which are grouped into directors.

The tools.directors section configures the workers that are available to service tool calls:

tools:
  directors:
    - id: default
      enabled: true
      max_tools: 64
      workers:
        - id: local_worker
          enabled: true
          http:
            uri: "http://localhost:8002"
            timeout: 30
            retry: 3
            secret: ${env:ARCADE_WORKER_SECRET}

When a worker is added to an enabled director, all of the tools hosted by that worker will be available to the model and through the Arcade API.

HTTP worker configuration

The http sub-section configures the HTTP client used to call the worker’s tools:

• uri (required) - The base URL of the worker’s tools
• secret (required) - Secret used to authenticate with the worker
• timeout (optional, default: 30s) - Timeout for calling the worker’s tools
• retry (optional, default: 3) - Number of times to retry a failed tool call

Config file version history

• 1.0: Full example  and schema