Configuration Reference

Setting Your API Key

After installing the package, configure your API key:

sec-gemini set-key

This shows a welcome banner, prompts for your key, verifies it against the API, and saves it to config.toml. You can also pass the key directly:

sec-gemini set-key YOUR_API_KEY

Flag	Description
--force	Overwrite an existing key
--skip-verify	Save without verifying against the API

Once set, the TUI, BYOT client, and SDK all pick up the key automatically.

Environment Variables

Variable	Default	Description
SEC_GEMINI_API_KEY	–	API key (overrides config.toml for TUI, BYOT, and scripts)
SEC_GEMINI_CONFIG_DIR	~/.config/sec-gemini/	Override the config directory
SEC_GEMINI_API_HOST	production hub	Override the API Hub hostname (advanced/dev use)

The BYOT client resolves the API key in this order: --api-key flag, SEC_GEMINI_API_KEY env var, config.toml.

config.toml

All persistent configuration lives in ~/.config/sec-gemini/config.toml. The file is created automatically on first use with 0600 permissions.

# Authentication
api_key = "your-api-key"

# Auto-approve tool confirmations (default: false)
auto_confirm_tools = false

# Log verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL
log_level = "INFO"

# Max sessions shown in the TUI session list (1-500)
max_sessions_displayed = 50

# Optional: path to a directory of skill files to auto-load
# skills_directory = "/path/to/my/skills"

# Base tools (file operations, shell, network) used by BYOT
[baseline_tools]
enabled = true
# Disable specific tools by name (new tools are enabled by default)
disabled_tools = []
# Example: disabled_tools = ["bash", "remove_file"]

# Display preferences (TUI)
[display]
theme = "dark"           # "dark" or "light"
font_size = 14            # 8-32
terminal_colors = true
show_timestamps = true
compact_mode = false

# Register persistent MCP servers
# [[mcp_servers]]
# name = "my-mcp"
# uri = "https://my-mcp-server.example.com/sse"
# enabled_by_default = true

# Register local tool servers (FastMCP .py files)
# [[local_tools]]
# name = "my-tools"
# path = "/path/to/my_tools.py"
# enabled_by_default = true

Config CLI Commands

The TUI provides commands for managing config from the terminal:

# Show current configuration
sec-gemini config show

# Set a value (dotted keys for nested fields)
sec-gemini config set api_key "your-key"
sec-gemini config set display.theme "light"
sec-gemini config set log_level "DEBUG"

# Reset to defaults
sec-gemini config reset

Session Configuration Overrides (--meta)

Runtime behavior for individual sessions can be customized using session metadata overrides via the --meta flag in the CLI/TUI or via the meta parameter in the Python SDK.

# Enable low-refusal mode via CLI
sec-gemini --meta config.enable_low_refusal_mode=true

Or via the Python SDK (overrides are passed with the prompt and persist for the rest of the session):

session = await client.sessions.create()
await session.prompt(
    "Analyze the attached sample",
    meta={"config.enable_low_refusal_mode": "true"},
)

Supported Overrides

Override Option	Description
config.enable_low_refusal_mode	Enables low-refusal mode (alias for config.enable_refusal_remover).
config.enable_refusal_remover	Enables refusal remover processing and defensive security framing (enabled by default).
config.debug	Enables verbose debug mode and diagnostic logging.
config.allow_secgemini_fast_switch	Allows preplanner to switch to secgemini-fast harness for simple queries.
config.enable_builtin_sleep	Enables built-in sleep tool (enabled by default; supports inline sleep up to 5m and cold-sleep suspension up to 7 days).
config.max_session_duration_seconds	Sets hard deadline for total session wall-clock duration in seconds (default 604800 / 7 days).
config.model	Shortcut that sets config.fast_model, config.escalation_model, and config.refusal_retry_model at once. Per-role keys passed alongside it win.
config.fast_model	Sets model name used for fast operations (main agent).
config.escalation_model	Sets model name used for escalation steps (review, self-reflection).
config.refusal_retry_model	Sets model name used to retry a request after a policy refusal (default gemini-3.1-pro-preview).

Model Selection

The CLI exposes --model, --fast-model, and --escalation-model as dedicated flags for the corresponding overrides (config.refusal_retry_model is --meta only); they take precedence over equivalent --meta items, and the TUI offers the same choice in the Model dropdown of the New Session screen:

# Every agent role on one model
sec-gemini --model gemini-3.8-flash-cyber -p "Triage this sample"

# Mix models per role
sec-gemini --fast-model gemini-3.8-flash-cyber --escalation-model gemini-3.1-pro-preview

Model availability depends on the deployment you talk to: gemini-3.8-flash-cyber (Gemini 3.8 Flash post-trained for cybersecurity) is only served on allowlisted internal deployments, and a request for an unavailable model fails with a 404 from the model backend. Whenever a cyber model is in use, Sec-Gemini automatically enforces the default-deny-internet-access security policy (blocking outbound HTTP/network access, web search, browser navigation, and live network probing while preserving offline PCAP analysis) and disables external sandbox connectivity.

Log Files

Logs are written to ~/.config/sec-gemini/logs/ in JSON format with automatic rotation.

File	Source
ui.log	TUI
byot.log	BYOT client
mcp.log	MCP server

Stream recordings are saved as JSONL files under ~/.config/sec-gemini/runs/.