Configuration | AMADEV Documentation

Amadev Getting started Why Amadev? Providers Supported providers Custom providers CLI Amadev MCP Git worktrees Schedules Skills Voice Configuration Security Best practices Amadev Getting started Why Amadev? Providers Supported providers Custom providers CLI Amadev MCP Git worktrees Schedules Skills Voice Configuration Security Best practices

# Amadev loads configuration from a single JSON file in your Amadev home directory, with optional environment variable and CLI overrides.

#Where config lives

# By default, Amadev uses ~/.amadev as its home directory. The configuration file is:

Code

~/.amadev

Code

~/.amadev/config.json

Code

~/.amadev/config.json

You can change the home directory by setting AMADEV_HOME or passing --home to amadev daemon start.

Code

AMADEV_HOME

Code

--home

Code

amadev daemon start

#Precedence

# Amadev merges configuration in this order:

Defaults
config.json
Environment variables
CLI flags

Code

config.json

Lists append across sources (for example, hostnames and cors.allowedOrigins).

Code

hostnames

Code

cors.allowedOrigins

#Example

# Minimal example that configures listening address, hostnames, and MCP:

Code

{ "$schema": "https://amadev.org/schemas/amadev.config.v1.json", "version": 1, "daemon": { "listen": "127.0.0.1:6767", "hostnames": ["localhost", ".localhost"], "mcp": { "enabled": true } } }

Code

{ "$schema": "https://amadev.org/schemas/amadev.config.v1.json", "version": 1, "daemon": { "listen": "127.0.0.1:6767", "hostnames": ["localhost", ".localhost"], "mcp": { "enabled": true } } }

daemon.hostnames is the primary field. The old daemon.allowedHosts name still works as a deprecated alias for backward compatibility.

Code

daemon.hostnames

Code

daemon.allowedHosts

#Agent providers

# Agent providers, both the first-class ones Amadev ships with and custom entries you add under agents.providers, are documented on their own page.

Code

agents.providers

See Providers for the mental model and Supported providers for the full list of agents Amadev can launch. For pointing Claude at Anthropic-compatible endpoints (Z.AI, Alibaba/Qwen), multiple profiles, custom binaries, ACP agents, and the additionalModels merge behavior, see Custom providers. The full field reference lives on GitHub at docs/custom-providers.md.

Code

additionalModels

#Voice

# Voice is configured through features.dictation and features.voiceMode, with provider credentials under providers.

Code

features.dictation

Code

features.voiceMode

Code

providers

For voice philosophy, architecture, and complete local/OpenAI setup examples, see Voice docs.

#Logging

# Daemon logging uses separate console and file sinks by default:

Console: info and above
File ($AMADEV_HOME/daemon.log): trace and above
File rotation: 10m max file size, 2 retained files total (active + 1 rotated)

Code

info

Code

$AMADEV_HOME/daemon.log

Code

trace

Code

10m

Code

{ "log": { "console": { "level": "info", "format": "pretty" }, "file": { "level": "trace", "path": "daemon.log", "rotate": { "maxSize": "10m", "maxFiles": 2 } } } }

Code

{ "log": { "console": { "level": "info", "format": "pretty" }, "file": { "level": "trace", "path": "daemon.log", "rotate": { "maxSize": "10m", "maxFiles": 2 } } } }

Legacy fields log.level and log.format are still supported and map to the new destination settings.

Code

log.level

Code

log.format

# You can require a password to connect to the daemon. When set, all HTTP and WebSocket clients must authenticate. Only the /api/health liveness endpoint is exempt, so that process supervisors and load balancers can probe without credentials.

Code

/api/health

The easiest way to set a password is with the CLI:

Code

amadev daemon set-password

Code

amadev daemon set-password

This prompts for a password, writes the bcrypt hash to config.json, and tells you to restart the daemon.

Code

config.json

Alternatively, set the AMADEV_PASSWORD environment variable (plaintext, hashed automatically at startup):

Code

AMADEV_PASSWORD

Code

AMADEV_PASSWORD=my-secret amadev daemon start

Code

AMADEV_PASSWORD=my-secret amadev daemon start

Or write the hash directly in config.json:

Code

config.json

Code

{ "daemon": { "auth": { "password": "$2b$12$..." } } }

Code

{ "daemon": { "auth": { "password": "$2b$12$..." } } }

After setting a password, restart the daemon for the change to take effect.

# The CLI picks up a password from, in order: 1. The password query parameter on a tcp:// host URI: amadev --host "tcp://192.168.1.10:6767?password=my-secret" ls

The AMADEV_PASSWORD environment variable, used as a fallback when the host carries no embedded password (works for localhost:6767, bare host:port, or tcp:// hosts without a password= query): AMADEV_PASSWORD=my-secret amadev ls AMADEV_PASSWORD=my-secret amadev --host 192.168.1.10:6767 ls

The password query parameter on a tcp:// host URI:

Code

password

Code

tcp://

Code

amadev --host "tcp://192.168.1.10:6767?password=my-secret" ls

Code

amadev --host "tcp://192.168.1.10:6767?password=my-secret" ls

The AMADEV_PASSWORD environment variable, used as a fallback when the host carries no embedded password (works for localhost:6767, bare host:port, or tcp:// hosts without a password= query):

Code

AMADEV_PASSWORD

Code

localhost:6767

Code

host:port

Code

tcp://

Code

password=

Code

AMADEV_PASSWORD=my-secret amadev ls AMADEV_PASSWORD=my-secret amadev --host 192.168.1.10:6767 ls

Code

AMADEV_PASSWORD=my-secret amadev ls AMADEV_PASSWORD=my-secret amadev --host 192.168.1.10:6767 ls

A password= in the URI always wins over the env var, so you can keep AMADEV_PASSWORD set globally and still target a different daemon by spelling its password into the URI.

Code

password=

Code

AMADEV_PASSWORD

In the mobile app, enter the password in the direct connection setup screen.

#Common env vars

AMADEV_HOME, set Amadev home directory
AMADEV_PASSWORD, on the daemon, the password to require (plaintext, hashed at startup); on the CLI, the password used to connect when the host URI doesn't include one
AMADEV_LISTEN, override daemon.listen
AMADEV_HOSTNAMES, override/extend daemon.hostnames
AMADEV_ALLOWED_HOSTS, deprecated alias for AMADEV_HOSTNAMES
AMADEV_LOG_CONSOLE_LEVEL, override log.console.level
AMADEV_LOG_FILE_LEVEL, override log.file.level
AMADEV_LOG_FILE_PATH, override log.file.path
AMADEV_LOG_FILE_ROTATE_SIZE, override log.file.rotate.maxSize
AMADEV_LOG_FILE_ROTATE_COUNT, override log.file.rotate.maxFiles
AMADEV_LOG, AMADEV_LOG_FORMAT, legacy log overrides (still supported)
OPENAI_API_KEY, override OpenAI provider key
AMADEV_VOICE_LLM_PROVIDER, override voice LLM provider (claude, codex, opencode)
AMADEV_DICTATION_STT_PROVIDER, AMADEV_VOICE_STT_PROVIDER, AMADEV_VOICE_TTS_PROVIDER, override voice provider selection (local or openai)
AMADEV_LOCAL_MODELS_DIR, control local model directory
AMADEV_DICTATION_LOCAL_STT_MODEL, override local dictation STT model
AMADEV_VOICE_LOCAL_STT_MODEL, AMADEV_VOICE_LOCAL_TTS_MODEL, override local voice STT/TTS models
AMADEV_VOICE_LOCAL_TTS_SPEAKER_ID, AMADEV_VOICE_LOCAL_TTS_SPEED, optional local voice TTS tuning

Code

AMADEV_HOME

Code

AMADEV_PASSWORD

Code

AMADEV_LISTEN

Code

daemon.listen

Code

AMADEV_HOSTNAMES

Code

daemon.hostnames

Code

AMADEV_ALLOWED_HOSTS

Code

AMADEV_HOSTNAMES

Code

AMADEV_LOG_CONSOLE_LEVEL

Code

log.console.level

Code

AMADEV_LOG_FILE_LEVEL

Code

log.file.level

Code

AMADEV_LOG_FILE_PATH

Code

log.file.path

Code

AMADEV_LOG_FILE_ROTATE_SIZE

Code

log.file.rotate.maxSize

Code

AMADEV_LOG_FILE_ROTATE_COUNT

Code

log.file.rotate.maxFiles

Code

AMADEV_LOG

Code

AMADEV_LOG_FORMAT

Code

OPENAI_API_KEY

Code

AMADEV_VOICE_LLM_PROVIDER

Code

claude

Code

codex

Code

opencode

Code

AMADEV_DICTATION_STT_PROVIDER

Code

AMADEV_VOICE_STT_PROVIDER

Code

AMADEV_VOICE_TTS_PROVIDER

Code

local

Code

openai

Code

AMADEV_LOCAL_MODELS_DIR

Code

AMADEV_DICTATION_LOCAL_STT_MODEL

Code

AMADEV_VOICE_LOCAL_STT_MODEL

Code

AMADEV_VOICE_LOCAL_TTS_MODEL

Code

AMADEV_VOICE_LOCAL_TTS_SPEAKER_ID

Code

AMADEV_VOICE_LOCAL_TTS_SPEED

#Schema

# For editor autocomplete/validation, set $schema to:

Code

$schema

Code

https://amadev.org/schemas/amadev.config.v1.json

Code

https://amadev.org/schemas/amadev.config.v1.json

View this page on GitHub