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:

session = await client.sessions.create(
    meta={"config.enable_low_refusal_mode": True}
)

Supported Overrides

Override Option	Description
config.enable_low_refusal_mode	Enables low-refusal mode (activates the refusal remover worker for unstructured agent responses).
config.enable_refusal_remover	Enables refusal remover processing for unstructured model responses.
config.debug	Enables verbose debug mode and diagnostic logging.
config.enable_fast_agent	Enables fast agent execution harness.
config.enable_builtin_sleep	Enables built-in sleep tool.
config.fast_model	Sets model name used for fast operations.
config.escalation_model	Sets model name used for escalation steps.

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/.