OptiQ CLI · Configuration

Configuration

OptiQ has one list of settings, and you can set each one in a config file or with one environment variable. You rarely need any of them: with nothing set, optiq code finds or starts a local model and optiq serve measures what your Mac can hold.

Where settings go

The first source that sets a value wins:

flag > environment > repo config > saved values > user config > default

~/.optiq/config.yaml is your user config, and applies everywhere.
<repo>/.optiq/config.yaml is a repo config, checked in and shared by the team.
~/.optiq/state.json holds saved values OptiQ writes itself: your optiq cloud login token and the hosts you approve for the sandbox. You do not need to edit it.
Every setting has one variable: its name in capitals after OPTIQ_, so max_turns is OPTIQ_MAX_TURNS.

A misspelled setting or an OPTIQ_ variable OptiQ does not know gets a warning, because a typo that silently does nothing is worse. To see every value and where it came from:

terminalbash

$ optiq config

Example files

Each file holds only what it changes. A repo file can set its own base_url, but your api_key is not sent to it.

A local model on your Mac

local-mac.yamlyaml

# ~/.optiq/config.yaml: OptiQ Code on your own Mac, with a local model.
model: mlx-community/Qwen3.5-9B-OptiQ-4bit   # what `optiq code` serves when nothing is running
server_port: 8080                            # change it to run two instances side by side
reasoning_effort: high

# Ask before bash, but let edits through.
gated_tools: bash

# Turn off the terminal bell and the mouse capture.
notify: false
mouse: false

A hosted endpoint

cloud-endpoint.yamlyaml

# ~/.optiq/config.yaml: OptiQ Code against a hosted OpenAI-compatible endpoint.
base_url: https://openrouter.ai/api/v1
api_key: sk-or-v1-your-key                   # or leave it out and export OPTIQ_API_KEY
model: qwen/qwen3.5-397b-a17b
context_window: 131072                       # a hosted endpoint does not report one

# Sent as-is in the body of every chat request.
request_extra:
  provider:
    sort: throughput

Unattended, on CI

ci.yamlyaml

# ~/.optiq/config.yaml on a CI runner: nobody is there to approve anything.
base_url: https://cloud.mlx-optiq.com/api/v1
model: glm-5.3-flash                         # export OPTIQ_API_KEY from a CI secret
auto_approve: true
sandbox: true
wall_clock: 3600                             # stop after an hour
finish_gate: true                            # hand back a tree that does not build
disable_tools: web_search,web_fetch
color: false

Shared by a team

team-repo.yamlyaml

# <repo>/.optiq/config.yaml: checked in, so it applies to everyone on the team.
# A repo file cannot set cloud_url, cloud_api_key or the sandbox's exceptions,
# and your own api_key is not sent to a base_url set here.
after_edit_hook: ruff check .                # its output goes back to the agent
auto_verify: syntax                          # or full, to run the whole test suite
gated_tools: write_file,edit_file,bash
max_tool_output: 16000

OptiQ Code settings

Endpoint and model

Setting and variable	Default	What it does
`base_url` `OPTIQ_BASE_URL`	unset	OpenAI-compatible endpoint OptiQ Code talks to. Unset: it finds a local server, or starts one.
`api_key` `OPTIQ_API_KEY`	unset	Bearer token for that endpoint. `optiq serve` and the Lab also read `OPTIQ_API_KEY` as the key a client must send. Default for a local server: sk-optiq-local.
`model` `OPTIQ_MODEL`	unset	Which served model to use. Default: whatever the server serves.
`context_window` `OPTIQ_CONTEXT_WINDOW`	unset	The model's context window in tokens. `optiq serve` reports it; set it for any other endpoint so compaction has a budget.
`request_timeout` `OPTIQ_REQUEST_TIMEOUT`	`1200.0`	Seconds to wait for one model response. A big model on a small Mac can take many minutes to read a long prompt.
`max_retries` `OPTIQ_MAX_RETRIES`	`3`	Retries for a request that errors or times out. The worst case is (max_retries + 1) x request_timeout.
`request_extra` `OPTIQ_REQUEST_EXTRA`	unset	Mapping merged into the body of every chat request, for options the OpenAI API has no field for, such as OpenRouter provider routing.
`server_port` `OPTIQ_SERVER_PORT`	`8080`	Port for a server OptiQ Code spawns itself. Ignored when base_url is set. Change it to run two instances side by side.

Sampling and limits

Setting and variable	Default	What it does
`temperature` `OPTIQ_TEMPERATURE`	unset	Sampling temperature for the endpoint you configure. Unset: an OptiQ server uses the model's own (its generation_config.json), any other endpoint 0.6. Boost ignores it: OptiQ Cloud sets Boost's sampling.
`top_p` `OPTIQ_TOP_P`	unset	Nucleus sampling for the endpoint you configure. Unset: the model's own on an OptiQ server, 0.95 anywhere else. Boost ignores it.
`reasoning_effort` `OPTIQ_REASONING_EFFORT`	unset	Reasoning effort for thinking models (low \| medium \| high).
`replay_reasoning` `OPTIQ_REPLAY_REASONING`	`auto`	Send each assistant turn's thinking back on later requests. `auto` does it only for an OptiQ server, whose prompt cache depends on it. `on` or `off` to force.
`max_tokens` `OPTIQ_MAX_TOKENS`	`16384`	Token cap per model response. It also caps a single edit, and thinking models spend thousands before answering, so keep it generous.
`max_turns` `OPTIQ_MAX_TURNS`	`1000`	Tool-calling turns before the agent stops. A safety net, not a budget: a stuck run is stopped by the stall ladder and time by `wall_clock`.
`wall_clock` `OPTIQ_WALL_CLOCK`	unset	Seconds before the agent stops, regardless of turns. Default: none.
`compact_at` `OPTIQ_COMPACT_AT`	unset	Token count at which old tool output is compacted out of the conversation. Default: 80% of whichever is smaller, the server's context window or what it can still cache.
`max_tool_output` `OPTIQ_MAX_TOOL_OUTPUT`	unset	Bytes of a single tool result kept before truncation.

OptiQ Cloud and Boost

Setting and variable	Default	What it does
`cloud_url` `OPTIQ_CLOUD_URL`	`https://cloud.mlx-optiq.com`	OptiQ Cloud endpoint used for Boost. User config or environment only: a repo file cannot set it.
`cloud_api_key` `OPTIQ_CLOUD_API_KEY`	unset	OptiQ Cloud token, written by `optiq cloud login`. User config or environment only: a repo file cannot set it.
`boost_mode` `OPTIQ_BOOST_MODE`	`off`	off: your local model runs the task. lead: the OptiQ Cloud model leads the task and your local model is its `local` tool, billed per token in dollars against your OptiQ Cloud balance. Needs `optiq cloud login`. Default: off.
`boost_model` `OPTIQ_BOOST_MODEL`	unset	Which OptiQ Cloud model Boost runs on, e.g. glm-5.3-flash or deepseek-v4.1-flash (`/boost <model>` picks one for a session). Unset: OptiQ Cloud's own choice for Boost.

The local tool

Setting and variable	Default	What it does
`local_tool_base_url` `OPTIQ_LOCAL_TOOL_BASE_URL`	unset	OpenAI-compatible endpoint of a cheaper worker model behind the `local` tool, which runs bulky work in a fresh context and returns a short answer. Needs local_tool_model.
`local_tool_model` `OPTIQ_LOCAL_TOOL_MODEL`	unset	Model name the `local` tool's worker asks its endpoint for. Required together with local_tool_base_url.
`local_tool_api_key` `OPTIQ_LOCAL_TOOL_API_KEY`	unset	Bearer token for local_tool_base_url. Never falls back to api_key, so the main endpoint's key is not sent to a second server. Default: sk-optiq-local.

Approvals and sandbox

Setting and variable	Default	What it does
`auto_approve` `OPTIQ_AUTO_APPROVE`	`false`	Run tool calls without asking. `-y` sets it for one launch. Use it for anything unattended, which has nobody to answer a prompt.
`gated_tools` `OPTIQ_GATED_TOOLS`	`write_file,edit_file,bash`	Comma-separated tools that require approval when auto_approve is off. Narrow it to keep the useful middle ground — 'bash' alone lets edits through while still asking before anything runs a command.
`disable_tools` `OPTIQ_DISABLE_TOOLS`	unset	Comma-separated tools to withhold, e.g. `web_search,web_fetch`. They are hidden from the model and refused if it names one anyway.
`sandbox` `OPTIQ_SANDBOX`	`false`	Run bash and run_tests in the OS sandbox: writes only to the repo, temp and package caches, credential files unreadable, and the network limited to package registries and git hosts.
`sandbox_allow_domains` `OPTIQ_SANDBOX_ALLOW_DOMAINS`	unset	Extra hosts the sandbox may reach, on top of the built-in registries and git hosts. Comma-separated; *.example.com matches subdomains. User config or environment only: a repo file cannot widen it.
`sandbox_exclude` `OPTIQ_SANDBOX_EXCLUDE`	unset	Commands that always run outside the sandbox, as shell-style patterns (e.g. 'docker *'). They still need approval. User config or environment only: a repo file cannot set it.

Checks and the terminal

Setting and variable	Default	What it does
`auto_verify` `OPTIQ_AUTO_VERIFY`	`syntax`	What runs on its own after a turn that changed code. `syntax` checks the edited files and builds the project where it can; `full` runs the whole test suite; `off` leaves it to the model.
`after_edit_hook` `OPTIQ_AFTER_EDIT_HOOK`	unset	A shell command run in the repo after every turn that changed code, with its output handed to the agent, such as `ruff check .`. Empty: none.
`finish_gate` `OPTIQ_FINISH_GATE`	`false`	Headless only. When the agent finishes with code changed, build the whole tree first. A tree that does not build is handed back with the errors.
`skills` `OPTIQ_SKILLS`	`true`	Read Agent Skills (folders with a SKILL.md) from .agents/skills and .claude/skills in the project and in your home directory: their names and descriptions go in the system prompt, and the agent loads one with the `skill` tool or you run it with /<name>.
`trace_tags` `OPTIQ_TRACE_TAGS`	unset	Mapping merged into every exported trace header, such as a benchmark's instance id.
`notify` `OPTIQ_NOTIFY`	`true`	TUI only. When a run finishes, or needs your approval, while the terminal is not focused, ring the bell and send a desktop notification (OSC 9: iTerm2, Ghostty, WezTerm, Windows Terminal), so the dock or tab shows it. Needs a terminal that reports focus.
`idle_compact_secs` `OPTIQ_IDLE_COMPACT_SECS`	`60`	TUI only. After this many idle seconds, if the conversation is within 85% of the compaction threshold, compact it and have the server re-read it then, while you are away, instead of on your next message. A compaction rewrites the prefix, so the re-read costs minutes on a local server. 0 turns it off.
`color` `OPTIQ_COLOR`	`true`	ANSI color in output.
`mouse` `OPTIQ_MOUSE`	`true`	Capture the mouse in the TUI. On by default: the wheel scrolls the transcript, and dragging selects text inside OptiQ Code, which is copied to the clipboard when you let go. Set false (or type /mouse) to leave the mouse to the terminal for its own selection; PageUp/PageDown or Ctrl-U/D then scroll.

Serving, quantizing and training settings

These reach further down. Most are for measuring something, or for working around a tight machine.

Setting and variable	Default	What it does
`home` `OPTIQ_HOME`	`~/.optiq`	Root for OptiQ state on disk. Defaults to ~/.optiq. Environment only (OPTIQ_HOME): a config file cannot set it, because the config file itself lives here.
`output_dir` `OPTIQ_OUTPUT_DIR`	`optiq_output`	Where `optiq convert` and `optiq kv-cache` write when no output path is given, and where the Lab lists local quants. Relative paths are taken from the working directory.
`sandbox_container` `OPTIQ_SANDBOX_CONTAINER`	unset	Container runtime for the code sandbox. A CLI name forces that runtime; 0/off disables the container tier.
`sandbox_python_image` `OPTIQ_SANDBOX_PYTHON_IMAGE`	`python:3.11-slim`	Container image for the python tool. The default is stdlib only; use an image with numpy/pandas/matplotlib if you want those.
`sandbox_shell_image` `OPTIQ_SANDBOX_SHELL_IMAGE`	`alpine:3.20`	Container image for the terminal tool.
`lab_boot_timeout` `OPTIQ_LAB_BOOT_TIMEOUT`	`900`	Seconds to wait for a model server to come up.
`cluster_cwd` `OPTIQ_CLUSTER_CWD`	unset	Working directory for cluster workers.
`cluster_headroom_gb` `OPTIQ_CLUSTER_HEADROOM_GB`	`2`	RAM left free per node when placing shards, in GB. A comma-separated list sets it per rank, as in "1.2,0.2".
`stream_lookahead` `OPTIQ_STREAM_LOOKAHEAD`	unset	Lookahead expert prefetch depth: run the next MoE layer's router early and read its top-N experts ahead of time. Unset means the measured per-model default (off for unmeasured models); 0 is off.
`stream_reference` `OPTIQ_STREAM_REFERENCE`	unset	Force streaming of the reference model on or off. Unset means auto, decided by whether it fits in RAM.
`flash_attn` `OPTIQ_FLASH_ATTN`	`auto`	Attention backward: auto, always or never.
`flash_attn_budget_gb` `OPTIQ_FLASH_ATTN_BUDGET_GB`	unset	Memory budget that routes stock vs tiled backward.
`flash_block` `OPTIQ_FLASH_BLOCK`	`128`	Query-block size for the tiled FlashAttention backward.
`fused_ce` `OPTIQ_FUSED_CE`	unset	Force fused cut-cross-entropy on or off. Unset means auto, gated on the size of the logit tensor.
`fused_dpo` `OPTIQ_FUSED_DPO`	`false`	Fused cross-entropy for DPO.
`no_think` `OPTIQ_NO_THINK`	`false`	Disable thinking blocks for models that support a toggle, on every chat endpoint including the Anthropic-compatible one.
`low_bit_search` `OPTIQ_LOW_BIT_SEARCH`	`true`	Pick each group's range by search when quantizing. Off reproduces a pre-0.4.14 artifact exactly.
`adapter_cache` `OPTIQ_ADAPTER_CACHE`	unset	Where `optiq serve --adapter <hf-repo>` caches remote adapters. Defaults to ~/.cache/optiq/adapters ($OPTIQ_HOME/cache/adapters when OPTIQ_HOME is set).
`kernels` `OPTIQ_KERNELS`	`true`	Custom Metal kernels on the models they are tested for. Off falls back to stock attention everywhere.
`batch_hybrid` `OPTIQ_BATCH_HYBRID`	`false`	Let `optiq serve` batch requests on hybrid-attention models. Off by default: their cache cannot be trimmed, so batching loses prompt-cache reuse across turns.
`on_generation_death` `OPTIQ_ON_GENERATION_DEATH`	`restart`	What `optiq serve` does when its generation loop dies: restart (re-exec the same command) or exit (status 3, for a supervisor).
`prefill_step` `OPTIQ_PREFILL_STEP`	`512`	Prompt tokens per prefill chunk in the OptiQ engine. Smaller chunks bound the attention transient on a tight machine.
`dump_requests` `OPTIQ_DUMP_REQUESTS`	unset	Directory to write every request body to, for seeing what a client actually sends. Off unless set.

Upgrading from 0.7 or earlier? The first run moves ~/.optiq/config.json and ~/.optiq/code/config.json into these files and keeps the originals as .bak, so you stay logged in. Move a repo's .optiq/code.json or .optiq/optiq.json to .optiq/config.yaml yourself. OPTIQ_CODE_MAX_TURNS and the other OPTIQ_CODE_ variables are now OPTIQ_MAX_TURNS and so on.