Configuration

Motus reads configuration from environment variables at runtime. For project-level settings, you can also create a motus.toml file in your project root.

API keys

Set your provider API keys as environment variables before running an agent. You only need the key for the provider you are using.

Variable	Provider	Example value
`OPENAI_API_KEY`	OpenAI	`sk-...`
`ANTHROPIC_API_KEY`	Anthropic	`sk-ant-...`
`OPENROUTER_API_KEY`	OpenRouter	`sk-or-...`
`BRAVE_API_KEY`	Brave Search
`JINA_API_KEY`	Jina AI (MCP)

OpenAIChatClient also reads OPENAI_BASE_URL if you want to point it at a custom endpoint, such as a local model server:

export OPENAI_BASE_URL="http://localhost:11434/v1"

OpenRouterChatClient reads OPENROUTER_BASE_URL to override the default endpoint (https://openrouter.ai/api/v1).

Runtime variables

These variables control Motus’s logging and tracing behavior.

Variable	Purpose	Default
`MOTUS_LOG_LEVEL`	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`	`DEBUG`
`MOTUS_QUIET_SYNC`	Suppress sync barrier warnings (`1` to enable)	off
`MOTUS_TRACING`	Enable trace collection and file export (`1` to enable)	off
`MOTUS_COLLECTION_LEVEL`	Tracing detail: `disabled`, `basic`, `detailed`	`basic`
`MOTUS_TRACING_ONLINE`	Enable tracing and the live trace viewer (`1` to enable)	off
`MOTUS_TRACING_EXPORT`	Write trace files without the live viewer (`1` to enable)	off
`MOTUS_TRACING_DIR`	Directory to write trace output	`traces/trace_<timestamp>/`

Tracing

When tracing is enabled, Motus records task execution, tool calls, and model interactions:

disabled — no trace data is collected.
basic — task-level events only (start, end, errors).
detailed — includes model request/response payloads and tool arguments.

Set MOTUS_TRACING=1 to enable collection and file export. To also open the live trace viewer in your browser, use MOTUS_TRACING_ONLINE=1 instead. If you want file export without the viewer, set MOTUS_TRACING_EXPORT=1.

# Enable basic tracing with file export
export MOTUS_TRACING=1

# Enable detailed tracing with live viewer
export MOTUS_TRACING_ONLINE=1
export MOTUS_COLLECTION_LEVEL=detailed

`motus.toml`

Create a motus.toml file in your project root to store project-level settings. Motus searches upward from the current working directory until it finds this file.

project_id = "my-project"
import_path = "myapp:agent"

Field	Description
`project_id`	Unique identifier for your project, used in deployment and tracing.
`import_path`	Python import path to your agent instance, in `module:attribute` format.

With motus.toml in place, you can omit these values from CLI commands:

# Without motus.toml
motus serve start --import-path myapp:agent

# With motus.toml (reads import_path automatically)
motus serve start

motus deploy creates a motus.toml automatically when you first deploy a project. You can also create it by hand.

`.env` file support

Motus does not auto-load .env files. If you prefer to manage secrets in a .env file, load it yourself at the top of your entry point using python-dotenv:

pip install python-dotenv

Create a .env file in your project root:

# .env
OPENAI_API_KEY=sk-...
MOTUS_LOG_LEVEL=INFO

Then load it before any Motus imports:

from dotenv import load_dotenv

load_dotenv()  # loads .env into os.environ

from motus.agent import ReActAgent

Call load_dotenv() before importing any Motus modules. Environment variables are read when modules initialize, so loading them afterward has no effect.

Verifying your configuration

Run this snippet to confirm your API key is set and the client can initialize:

import os
from motus.models import OpenAIChatClient

assert os.environ.get("OPENAI_API_KEY"), "OPENAI_API_KEY is not set"

client = OpenAIChatClient()
print("Client initialized successfully")

If the key is missing or invalid, the client raises an error at request time with a descriptive message.

Get Started

Run and Deploy

Motus Cloud

Motus Library

Integrations

Contributing

Configuration

API keys

Runtime variables

Tracing

`motus.toml`

`.env` file support

Verifying your configuration

​API keys

​Runtime variables

​Tracing

​motus.toml

​.env file support

​Verifying your configuration

API keys

Runtime variables

Tracing

`motus.toml`

`.env` file support

Verifying your configuration