Configuration

You can configure OpenSploit using a JSON config file.

Format

OpenSploit supports both JSON and JSONC (JSON with Comments) formats.

{
  "$schema": "https://opensploit.ai/config.json",
  "theme": "default",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Locations

Configuration files are merged together. Settings from all config locations are combined, where later configs override earlier ones for conflicting keys.

| Priority | Location | Use Case | |----------|----------|----------| | 1 | Remote config | Organization defaults | | 2 | Global config | Personal preferences | | 3 | Custom path | CI/CD, automation | | 4 | Project config | Project-specific settings | | 5 | .opensploit directory | Team-shared settings | | 6 | Inline config | Ephemeral overrides |

Global

Place your global config in ~/.config/opensploit/opensploit.json. Use this for themes, providers, or keybinds.

Per Project

Add an opensploit.json in your project root. This is useful for project-specific settings like target scopes or tool restrictions.

Custom Path

Specify a custom config file using the OPENSPLOIT_CONFIG environment variable:

export OPENSPLOIT_CONFIG=/path/to/custom-config.json
opensploit

Inline Config

Pass config content directly via environment variable:

OPENSPLOIT_CONFIG_CONTENT='{"model":"ollama/llama3.1"}' opensploit

Schema Reference

TUI

Configure the terminal user interface behavior:

{
  "tui": {
    "scroll_speed": 2,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | scroll_speed | 1-3 | 2 | Scroll speed multiplier | | scroll_acceleration.enabled | boolean | true | macOS-style smooth scrolling |

Server

Configure the HTTP server for headless operation:

{
  "server": {
    "port": 9321,
    "hostname": "127.0.0.1",
    "mdns": false,
    "cors": []
  }
}

Model

Configure the LLM model to use:

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

The small_model is used for lightweight tasks like title generation and session summarization.

Provider

Configure LLM provider settings:

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Tools

Enable or disable specific security tools:

{
  "tools": {
    "nmap": true,
    "sqlmap": true,
    "metasploit": false
  }
}

Themes

Set your preferred visual theme:

{
  "theme": "default"
}

See the Themes page for available options.

Agents

Define custom specialized agents:

{
  "agents": {
    "recon-only": {
      "description": "Reconnaissance phase agent",
      "tools": {
        "nmap": true,
        "ffuf": true,
        "metasploit": false
      },
      "prompt": "Focus only on reconnaissance. Do not attempt exploitation."
    }
  }
}

Sharing

Control session sharing behavior:

{
  "sharing": {
    "mode": "manual"
  }
}

| Mode | Description | |------|-------------| | manual | Share only when explicitly requested | | auto | Automatically share sessions | | disabled | Disable sharing entirely |

Commands

Define reusable command templates:

{
  "commands": {
    "quick-scan": {
      "prompt": "Run a quick port scan on the target",
      "description": "Fast initial reconnaissance"
    }
  }
}

Keybinds

Customize keyboard shortcuts:

{
  "keybinds": {
    "submit": ["enter"],
    "newline": ["shift+enter"],
    "cancel": ["escape", "ctrl+c"]
  }
}

Permissions

Configure approval requirements for different actions:

{
  "permission": {
    "exploit": "ask",
    "scan_external": "ask",
    "bash": {
      "command:*": "ask"
    }
  }
}

| Value | Behavior | |-------|----------| | allow | Execute without confirmation | | ask | Prompt for approval | | deny | Block the action |

MCP Servers

Configure Model Context Protocol servers:

{
  "mcp": {
    "servers": {
      "custom-tool": {
        "command": "docker",
        "args": ["run", "-i", "my-custom-tool"],
        "env": {}
      }
    }
  }
}

Instructions

Reference external rule files:

{
  "instructions": {
    "rules": [
      ".opensploit/rules.md",
      "AGENTS.md"
    ]
  }
}

Autoupdate

Control automatic updates:

{
  "autoupdate": true
}

| Value | Behavior | |-------|----------| | true | Auto-install updates | | "notify" | Notify but don't install | | false | Disable update checks |

Variables

Environment Variables

Use {env:VARIABLE_NAME} to substitute environment variables:

{
  "model": "{env:OPENSPLOIT_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

File Contents

Use {file:path/to/file} to substitute file contents:

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | OPENSPLOIT_CONFIG | Custom config file path | | OPENSPLOIT_CONFIG_CONTENT | Inline config JSON | | OPENSPLOIT_DISABLE_AUTOUPDATE | Disable update checks | | OPENSPLOIT_ENABLE_EXPERIMENTAL | Enable experimental features |