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

BYOT tools run on your machine

When you enable baseline tools, the cloud agent can execute shell commands, read/write files, run Python and JavaScript code, and make network requests on your local machine. There is no sandbox or permission boundary – tool calls execute with your user privileges.

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.

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

Quick Start

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

pip

pip install sec-gemini
sec-gemini-byot

uv (standalone)

uvx --from 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:

pip

sec-gemini-byot --list-tools

uv (standalone)

uvx --from sec-gemini sec-gemini-byot --list-tools

To only enable specific tools:

pip

sec-gemini-byot --tools dns_lookup ssl_check check_email_security

uv (standalone)

uvx --from sec-gemini sec-gemini-byot --tools dns_lookup ssl_check check_email_security

To disable the base tools entirely:

pip

sec-gemini-byot --no-base-tools

uv (standalone)

uvx --from sec-gemini 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"]

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:

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:

pip

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

uv (standalone)

uvx --from sec-gemini sec-gemini-byot --mcp ./my_tools.py

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

pip

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

uv (standalone)

uvx --from sec-gemini sec-gemini-byot --mcp ./my_tools.py ./other_tools.py http://localhost:9000/sse

Using BYOT from the SDK

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])

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

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
--verbose	false	DEBUG-level console output

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

Note

File writes are guarded: the agent must read_file before it can write_file or edit_file. This sha256-based tracking prevents blind overwrites.

Logs

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

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