Arcade Engine configuration
Arcade Engine’s configuration is a YAML file with the following sections:
api
- Configures the server for specific protocolsauth
- Configures user authorization providers and token storagecache
- Configures the short-lived cachellm
- Defines a collection of AI models available for routingsecurity
- Configures security and encryptionstorage
- Configures persistent storagetelemetry
- 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 authenticationapi.http.host
(default:localhost
) - Address to which Arcade Engine binds its server (e.g.,localhost
or0.0.0.0
)api.http.read_timeout
(optional, default:30s
) - Timeout for reading data from clientsapi.http.write_timeout
(optional, default:1m
) - Timeout for writing data to clientsapi.http.idle_timeout
(optional, default:30s
) - Timeout for idle connectionsapi.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 toolssecret
(required) - Secret used to authenticate with the workertimeout
(optional, default:30s
) - Timeout for calling the worker’s toolsretry
(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
- 1.0: Full example and schema