genai-toolbox/docs/en/reference/cli.md at 8a514b3dd2780c34bcccfb1a7b035abcd348bc25

mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-01-23 22:38:14 -05:00

Files

Yuan Teoh 17b41f6453 feat: add allowed-hosts flag (#2254 )

## Description

Previously added `allowed-origins` (for CORs) is not sufficient for
preventing DNS rebinding attacks. We'll have to check host headers.

To test, run Toolbox with the following:
```
go run . --allowed-hosts=127.0.0.1:5000
```

Test with the following:
```
// curl successfully
curl -H "Host: 127.0.0.1:5000" http://127.0.0.1:5000

// will show Invalid Host Header error
curl -H "Host: attacker:5000" http://127.0.0.1:5000
```

## PR Checklist

> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [ ] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [ ] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)
- [ ] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

2026-01-08 19:42:54 +00:00

6.5 KiB

Raw Blame History

title, type, weight, description

title	type	weight	description
CLI	docs	1	This page describes the `toolbox` command-line options.

Reference

Flag (Short)	Flag (Long)	Description	Default
`-a`	`--address`	Address of the interface the server will listen on.	`127.0.0.1`
	`--disable-reload`	Disables dynamic reloading of tools file.
`-h`	`--help`	help for toolbox
	`--log-level`	Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.	`info`
	`--logging-format`	Specify logging format to use. Allowed: 'standard' or 'JSON'.	`standard`
`-p`	`--port`	Port the server will listen on.	`5000`
	`--prebuilt`	Use a prebuilt tool configuration by source type. See Prebuilt Tools Reference for allowed values.
	`--stdio`	Listens via MCP STDIO instead of acting as a remote HTTP server.
	`--telemetry-gcp`	Enable exporting directly to Google Cloud Monitoring.
	`--telemetry-otlp`	Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. 'http://127.0.0.1:4318')
	`--telemetry-service-name`	Sets the value of the service.name resource attribute for telemetry data.	`toolbox`
	`--tools-file`	File path specifying the tool configuration. Cannot be used with --tools-files or --tools-folder.
	`--tools-files`	Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --tools-file or --tools-folder.
	`--tools-folder`	Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --tools-file or --tools-files.
	`--ui`	Launches the Toolbox UI web server.
	`--allowed-origins`	Specifies a list of origins permitted to access this server for CORs access.	`*`
	`--allowed-hosts`	Specifies a list of hosts permitted to access this server to prevent DNS rebinding attacks.	`*`
`-v`	`--version`	version for toolbox

Examples

Transport Configuration

Server Settings:

--address, -a: Server listening address (default: "127.0.0.1")
--port, -p: Server listening port (default: 5000)

STDIO:

--stdio: Run in MCP STDIO mode instead of HTTP server

Usage Examples

# Basic server with custom port configuration
./toolbox --tools-file "tools.yaml" --port 8080

# Server with prebuilt + custom tools configurations
./toolbox --tools-file tools.yaml --prebuilt alloydb-postgres

Tool Configuration Sources

The CLI supports multiple mutually exclusive ways to specify tool configurations:

Single File: (default)

--tools-file: Path to a single YAML configuration file (default: tools.yaml)

Multiple Files:

--tools-files: Comma-separated list of YAML files to merge

Directory:

--tools-folder: Directory containing YAML files to load and merge

Prebuilt Configurations:

--prebuilt: Use predefined configurations for specific database types (e.g., 'bigquery', 'postgres', 'spanner'). See Prebuilt Tools Reference for allowed values.

{{< notice tip >}} The CLI enforces mutual exclusivity between configuration source flags, preventing simultaneous use of the file-based options ensuring only one of --tools-file, --tools-files, or --tools-folder is used at a time. {{< /notice >}}

Hot Reload

Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag.

Toolbox UI

To launch Toolbox's interactive UI, use the --ui flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit Toolbox UI.

6.5 KiB Raw Blame History