Configuration

Config File

Armament uses ~/.armament/config.json (JSON format). Here’s a complete reference of all supported settings:

{
  "providers": [
    {
      "type": "anthropic",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "models": [
        { "name": "claude-sonnet-4-20250514", "inputPrice": 3, "outputPrice": 15 },
        { "name": "claude-opus-4-20250514", "inputPrice": 15, "outputPrice": 75 }
      ]
    },
    {
      "type": "openai",
      "apiKey": "${OPENAI_API_KEY}",
      "models": [
        { "name": "gpt-4o", "inputPrice": 2.5, "outputPrice": 10, "cacheReadMultiplier": 0.5, "cacheWriteMultiplier": 0 }
      ]
    },
    {
      "type": "openai",
      "name": "deepseek",
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "models": [
        { "name": "deepseek-chat", "inputPrice": 0.5, "outputPrice": 2.19, "cacheReadMultiplier": 0.1, "cacheWriteMultiplier": 1.25 }
      ]
    }
  ],
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultProvider": "anthropic",
  "session": {
    "streaming": true,
    "autoSave": true,
    "promptCaching": true,
    "useThreads": true,
    "maxTurns": 100,
    "conversationTimeout": 30,
    "budget": 5.00
  },
  "context": {
    "maxTokens": 200000,
    "compactThreshold": 0.75,
    "recentMessages": 20,
    "maxSnapshots": 50,
    "autoCompact": true,
    "strategy": "llm"
  },
  "workspace": {
    "mode": "sandbox",
    "allowedPaths": [],
    "denyPaths": [],
    "gitAutoCommit": true,
    "fileWatcher": true,
    "maxFileSize": 10485760,
    "encoding": "utf-8"
  },
  "display": {
    "theme": "dark",
    "showThinking": true,
    "showToolCalls": true,
    "compact": false,
    "verbose": false,
    "timestamps": true,
    "syntaxHighlighting": true,
    "maxOutputLines": 500,
    "fontSize": 13,
    "fontFamily": "monospace",
    "fontWeight": "normal",
    "renderInterval": 50
  }
}

Configuration Sections

Session

Controls agent behavior and costs:

Field	Type	Default	Description
`streaming`	boolean	true	Stream responses token-by-token
`autoSave`	boolean	true	Auto-save session state
`promptCaching`	boolean	true	Enable prompt caching
`useThreads`	boolean	true	Enable thread-based execution
`maxTurns`	number	100	Max turns per agent before forced summary
`conversationTimeout`	number	30	Minutes of inactivity before timeout
`budget`	number	5.00	Session cost limit (USD). When exceeded, a warning fires in the active channel once per session.

Context

Controls how the agent manages its conversation history:

Field	Type	Default	Description
`maxTokens`	number	200000	Maximum context window size
`compactThreshold`	number	0.75	Fraction of maxTokens that triggers compaction (0-1)
`recentMessages`	number	20	Messages preserved verbatim after compaction
`maxSnapshots`	number	50	Max rewind snapshots stored
`autoCompact`	boolean	true	Auto-compact when threshold exceeded
`strategy`	string	”llm”	Compaction strategy: `llm` (summarize) or `truncate`

Workspace

Controls file system access for agents:

Field	Type	Default	Description
`mode`	string	”sandbox”	Access mode: `sandbox`, `restricted`, or `unrestricted`
`allowedPaths`	string[]	[]	Extra paths the agent can access (expands sandbox)
`denyPaths`	string[]	[]	Paths the agent cannot access
`gitAutoCommit`	boolean	true	Auto-commit agent file changes
`fileWatcher`	boolean	true	Watch workspace files for changes
`maxFileSize`	number	10485760	Max file size in bytes for agent read/write
`encoding`	string	”utf-8”	Default encoding for file operations

Display

Controls TUI appearance:

Field	Type	Default	Description
`theme`	string	”dark”	Color theme (`dark`, `light`, or custom theme name)
`showThinking`	boolean	true	Show reasoning/thinking chunks
`showToolCalls`	boolean	true	Show tool call details
`compact`	boolean	false	Compact mode (less padding, denser layout)
`verbose`	boolean	false	Verbose mode (show additional metadata)
`timestamps`	boolean	true	Show message timestamps
`syntaxHighlighting`	boolean	true	Enable syntax highlighting in output
`maxOutputLines`	number	500	Max lines per tool output before truncation
`fontSize`	number	13	Terminal font size
`fontFamily`	string	”monospace”	Font family
`fontWeight`	string	”normal”	Font weight (`normal`, `bold`, `light`)
`renderInterval`	number	50	UI render interval in ms

Provider Configuration

Each provider entry supports:

Field	Type	Description
`type`	string	Provider type: `anthropic`, `openai`, `bedrock`, `gemini`, `ollama`
`name`	string?	Optional display name (e.g., “deepseek” for an OpenAI-compatible endpoint)
`apiKey`	string	API key (supports `${ENV_VAR}` interpolation)
`baseUrl`	string?	Custom API endpoint (for proxies or self-hosted models)
`region`	string?	AWS region (bedrock only)
`streaming`	boolean?	Enable streaming (defaults to true)
`models`	object[]	Per-model pricing and configuration

Per-Model Pricing

Each model entry:

Field	Type	Default	Description
`name`	string	—	Model identifier (e.g., `claude-sonnet-4-20250514`)
`inputPrice`	number	3	Cost per million input tokens (USD)
`outputPrice`	number	15	Cost per million output tokens (USD)
`cacheReadMultiplier`	number	0.1	Cache read cost multiplier (Claude: 0.1, OpenAI: 0.5)
`cacheWriteMultiplier`	number	1.25	Cache write cost multiplier (Claude: 1.25, OpenAI: 0)

Default pricing is provided for Claude, GPT, and DeepSeek models, but custom entries override them.

Environment Variables

API keys support environment variable interpolation with ${VAR_NAME} syntax. Never hardcode secrets in config files.

Hot Reconfiguration

Most display and session settings can be changed live without restarting:

/config set display.theme ice
/config set session.budget 10

The session performs atomic reconfiguration — if the new config is invalid, it rolls back to the previous state.

MCP Server Configuration

Configure MCP servers to extend agent capabilities with external tools:

{
  "mcp": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

See MCP Servers for transport options, auth types, and full configuration reference.