Configuration

Configuration

Every malac configuration key, with its type, default and meaning.

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.

Warning

Project files are restricted A project file cannot set mode, providers, mcp, control, permissions, memory, web, update, daemon, remote 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
cwd	string	malac's	Working directory of a command server
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. Enabled plugins add their servers here as <plugin> or <plugin>-<server>; a server you configure under the same name wins. 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.

[context]

What a session knows about its project before the first prompt. See Project context.

Key	Type	Default	Meaning
instruction_files	array of strings	[]	More instruction files, after the standard ones: relative to the project root, or absolute or ~/… in the user config. A project config may name only files inside the project.
max_instruction_chars	integer	40000	Characters of instruction files in the system prompt, all together
docs	bool	true	List the project's Markdown docs (path, title, first sentence) in the prompt
index	bool	true	Keep .malac/index.md, the project index, in a repository
index_max_files	integer	5000	Files whose symbols the index lists
knowledge	bool	true	Include .malac/MALAC.md, the project knowledge malac keeps

[plugins]

Key	Type	Default	Meaning
enabled	bool	true	Load installed and enabled plugins
defaults	bool	true	Enable the plugins that ship with malac: ponytail, as ponytail@malac

Marketplaces and enabled plugins are not set here but in ~/.malac/plugins/plugins.toml and <project>/.malac/plugins.toml. See Plugins and marketplaces.

[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	Remote access: paired devices on other machines and through tunnels may connect (same as --remote). Off, only local requests get in.
host	string	"127.0.0.1", or "0.0.0.0" with remote	Bind address. 127.0.0.1 with remote = true allows tunnels and SSH but keeps the daemon off the network.
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)
keep_awake	string	"busy"	Keep the machine from sleeping: "busy" while agents or jobs run (released a minute after), "always" while the daemon runs, "off". See Keeping the machine awake.

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

[remote]

Not allowed in project files. How other devices reach the daemon when web.remote allows them. See Remote access.

Key	Type	Default	Meaning
tunnel	string	none	Start this tunnel with the daemon and stop it with it: "cloudflare", "ngrok", "tailscale" (your tailnet) or "tailscale-funnel" (public)
public_url	string	none	An address in front of the daemon, such as a reverse proxy with TLS (https://malac.example.com); offered first in pairing links after a running tunnel

[web]
remote = true
host = "127.0.0.1"   # tunnels and SSH only

[remote]
tunnel = "cloudflare"

[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
<project>/.malac/MALAC.md	Project knowledge, listed from the project memories; commit it
<project>/.malac/index.md, index.cache.json	The project index; regenerable, kept out of git by .malac/.gitignore
AGENTS.md, CLAUDE.md, GEMINI.md, …	Instruction files, read from ~/.malac/ and every directory from the repository root down to the working directory
~/.malac/agents/*.md, <project>/.malac/agents/*.md	Agent types
…/skills/<name>/SKILL.md under ~/.malac/, ~/.claude/, ~/.agents/ and the same in the project	Skills
…/commands/*.md under ~/.malac/, ~/.claude/ and the project; …/commands/*.toml under ~/.gemini/ and the project	Slash commands
~/.malac/plugins/, <project>/.malac/plugins.toml	Plugins: your marketplaces, installed plugins and approvals; the team's plugins
~/.malac/devices.json, ~/.malac/connections.json	Devices paired with this daemon, and saved connections to daemons elsewhere (Remote access)
~/.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