Skip to content

Bring Your Own Tools (BYOT)

Bring Your Own Tools (BYOT) bridges your local machine to the Sec-Gemini cloud agent. The SDK includes a BYOT client (sec-gemini-byot) that establishes an outbound tunnel – no inbound ports, no firewall changes. Once connected, the agent can call tools on your machine as if they were cloud-native: reading files, running commands, scanning your network, and calling any custom MCP you plug in.

Before using BYOT, consider if these mitigations are appropriate:

  • Run inside a container, VM, or disposable instance. Isolate execution environments when running tools.
  • Run with standard unprivileged user accounts. Tools inherit the privileges of the active local user account.
  • Limit the tool surface. Use --tools to allow-list only specific tools, or use --no-base-tools with restricted custom MCP servers.
  • Keep tool confirmations enabled. Pausing for approval before executing tool calls provides full interactive control over local execution.
  • Treat skills as code. A skill loaded with --skills is a set of instructions the agent follows using the tools this client exposes. Only load skills you wrote or reviewed; never point --skills at a directory from an untrusted checkout. See Adding Your Own Skills.

For cloud-side security guarantees (data handling, encryption, logging suppression), see Architecture & Security.

To allow Sec-Gemini to access your filesystem and network (see the full tool list below), launch the BYOT client:

Terminal window
pip install sec-gemini
sec-gemini-byot

The client picks up your API key from config.toml (or the SEC_GEMINI_API_KEY env var), registers 35 base tools, and keeps running until you Ctrl+C.

To see what tools are available:

Terminal window
sec-gemini-byot --list-tools

To only enable specific tools:

Terminal window
sec-gemini-byot --tools dns_lookup ssl_check check_email_security

To disable the base tools entirely:

Terminal window
sec-gemini-byot --no-base-tools

To selectively disable specific tools via config, set disabled_tools in your ~/.config/sec-gemini/config.toml:

[baseline_tools]
enabled = true
disabled_tools = ["bash", "remove_file", "remove_directory"]

You can extend the agent with custom tools by writing an MCP server. The easiest way is with FastMCP – create a .py file:

my_tools.py
from fastmcp import FastMCP
mcp = FastMCP("my-security-tools")
@mcp.tool()
def lookup_hash(sha256: str) -> str:
"""Look up a file hash in the local threat intelligence database."""
return f"Hash {sha256[:16]}... analyzed"
@mcp.tool()
def scan_yara(file_path: str, rules_dir: str = "/opt/yara-rules") -> str:
"""Run YARA rules against a file."""
return f"Scanned {file_path} with rules from {rules_dir}"

Pass it to the BYOT client with --mcp:

Terminal window
sec-gemini-byot --mcp ./my_tools.py

You can pass multiple sources – .py files or URLs of already-running MCP servers:

Terminal window
sec-gemini-byot --mcp ./my_tools.py ./other_tools.py http://localhost:9000/sse

A skill is a markdown file with YAML frontmatter (name and description are required) that teaches the agent how to approach a task. The BYOT client can expose local skills to the agent with --skill / --skills (same flag, repeatable):

---
name: triage-phishing
description: Triage a suspected phishing email end to end
---
1. Extract URLs and attachments ...
Terminal window
# One skill
sec-gemini-byot --skill ./triage-phishing/SKILL.md
# A directory of skills: one SKILL.md per skill folder
sec-gemini-byot --skills ~/my-skills
Path What is loaded
./triage/SKILL.md or ./note.md That one file
./triage/ (a folder containing SKILL.md) Its SKILL.md; sibling files (references/*.md, scripts/) are supporting material and are not exposed
~/my-skills/ Every skill folder below it (a folder with a SKILL.md is a leaf: nothing under it, not even a template SKILL.md in resources/, becomes a skill); every other *.md file outside a skill folder is loaded as a skill too, except README.md

Loading is strict: a file without frontmatter (including a stray document such as CONTRIBUTING.md in a skills directory: move it, or point --skills at the skill folders), a missing name/description, a dangling symlink, an empty path, a directory that yields no skill, a name longer than 128 characters or containing control characters or any of , " < >, or two files declaring the same name (case-insensitive; -, _ and spaces are equivalent) abort startup with the offending path. Dot-prefixed entries (.git, .venv) are skipped. Symlinks are dereferenced, including targets outside the directory, so audit links (find DIR -type l) before loading a tree you did not write. The client prints one loaded skill '<name>' from <path> line per skill (<path> -> <target> when reached through a symlink), so you can see exactly what the agent received.

Only the skill body travels to the agent: files next to a SKILL.md (references/*.md, scripts/) are not exposed over BYOT, so inline what the agent needs or reference absolute paths it can open with the base file tools. Skills appear in the agent’s catalog by name and description and their body is fetched on demand; to have them in context from the first turn, load them with sec-gemini --skill PATH --force-load-skills instead (that flag belongs to the sec-gemini TUI/CLI, not to sec-gemini-byot).

Start the BYOT client programmatically instead of the CLI:

from sec_gemini.byot.service import ByotService
from sec_gemini.tools import load_baseline_mcps
baseline_tools = load_baseline_mcps()
byot = ByotService(api_key="YOUR_API_KEY", name="my-client")
await byot.start(tools=baseline_tools)
# Check status
status = byot.status() # .state, .tool_count, .tools
# Stop when done
await byot.stop()

To add custom tools programmatically:

from fastmcp import FastMCP
custom = FastMCP("custom-tools")
@custom.tool()
def my_tool(query: str) -> str:
"""My custom tool."""
return f"Result: {query}"
baseline_tools = load_baseline_mcps()
await byot.start(tools=baseline_tools + [custom])
sequenceDiagram
  participant Local as Your Machine
  participant Hub as BYOT Hub (Cloud)
  participant Agent as Gemini Agent

  Local->>Hub: Outbound gRPC stream (authenticated)
  Agent->>Hub: "Call tool X on user's machine"
  Hub->>Local: Forward tool request
  Local->>Local: Execute tool locally
  Local->>Hub: Return result
  Hub->>Agent: Forward result

The BYOT client establishes a persistent outbound gRPC connection to the BYOT Hub, authenticated with your API key. When the agent needs a local tool, the request is tunneled through this connection. Your machine executes the tool and sends the result back. Zero inbound ports – everything is outbound-only.

Reconnection: The client retries on connection failures with exponential backoff (4s initial, 30s max, 10 attempts). If the connection drops mid-session, it automatically retries.

Multi-client: You can run multiple BYOT clients with different --name values (e.g., --name lab and --name home). The agent sees both and can use tools from either machine.

uvx --from sec-gemini sec-gemini-byot [OPTIONS]
Flag Default Description
--api-key config.toml / env Sec-Gemini API key (see Configuration)
--name local Display name for this client
--hub production hub Hub URL (override for local dev)
--list-tools – List available base tools and exit
--tools TOOL [...] all Only enable these base tools
--no-base-tools – Disable all base tools
--mcp PATH [PATH ...] [] Extra MCPs as .py file paths or URLs
--skill, --skills PATH [PATH ...] [] Local skills: SKILL.md files, skill folders, or directories of skills (see Adding Your Own Skills)
--verbose false DEBUG-level console output

File Operations (9): read_file, write_file, edit_file, list_directory, grep, find_files, file_info, remove_file, remove_directory

Shell (6): bash, run_background, list_background, peek_background, stop_background, read_background

Python Execution (4): python_exec, python_install, python_packages, python_find_packages

JavaScript Execution (4): javascript_exec, javascript_install, javascript_packages, javascript_find_packages

Network (12): dns_lookup, whois_lookup, tcp_port_check, tcp_send, ping, traceroute, fetch_http, grep_http, http_headers, fetch_file, ssl_check, check_email_security

BYOT logs to ~/.config/sec-gemini/logs/byot.log (JSON, rotating). Add --verbose for console output.

Symptom Fix
“max retries reached” Check network, verify --hub URL
Tools not visible in session TUI handles this automatically; for SDK use, verify session MCP config
Connection drops frequently Client auto-retries; check your connection