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.
Security Considerations
Section titled “Security Considerations”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
--toolsto allow-list only specific tools, or use--no-base-toolswith 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
--skillsis a set of instructions the agent follows using the tools this client exposes. Only load skills you wrote or reviewed; never point--skillsat a directory from an untrusted checkout. See Adding Your Own Skills.
For cloud-side security guarantees (data handling, encryption, logging suppression), see Architecture & Security.
Quick Start
Section titled “Quick Start”To allow Sec-Gemini to access your filesystem and network (see the full tool list below), launch the BYOT client:
pip install sec-geminisec-gemini-byotuvx --from sec-gemini sec-gemini-byotThe 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:
sec-gemini-byot --list-toolsuvx --from sec-gemini sec-gemini-byot --list-toolsTo only enable specific tools:
sec-gemini-byot --tools dns_lookup ssl_check check_email_securityuvx --from sec-gemini sec-gemini-byot --tools dns_lookup ssl_check check_email_securityTo disable the base tools entirely:
sec-gemini-byot --no-base-toolsuvx --from sec-gemini sec-gemini-byot --no-base-toolsTo selectively disable specific tools via config, set disabled_tools in your ~/.config/sec-gemini/config.toml:
[baseline_tools]enabled = truedisabled_tools = ["bash", "remove_file", "remove_directory"]Adding Your Own Tools
Section titled “Adding Your Own Tools”You can extend the agent with custom tools by writing an MCP server. The easiest way is with FastMCP – create a .py file:
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:
sec-gemini-byot --mcp ./my_tools.pyuvx --from sec-gemini sec-gemini-byot --mcp ./my_tools.pyYou can pass multiple sources – .py files or URLs of already-running MCP servers:
sec-gemini-byot --mcp ./my_tools.py ./other_tools.py http://localhost:9000/sseuvx --from sec-gemini sec-gemini-byot --mcp ./my_tools.py ./other_tools.py http://localhost:9000/sseAdding Your Own Skills
Section titled “Adding Your Own Skills”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-phishingdescription: Triage a suspected phishing email end to end---
1. Extract URLs and attachments ...# One skillsec-gemini-byot --skill ./triage-phishing/SKILL.md
# A directory of skills: one SKILL.md per skill foldersec-gemini-byot --skills ~/my-skills# One skilluvx --from sec-gemini sec-gemini-byot --skill ./triage-phishing/SKILL.md
# A directory of skills: one SKILL.md per skill folderuvx --from sec-gemini 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).
Using BYOT from the SDK
Section titled “Using BYOT from the SDK”Start the BYOT client programmatically instead of the CLI:
from sec_gemini.byot.service import ByotServicefrom 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 statusstatus = byot.status() # .state, .tool_count, .tools
# Stop when doneawait 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])How It Works Under the Hood
Section titled “How It Works Under the Hood”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.
CLI Reference
Section titled “CLI Reference”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 |
Base Tools (enabled by default)
Section titled “Base Tools (enabled by default)”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.
Troubleshooting
Section titled “Troubleshooting”| 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 |