Configuration

The CLI and terminal UI share one JSON configuration system. Use named profiles for different local servers and models instead of repeating environment variables.

Find or create configuration


truss-cli config path
truss-cli config init

On Windows, the user configuration file is %APPDATA%\truss-harness\config.json. Each workspace can also define .truss-harness/config.json.

config init creates a workspace template and refuses to overwrite an existing file.

Interactive setup


truss-cli setup

This guided user-level setup discovers reachable local endpoints and saves the selected server, model, mode, permission policy, and internet setting as the default profile.

Profile example


{
  "defaultProfile": "ollama-coder",
  "profiles": {
    "ollama-coder": {
      "provider": "ollama",
      "baseUrl": "http://127.0.0.1:11434",
      "model": "qwen3:8b",
      "mode": "edit",
      "permission": "ask",
      "internetAccess": false,
      "tuiTheme": "forest"
    },
    "lm-studio-fast": {
      "provider": "openai-compatible",
      "baseUrl": "http://127.0.0.1:1234/v1",
      "model": "local-model-id",
      "mode": "plan",
      "permission": "auto-read"
    }
  }
}

Fields

Field	Purpose
`provider`	`ollama` or `openai-compatible`
`baseUrl`	Local server base URL
`model`	Server model ID
`mode`	`chat`, `plan`, or `edit`
`permission`	`ask`, `auto-read`, or `auto-all`
`internetAccess`	Enables optional public web search and page fetching; defaults to `false`
`systemPrompt`	Optional system instruction
`apiKeyEnv`	Name of an environment variable that contains a token
`mcpServers`	Named local stdio MCP server definitions
`tuiTheme`	Terminal UI palette: `forest` (default), `sage`, or `dusk`
`allowWorkspaceMcpServers`	User-level opt-in for MCP commands defined by a workspace

Keep tokens out of JSON files. Use apiKeyEnv to reference an environment variable instead.

MCP configuration

MCP servers can expose additional tools to Agent and Plan modes:


{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "enabled": true,
      "readOnly": true
    }
  }
}

User-level MCP definitions load normally. Workspace MCP definitions are ignored unless the user configuration sets "allowWorkspaceMcpServers": true, because opening a workspace must not silently authorize it to launch a local command. See MCP Servers for the complete schema, UI setup, mode rules, and security behavior.

Precedence

CLI flags
Selected workspace profile and workspace fields
Selected user profile and user fields
TRUSS_HARNESS_* environment variables
Detected local model and defaults

CLI flags include --profile, --provider, --base-url, --model, --mode, --permission, --internet-access, and --no-internet-access.

Set TRUSS_HARNESS_INTERNET_ACCESS=true to enable the same capability through the environment.

TRUSS_HARNESS_MCP_SERVERS accepts an mcpServers object encoded as JSON.

Set TRUSS_HARNESS_TUI_THEME=forest, sage, or dusk to override the terminal UI palette for one launch.