Configuration Reference :: tilegroxy Docs

See Examples for complete configurations explained line by line. More examples are available in the repository.

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-config in your project (or ~/.claude/skills/ to make it available everywhere).
OpenClaw: Run openclaw skills install git:Michad/tilegroxy@main --as generating-tilegroxy-config (add --global to 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 .zip containing 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.md into 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 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

Structure

The following is the top-level configuration structure. All top-level keys are optional besides layers:

server: ... (1)
health: ... (2)
client: ... (3)
logging: ... (4)
telemetry: ... (5)
error: ... (6)
secret: ... (7)
authentication: ... (8)
cache: ... (9)
defaultcache: some-id (10)
datastores: (11)
  - ...
analytics: ... (12)
layers: (13)
  - ...

1	Server: how the HTTP server operates
2	Health: health check endpoints served on a separate port
3	Client: how requests to upstream HTTP servers are made
4	Log: application, access, and audit logs
5	Telemetry: OpenTelemetry metrics, logs, and traces
6	Error: how errors are returned to users
7	Secret: an external store for sensitive values
8	Authentication: how incoming requests are authenticated
9	Cache: where tiles are stored, either a single cache or a list of them
10	Default cache: the ID of the cache layers use unless they specify another
11	Datastores: shared connections used by caches, providers, and analytics
12	Analytics: where usage events are recorded
13	Layers: the layers to serve