Configuration

malac is configured with TOML. Files are merged in this order; later sources win, and tables merge key by key:

1. Built-in defaults: the anthropic and openai providers, reading ANTHROPIC_API_KEY and OPENAI_API_KEY.
2. ~/.malac/config.toml, your user config.
3. <project>/.malac/config.toml, where the project root is the nearest directory with .git.
4. [profiles.<name>], when started with --profile <name>.
5. Command-line flags.

MALAC_HOME moves ~/.malac elsewhere. malac config path prints the file locations; malac config show prints the merged result.

Project files are restricted

A project file cannot set mode, providers, mcp, control, permissions, memory, web, update, daemon or profiles: cloning a repository should never be enough to run commands, widen permissions or send your credentials elsewhere. malac ignores those keys with a warning. Set trust_project_config = true in your user config to lift this.

A complete example lives in the repository at examples/config.toml. You can also change any key by asking malac or in the web UI.

Top level

Key	Type	Default	Meaning
model	string	see below	Main model, as provider/model
small_model	string	the session’s model	Model for compaction summaries
vision_model	string	none	Describes images for models with vision = false
mode	string	"ask"	ask, edits or autopilot. Not allowed in project files.
max_steps	integer	200	Tool-call rounds per prompt before the agent is stopped
trust_project_config	bool	false	Let project config set every key. Only read from the user config.

Without model, malac uses anthropic/claude-sonnet-5-5 when ANTHROPIC_API_KEY is set, otherwise openai/gpt-5 when OPENAI_API_KEY is set. With neither, it asks you to run malac provider add.

[providers.<name>]

Not allowed in project files.

Key	Type	Default	Meaning
kind	string	"openai"	"openai" (chat completions) or "anthropic" (Messages API)
base_url	string		For example https://api.openai.com/v1, http://localhost:11434/v1, https://api.anthropic.com
api_key_env	string	none	Environment variable holding the key
headers	table	{}	Extra HTTP headers
models	array of strings	[]	Model ids offered by /model, the model picker and the web UI

Keys are looked up in api_key_env first, then in ~/.malac/credentials.toml (written by malac provider add --api-key-stdin, mode 0600).

[providers.lora]
kind = "openai"
base_url = "https://lora.example.com/v1"
api_key_env = "LORA_API_KEY"
models = ["default", "smart", "fast", "vision"]

[models."provider/model"]

Per-model settings. Quote the table name, since it contains a /.

Key	Type	Default	Meaning
description	string	none	What the model is good at, such as "fast and cheap". Listed to agents that can delegate, so they pick a model per subagent.
context_window	integer	200000	Context size in tokens. Compaction starts at 80% of this.
max_output_tokens	integer	16384	max_tokens sent with each request
vision	bool	assumed true	Set false to route images through vision_model
thinking_budget	integer	none	Anthropic extended thinking budget, in tokens
temperature	float	provider default	Sampling temperature

Agents that can delegate get an “Available models” section in their system prompt: every model in the providers’ models lists, plus every model here with a description. See Subagents.

[models."lora/default"]
description = "general purpose"
context_window = 200000
vision = false

[models."lora/fast"]
description = "fast and cheap: searches, summaries, mechanical edits"

[profiles.<name>]

A profile is any set of keys, applied on top of the merged configuration with --profile <name>. Not allowed in project files, since a profile could carry restricted keys.

[profiles.fast]
model = "lora/fast"

[profiles.yolo]
mode = "autopilot"

[permissions]

Not allowed in project files.

Key	Type	Default	Meaning
allow	array of strings	[]	Rules that allow calls without asking
deny	array of strings	[]	Rules that block calls. Checked first, enforced in every mode.

A rule is a tool-name glob, optionally followed by a glob in parentheses matched against the tool’s key: each command segment for bash, the path for write and edit, the host for web_fetch, action:key for malac_configure. See Permissions and autopilot.

[permissions]
allow = ["bash(cargo *)", "bash(git status*)", "browser_*", "web_fetch(*.rust-lang.org)"]
deny = ["bash(rm -rf /*)", "bash(git push --force*)"]

[mcp.<name>]

Not allowed in project files.

Key	Type	Default	Meaning
command	string	none	Program to start for a stdio server
args	array of strings	[]	Its arguments
env	table	{}	Extra environment variables
url	string	none	http(s):// for streamable HTTP, ws(s):// for WebSocket
headers	table	{}	Extra HTTP headers
token_env	string	none	Variable whose value is sent as a bearer token
enabled	bool	true	Connect to this server
prefix	bool	true	Expose tools as <name>__<tool>

${VAR} is expanded in command, args, env and headers. See MCP servers.

[control]

The computer and browser control service. Not allowed in project files.

Key	Type	Default	Meaning
enabled	bool	true	Connect the control service
command	string	malac-control next to malac, else on PATH	Binary to spawn
url	string	none	Connect to a running service instead, for example ws://127.0.0.1:7878
token_env	string	none	Variable holding that service’s token

The service itself reads ~/.malac/control.toml; its keys are listed in Computer and browser control.

[memory]

Not allowed in project files.

Key	Type	Default	Meaning
enabled	bool	true	Memory tools and the memory index in the system prompt
auto_recall	bool	true	Attach vector matches to each prompt
recall_limit	integer	5	Matches considered per prompt

[memory.vector]

A Milvus or Zilliz Cloud collection. Vector search is on when both [memory.vector] and [memory.embeddings] are set.

Key	Type	Default	Meaning
url	string	"http://localhost:19530"	Milvus endpoint, or a Zilliz Cloud endpoint
token_env	string	none	Variable with user:password or an API key
database	string	Milvus default	Database name
collection	string	"malac_memory"	Collection name; created on first use

[memory.embeddings]

Key	Type	Default	Meaning
provider	string		Name of an OpenAI-compatible provider that serves /embeddings
model	string		Embedding model id

See Memory and Vector memory with Milvus.

[agents]

Key	Type	Default	Meaning
max_depth	integer	3	How deep subagents may nest; agents at the limit get no delegation tools
max_concurrent	integer	4	Subagents running at the same time

See Subagents.

[ui]

Key	Type	Default	Meaning
show_thinking	bool	false	Stream model reasoning in the terminal (same as -v)
tui	bool	true	Use the full-screen interface in a terminal; false keeps the line mode

[web]

Not allowed in project files.

Read by the daemon, which serves the web UI and its API, when it starts.

Key	Type	Default	Meaning
remote	bool	false	Listen on all interfaces instead of web.host. The token is still required.
host	string	"127.0.0.1"	Bind address when not remote
port	integer	7700	Port of the daemon and its web UI; any free port when it is taken

[daemon]

Not allowed in project files. Read when the daemon starts.

Key	Type	Default	Meaning
idle_minutes	integer	120	Exit after this long with no clients, running agents or jobs, or pending approvals; 0 never exits
browse_root	path	home directory	The web UI’s folder and file pickers list only what is below this (~/ allowed)

The daemon reads [daemon], [web], [update] and [control] from the user config only; each tab loads the full configuration for its own folder. See Workspaces, tabs and the daemon.

[update]

Not allowed in project files.

Key	Type	Default	Meaning
check	bool	true	Look for a newer release in the background, at most once a day
auto	bool	false	Install it automatically

See Updating.

Other files

Path	What it is
~/.malac/credentials.toml	Stored API keys, mode 0600
~/.malac/control.toml	Control service settings and browser profiles
~/.malac/sessions/*.jsonl	Session transcripts
~/.malac/memory/*.md, <project>/.malac/memory/*.md	Memories
~/.malac/agents/*.md, <project>/.malac/agents/*.md	Agent types
~/.malac/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md, and the same under <project>/.malac/ and <project>/.claude/	Skills
AGENTS.md, MALAC.md or CLAUDE.md	Instructions, read from ~/.malac/ and every directory from the project root down to the working directory (the first of the three found in each)
~/.malac/history.txt	Prompt history, shared by the terminal UI and the line mode
~/.malac/malac.log	Log output while the full-screen terminal UI is open
~/.malac/update.json	Cached update check
~/.malac/browser/<profile>/	Browser profile data
~/.malac/jobs/<id>.json, <id>.log	Background jobs and their output
~/.malac/workspaces/<id>.json, ~/.malac/state.json	Saved workspaces, and the last one used
~/.malac/daemon.json, daemon.token, daemon.lock, daemon.log	The running daemon’s address and token, its saved token, its lock and its log