All configurable options in DotAgents, organized by category.
General Settings
| Setting | Description | Default |
|---|
| AI Provider | Primary LLM provider (OpenAI, Groq, Gemini) | — |
| Model | Chat model to use | Provider default |
| STT Provider | Speech-to-text engine | OpenAI Whisper |
| STT Language | Language for speech recognition | English |
| TTS Provider | Text-to-speech engine | OpenAI |
| TTS Voice | Voice for spoken responses | Alloy |
| TTS Auto-play | Automatically speak responses | Off |
| Theme | Dark or light mode | Dark |
| Langfuse Enabled | Enable LLM tracing | Off |
| Langfuse Public Key | Langfuse public API key | — |
| Langfuse Secret Key | Langfuse secret API key | — |
| Langfuse Base URL | Self-hosted Langfuse URL | Cloud default |
Provider Settings
OpenAI
| Setting | Description |
|---|
| API Key | OpenAI API key (sk-...) |
| Base URL | Custom endpoint (default: https://api.openai.com/v1) |
| Organization | OpenAI organization ID (optional) |
Groq
| Setting | Description |
|---|
| API Key | Groq API key (gsk_...) |
| Base URL | Custom endpoint (optional) |
Google Gemini
| Setting | Description |
|---|
| API Key | Google AI API key |
Custom Provider
| Setting | Description |
|---|
| Base URL | Any OpenAI-compatible endpoint |
| API Key | Authentication key |
MCP Server Settings
See MCP Server Configuration for details.
| Setting | Description |
|---|
| mcpServers | JSON object of MCP server configurations |
| Server transport | stdio, websocket, or streamableHttp |
| Server command | Process to spawn (stdio only) |
| Server args | Process arguments (stdio only) |
| Server env | Environment variables |
| Server URL | Endpoint URL (remote only) |
| Server disabled | Disable without removing |
| Tool approval | Require user confirmation |
Agent Settings
See Agent Profiles for details.
| Setting | Description |
|---|
| Agent Profiles | List of configured agent profiles |
| Default Agent | Agent used by default |
| Tool Configuration | Per-agent tool access |
| Model Override | Per-agent model/provider |
| Skills Configuration | Per-agent skill access |
Remote Server Settings
See Remote Server & Mobile Pairing for setup and security guidance.
| Setting | Description | Default |
|---|
| Remote Server Enabled | Starts the Fastify HTTP API for mobile/operator clients | false |
| Port | Local HTTP port | 3210 |
| Bind Address | Interface to listen on; use 127.0.0.1 for local-only, 0.0.0.0 for LAN/tunnel | 127.0.0.1 |
| API Key | Bearer token required by remote clients | Generated locally |
| Log Level | Remote API log verbosity | info |
| CORS Origins | Allowed browser origins | * |
| Cloudflare Tunnel Enabled | Expose the local server through a tunnel | false |
| Cloudflare Tunnel Mode | Quick tunnel or named tunnel | Quick tunnel |
| Terminal QR | Print QR payloads for headless pairing | Auto for QR/headless flows |
Messaging Integration Settings
Discord
See Discord Integration for setup and access-control guidance.
| Setting | Description | Default |
|---|
| Discord Enabled | Starts or stops the Discord bot integration | false |
| Bot Token | Discord bot token; can also come from DOTAGENTS_DISCORD_BOT_TOKEN | — |
| Allow Direct Messages | Lets trusted users message the bot directly | true |
| Require Mention | Requires bot mentions in guild channels | true in shared-channel deployments |
| Allow User IDs | Users allowed to chat with the bot | Empty |
| Allow Guild IDs | Guilds allowed to chat with the bot | Empty |
| Allow Channel IDs | Channels allowed to chat with the bot | Empty |
| Allow Role IDs | Roles allowed to chat with the bot | Empty |
| DM Allow User IDs | Optional narrower user list for direct messages | Empty |
| Operator Allow User/Guild/Channel/Role IDs | Separate allowlists for privileged /ops commands | Empty |
| Default Profile ID | Agent profile used for Discord messages; can also come from DOTAGENTS_DISCORD_DEFAULT_PROFILE_ID | — |
| Log Messages | Store Discord message content in integration logs | false |
WhatsApp
See WhatsApp Integration for MCP setup and environment variables.
| Setting | Description | Default |
|---|
| WhatsApp Enabled | Enables the desktop integration controls for the WhatsApp MCP server | false |
| Allow From | Phone numbers allowed to message the agent | Empty |
| Operator Allow From | Phone numbers allowed to run /ops commands | Empty |
| Auto Reply | Automatically route incoming messages to an agent reply flow | false |
| Log Messages | Store WhatsApp message content in integration logs | false |
Loop Settings
| Setting | Description |
|---|
| Prompt | Message to send on each interval |
| Interval | Time between executions |
| Agent | Which agent handles the loop |
| Enabled | Whether the loop is active |
UI Settings
| Setting | Description | Default |
|---|
| Theme | dark or light | dark |
| Layout | Session view layout preference | Grid |
| Panel Mode | Floating panel vs full window | Full window |
Storage Locations
Desktop
| Platform | Config Path |
|---|
| macOS | ~/Library/Application Support/DotAgents/ |
| Windows | %APPDATA%/DotAgents/ |
| Linux | ~/.config/DotAgents/ |
Agent Protocol
| Layer | Path |
|---|
| Global | ~/.agents/ |
| Workspace | ./.agents/ (project directory) |
Configuration Files
| File | Content |
|---|
config.json | Main application settings |
.agents/dotagents-settings.json | General settings subset |
.agents/mcp.json | MCP server configuration |
.agents/models.json | Model presets and provider keys |
.agents/system-prompt.md | Custom system prompt |
.agents/agents.md | Agent guidelines |
.agents/layouts/ui.json | UI layout settings |
Mobile
All settings are stored in AsyncStorage on the device:
| Setting | Description |
|---|
| API Key | Bearer token for authentication |
| Base URL | Desktop remote server or OpenAI-compatible API endpoint URL |
| Model | Model identifier |
| Environment | Local vs Cloud toggle |
| Voice Preferences | TTS voice, auto-play, language |
Next Steps