Configuration

Every value resolves in the same order. Nothing is hidden, and oasis-agent --show-config prints where each value came from.

Resolution order

command-line flag  >  environment variable  >  config file  >  default

--base-url has no default and is required. Pointing at a server is an explicit choice, so the agent errors cleanly rather than dialling a stale baked-in address.

# Print every resolved value and which layer supplied it
oasis-agent --show-config

Config files

Two locations, checked in this order. The project file wins.

Path	Scope
./.oasis/config.json	This project
~/.oasis/config.json	This user

Override the path entirely with --config <path>.

{
  "base_url": "http://10.0.0.1:8080",
  "model": "qwen",
  "thinking_profile": "coding",
  "modules": {
    "ethercat": true
  }
}

Config-file keys mirror the flag names in snake_case. An unknown key is a hard error, not a silent no-op. A typo fails at startup rather than producing a run that quietly ignored your setting.

Keys with no flag

Two keys exist only in the file. Both are written by first-run setup and both can be set by hand.

Key	Type	Meaning
context_window	number	The window a guided install configured on the model server. Written only if the server accepted it, so the file and the server agree
checks_only	boolean	You deferred inference at first run. It stops setup reopening on every launch. oasis-agent setup clears it when an endpoint arrives

context_window is a number, not a string. A value that is not a whole number is rejected rather than stored, because a window saved as "32768" would read back as nothing at all.

The settings menu

From the REPL:

/config              open the settings menu (↑↓ choose, ←→ change, ↵ edit)
/config <key> <val>  set one key without opening the menu

The menu writes to the same file and shows which layer currently supplies each value, so you can see when a flag or environment variable is overriding what you are editing.

Core settings

Flag	Environment variable	Default
--base-url	OASIS_BASE_URL	required
--model	OASIS_MODEL	qwen
--cwd	OASIS_CWD	current directory
--api-key	OASIS_API_KEY	none
--actor	OASIS_ACTOR	none
--mode	OASIS_MODE	manual
--thinking-profile	OASIS_THINKING_PROFILE	off. One of off, creative, coding
--mcp-config	OASIS_MCP_CONFIG	none
--context-window	OASIS_CONTEXT_WINDOW	probed from the endpoint, else the context_window key, else 120 000
--config	—	./.oasis/config.json, then ~/.oasis/config.json

Context and compaction

Flag	Default	Purpose
--context-window	Probed from the endpoint	Tokens the model can hold
--response-reserve	8 192	Tokens held back for the reply
--max-prompt-tokens	context-window − response-reserve	The compaction trigger
--no-probe	off	Skip the startup context probe. Implied when both window values are given explicitly

--no-probe removes a round trip from the cold-start path. Use it when you already know the window and are running one-shot jobs at volume.

How the window is resolved

The probe asks the endpoint what it is serving. llama.cpp answers at /props. ollama has no /props and is asked instead which context a loaded model was loaded under. With nothing loaded, which is the usual case at startup, the answer is ollama's default and is treated as an assumption rather than a reading.

A value you set explicitly always wins, whether by flag, environment variable or config file. The startup line says which of the two it is using and does not print the one it discarded.

--max-prompt-tokens defaults to the window less the response reserve, or to half the window where that subtraction would leave too little to send a prompt at all. That applies below roughly 16k.

Behaviour

Flag	Default	Effect
--plan	off	Start read-only. Shorthand for --mode plan
--skip-permissions	off	Approve every waivable request. Does not waive hard-stop tools
--no-memory	off	No Memory tool and no memory briefing
--vision-capable	off	Required for ViewImage to do anything
--cwd-hint	off	Name the working directory in the system prompt
--no-delegation-nudge	off	Suppress the hint to hand bulk reading to a subagent
--no-session	off	Do not save this conversation
--ethercat-acquire-bus <if>	none	Restrict EtherCAT acquisition to these interfaces. Repeatable

--cwd-hint changes the prompt

It is off by default because it alters the assembled prompt prefix. Without it the model is not told where it is working and will occasionally guess wrong. Turn it on if you see that happening; expect one cold prefill when you do.

Terminal

Flag	Environment variable	Effect
--no-color	NO_COLOR	Disable ANSI colour
--no-history	OASIS_AGENT_NO_HISTORY=1	Disable persistent input history
--no-diffs	—	Show file edits as plain results rather than inline diffs
--no-collapse	—	Show every tool result in full
--repl	—	Force the interactive REPL. Implied when no other mode is selected and stdin is a terminal

Config-file-only keys

These name a directory an operator sets once rather than something worth a flag on every run. Set them with /config <key> <value> or by editing the file.

Key	Points at
modules	Which capability packs are on, e.g. {"ethercat": true}
ethercat_catalogue	Vendor ESI XML, which turns an EtherCAT product code into a device name
checks_catalogue	Descriptor TOML layered over the built-in check catalogue by check id

See Capability Packs and Conformance Checks.

Update settings

These govern how the binary updates itself. See Installing & Updating.

Key	Default	Purpose
auto_update	true	Background auto-update, and the update check at startup. Set false to turn both off
release_host	Compiled in at build time	The release store versions are resolved from
grant_capabilities	true	Grant the EtherCAT capabilities during an install. Set false to keep the binary unprivileged

auto_update and grant_capabilities are durable settings rather than environment variables only, because opting out should be written once rather than remembered on every invocation. OASIS_DISABLE_AUTOUPDATER, OASIS_RELEASE_HOST and OASIS_NO_CAPABILITIES are the environment overrides, for CI and containers where writing a config file is awkward.

grant_capabilities on a shared host

Capabilities attach to the file, so a granted binary hands a raw socket to anyone who can execute it. Set grant_capabilities: false where that matters.

Version policy

Two file-only keys pin which versions an install may move to. They are operator-owned and cannot be set with /config. Edit the file.

Key	Purpose
minimum_version	Refuse to update to anything older than this
maximum_version	Refuse to update to anything newer than this

{ "minimum_version": "0.4.0", "maximum_version": "0.5.0" }

An update blocked by a bound says which bound blocked it.

An invalid bound is ignored, not enforced

A value that is not a version is dropped rather than applied. The failure mode of a wrongly enforced bound (every install in a fleet frozen by one bad value) is worse than the failure mode of a missed one.

Paths

Path	Override with	Contents
~/.oasis	OASIS_ROOT	Installation root: config, sessions, versions, audit log
~/.local/bin	OASIS_INSTALL_DIR	The launcher
~/.oasis/sessions	—	Conversation history
~/.oasis/audit.jsonl	OASIS_AUDIT_FILE	The audit trail
~/.local/state/oasis-agent/memory/<project>	OASIS_MEMORY_DIR	Persistent per-project notes
~/.config/oasis-agent/mcp-tokens.json	OASIS_MCP_TOKEN_STORE	Cached MCP OAuth tokens

Full flag list

oasis-agent --help

--help prints every flag with its environment variable and default. A curated reference is at Command Reference.