Building your config
Tilegroxy has a comprehensive declarative configuration schema that's critical to understand.
| See the Configuration Reference for every available option and Examples for complete configurations explained line by line. More examples are available in the repository. |
AI Lazy Button
A Skill is available to help AI coding agents write and troubleshoot tilegroxy configuration.
How to install it depends on your agent:
- Claude Code
-
Copy the skill file into
.claude/skills/generating-tilegroxy-configin your project (or~/.claude/skills/to make it available everywhere). - OpenClaw
-
Run
openclaw skills install git:Michad/tilegroxy@main --as generating-tilegroxy-config(add--globalto make it available to all agents), or install to a workspace/project skills directory as documented. - ChatGPT
-
Go to Skills, select Create, then Upload from your computer, and upload the skill’s directory (or a
.zipcontaining it as a single top-level folder). - Other agents supporting the agent skills specification
-
Copy the skill’s directory wherever your agent looks for skills; consult your agent’s documentation for the exact location.
- Agents without skill support
-
Paste the contents of
SKILL.mdinto your prompt or system instructions, or point the agent at its raw URL.
Conventions
Parameter names (configuration keys) are case-insensitive unless indicated otherwise.
Names (see below) are always lower case.
Unknown or misspelled configuration keys are rejected as an error rather than silently ignored, both at the top level and within any entity block. See Config Check for details.
Some parameters can be specified by environment variables which must be upper case. Environment variables override config parameters which override default values.
The environment variable name is derived by joining the parameter’s full key path with _, upper-cased. For example, server.port becomes SERVER_PORT and logging.main.level becomes LOGGING_MAIN_LEVEL. This works for any scalar parameter with a fixed key, even if it’s not set in your config file at all. It does not apply to the dynamic, per-entity parameters described in Entities, which support env.ENV_VAR_NAME value substitution instead.
Entities
Some configuration sections (authentication, provider, cache, datastores, analytics, ratelimit, tls and secret) support selecting different methods of operation that change the full list of parameters available. For example, a "proxy" provider requires a url parameter to get a map tile from another server while a "static" provider takes in a image to return for every request. You select these operating modes using a parameter called name.
Since these entities are too dynamic to have fixed environment variables and frequently may require a secret to operate, any string parameters can be made to use an environment variable by specifying a value in the format of env.ENV_VAR_NAME. You can also use an external secret store if configured by specifying a value in the format secret.SECRET_NAME.
Extension Keys
If you need to re-use a section of configuration, you can make use of a top level extension key starting with x-. Tilegroxy allows any such section at the top level of the configuration. From there, you can use YAML anchors to reuse bits of configuration wherever you need.
For example:
x-shared:
regionValidator: ®ionValidator "(?:north|south|east)"
upstream: &upstream
name: proxy
url: "https://tiles.example.com/{layer.region}/{z}/{x}/{y}"
layers:
- id: regional
pattern: "regional_{region}"
paramValidator:
region: *regionValidator
provider: *upstream
- id: regional_hd
pattern: "regional_{region}_hd"
paramValidator:
region: *regionValidator
provider: *upstreamAn anchor must be defined above its first use in the file.