Bring Your Own Tools (BYOT)

Bring Your Own Tools (BYOT) bridges your local machine to the Sec-Gemini cloud agent. The SDK ships a binary (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 in any environment:

• Run inside a container, VM, or disposable cloud instance. This is the single most effective mitigation.
• Never run as root. The tools inherit your user privileges.
• Limit the tool surface. Use --tools to allow-list only the tools you need, or use --no-base-tools with a restricted custom MCP.
• Keep tool confirmations enabled. The default behavior pauses for approval before executing tool calls. Do not set auto_confirm_tools = true in config.toml when using baseline tools.
• Protect your API key. Use sec-gemini set-key rather than --api-key on the command line (visible in process listings). The SEC_GEMINI_API_KEY env var is a safer alternative for scripts.
• Verify custom MCP sources. There is no code-signing or integrity check on MCP files loaded via --additional-mcps.

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

Quick Start

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

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:

sec-gemini-byot --list-tools

To only enable specific tools:

sec-gemini-byot --tools dns_lookup ssl_check check_email_security

To disable the base tools entirely:

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 --additional-mcps:

sec-gemini-byot --additional-mcps ./my_tools.py

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

sec-gemini-byot --additional-mcps ./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 create_baseline_mcp

baseline, _ = create_baseline_mcp()
byot = ByotService(api_key="YOUR_API_KEY", name="my-client")
await byot.start(tools=[baseline])

# 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, _ = create_baseline_mcp()
await byot.start(tools=[baseline, 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

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
--additional-mcps	[]	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