Configuration

The CLI and terminal UI share one JSON configuration system. Use named profiles for different local servers, cloud providers, 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 can discover a local endpoint or create a cloud BYOK profile. Cloud setup saves the provider, model, and key environment-variable name only; it never saves the key itself.

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

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

Master prompt templates

Use masterPrompt when every run in a profile should begin with the same project rules. The template is plain text, so XML tags remain exactly as you wrote them. Only the documented {{variable}} tokens are substituted.

{
  "profiles": {
    "project-agent": {
      "provider": "openrouter",
      "model": "openai/gpt-4.1-mini",
      "mode": "edit",
      "masterPrompt": {
        "enabled": true,
        "template": "<project_rules>\nWork in {{agent.mode}} mode inside {{workspace.name}}.\nBranch: {{repository.branch}}\nChanged files:\n{{repository.changedFiles}}\n</project_rules>"
      }
    }
  }
}

Dynamic values are XML-escaped before insertion. Unknown or incomplete tokens, an empty enabled template, and oversized templates produce a visible validation error before Truss sends a model request. Templates cannot read API keys, environment variables, file contents, chat history, terminal output, or pairing data, and cannot override Truss tool permissions or mode safety.

Desktop and VS Code expose this editor in Settings. CLI profiles use the JSON setting above; for one launch, set TRUSS_HARNESS_MASTER_PROMPT. The older TRUSS_HARNESS_SYSTEM_PROMPT environment variable remains supported as a plain template for compatibility.

Bring your own key (BYOK)

The API-key cloud-provider rollout supports openai, anthropic, openrouter, groq, together, gemini, xai, mistral, deepseek, perplexity, fireworks, nvidia-nim, xiaomi-mimo, sakana-fugu, and ollama-cloud. Each has a documented default endpoint, so a cloud profile only needs a provider and model:

{
  "profiles": {
    "groq": {
      "provider": "groq",
      "model": "your-tool-capable-model",
      "mode": "edit",
      "permission": "ask"
    }
  }
}

Set the key outside JSON using the matching provider variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY, GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, FIREWORKS_API_KEY, NVIDIA_API_KEY, MIMO_API_KEY, SAKANA_API_KEY, or OLLAMA_API_KEY. TRUSS_HARNESS_API_KEY and a profile’s apiKeyEnv remain available when a custom environment-variable name is required.

xiaomi-mimo and sakana-fugu use OpenAI-compatible chat-completions endpoints. Sakana Fugu uses https://api.sakana.ai/v1 with SAKANA_API_KEY; choose fugu-ultra as the model when using a Fugu Ultra account. ollama-cloud uses Ollama’s native hosted API and requires OLLAMA_API_KEY; it is separate from local ollama, which continues to use http://127.0.0.1:11434 without a key.

In VS Code, use Truss: Configure BYOK Provider from the Command Palette instead. Its key is held in VS Code Secret Storage rather than workspace state.

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

1. CLI flags
2. Selected workspace profile and workspace fields
3. Selected user profile and user fields
4. TRUSS_HARNESS_* environment variables
5. 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.