Arcade Engine configuration

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

  • api - Configures the server for specific protocols
  • auth - Configures user authorization providers and token storage
  • cache - Configures the short-lived cache
  • llm - Defines a collection of AI models available for routing
  • security - Configures security and encryption
  • storage - Configures persistent storage
  • telemetry - Configures telemetry and observability (OTEL)
  • tools - Configures tools for AI models to use

Specify a config file

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

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

Or, for local development:

arcade dev -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:

llm:
  models:
    - id: primary
      openai:
        api_key: ${env:OPENAI_API_KEY}

External files (useful in cloud setups):

llm:
  models:
    - id: primary
      openai:
        api_key: ${file:/path/to/secret}

API configuration

HTTP is the only 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.http.host (default: localhost) - Address to which Arcade Engine binds its server (e.g., localhost or 0.0.0.0)
  • api.http.read_timeout (optional, default: 30s) - Timeout for reading data from clients
  • api.http.write_timeout (optional, default: 1m) - Timeout for writing data to clients
  • api.http.idle_timeout (optional, default: 30s) - Timeout for idle connections
  • api.http.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

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

Auth configuration

Arcade Engine manages auth for tools and agents. 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.

Configuring the cache is optional. If not configured, the cache will default to an in-memory cache implementation suitable for a single-node Arcade Engine deployment.

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

Model configuration

The llm.models section defines the models that the engine can route to, and the API keys or parameters for each model. Each item in the models array must have a unique id and a provider-specific configuration.

This example shows configuration for connecting to OpenAI and Anthropic:

llm:
  models:
    - id: primary
      openai:
        api_key: ${env:OPENAI_API_KEY}
    - id: secondary
      anthropic:
        api_key: ${env:ANTHROPIC_API_KEY}
        api_version: '2023-06-01'

For more details on model configuration and model-specific parameters, see model configuration.

Routing

When client code calls the Arcade Model API, it specifies a model by name. Arcade Engine matches the model name to a model in the configuration and routes the request to the appropriate provider.

If more than one model provider is configured, Arcade Engine will attempt to route to the correct provider using known model names.

from openai import OpenAI
 
client = OpenAI(base_url="http://localhost:9099/v1")
 
response = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Who is the CEO of Apple?"},
    ],
    model="gpt-4o",
)

If two model providers have the same models or a custom model is used, the provider can be explicitly specified using its id.

For example, given an llm.models configuration with one provider named primary, this request will be routed to primary with the model gpt-4o:

response = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Who is the CEO of Apple?"},
    ],
    model="primary/gpt-4o",
)

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}

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).

You must replace the value of ROOT_KEY_1 in engine.env before deploying to production.

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 and /v1/chat/completions 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
      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

Workers must be configured with a secret that is used to authenticate with the worker. This ensures that workers are not exposed to the public internet without security.

If api.development = true, the secret will default to "dev" for local development only. In production, the secret must be set to a random value.

Config file version history