This page is the canonical reference for everything tileserver-rs reads —
CLI flags, config keys (TOML or YAML), and environment variables — sourced directly
from the Rust structs in crates/tileserver-rs/src/config.rs and
crates/tileserver-rs/src/cli.rs.
Config file formats
tileserver-rs accepts both TOML and YAML config files. The format is detected from the file extension:
| Extension | Parser |
|---|---|
.toml | TOML (default) |
.yaml, .yml | YAML |
| anything else | TOML (fallthrough) |
TOML and YAML produce identical Config structs — every option documented
on this page works in both formats. See data/configs/example.toml
for the canonical exhaustively-commented reference and data/configs/example.yaml
for the YAML syntax mirror.
# Either of these works:
tileserver-rs --config config.toml
tileserver-rs --config config.yaml
tileserver-rs --config config.yml
For task-oriented guides see Quickstart, Vector tiles, Auto-detect, Postgres, MCP, and Telemetry.
Precedence
When the same value is supplied in multiple places, later sources override earlier ones:
- Hard-coded defaults (lowest priority)
- Config file in TOML or YAML (
--config) - Environment variables (
TILESERVER_*) - CLI flags (highest priority)
Config file lookup
If --config is not provided, the server resolves what to load in this
order:
--config <FILE>— explicit config path (fails if the file does not exist)- Positional
PATH— auto-detect sources/styles from that path (see Auto-detect) - Default locations, tried in order:
./config.toml,./config.yaml,./config.yml, then/etc/tileserver-rs/config.{toml,yaml,yml} - CWD auto-detect — scan the current directory for
.pmtiles,.mbtiles,style.json, and font directories
CLI flags
tileserver-rs [OPTIONS] [PATH] [SUBCOMMAND]
| Flag | Env fallback | Default | Description |
|---|---|---|---|
[PATH] (positional) | — | — | File or directory to auto-detect sources/styles from (zero-config mode) |
-c, --config <FILE> | TILESERVER_CONFIG | — | Path to TOML config file |
--cache-dir <PATH> | TILESERVER_CACHE_DIR | <tmp>/tileserver-rs | Scratch / state directory (uploads, on-disk subsystems). Overrides [cache].dir |
--host <HOST> | TILESERVER_HOST | from [server] | Override bind address |
-p, --port <PORT> | TILESERVER_PORT | from [server] | Override bind port |
--public-url <URL> | TILESERVER_PUBLIC_URL | — | Public URL embedded in TileJSON tiles entries |
--ui | TILESERVER_UI | true | Serve the embedded SPA web UI |
--no-ui | — | — | Disable the embedded SPA web UI |
-v, --verbose | — | false | Increase log verbosity |
Subcommands
| Subcommand | Feature gate | Description |
|---|---|---|
| (none) | — | Run the HTTP server (default) |
mcp-stdio | mcp | Run the MCP server over stdin/stdout for Claude Desktop and other local clients |
inspect | — | Print metadata, tile counts and layers of a PMTiles/MBTiles archive, then exit (see below) |
inspect
Describe an archive without starting the server. The target is a local
.pmtiles or .mbtiles file, or an http(s):// PMTiles URL (read with
range requests, so only the header, metadata and the requested tile are
downloaded).
tileserver-rs inspect data/tiles/protomaps-sample.pmtiles
tileserver-rs inspect data/zurich.mbtiles --verbose # adds tiles per zoom
tileserver-rs inspect data/zurich.mbtiles --tile 10/536/358 # decode one tile
tileserver-rs inspect https://example.com/planet.pmtiles --json
| Flag | Description |
|---|---|
--tile Z/X/Y | Decode one tile (XYZ order). Vector tiles list each layer's feature count per geometry type and its property keys |
-v, --verbose | Count tiles per zoom level (MBTiles only: a PMTiles count needs every leaf directory) |
--json | Print the report as JSON for scripts |
The report shows the container (PMTiles version or MBTiles), tile type,
compression, file size, tile count (and unique tiles for PMTiles), zoom
range, bounds, center, name, description, attribution and the
vector_layers metadata. A missing file or URL exits with status 1.
[server]
[server]
host = "0.0.0.0"
port = 8080
cors_origins = ["*"]
admin_bind = "127.0.0.1:0"
public_url = "https://tiles.example.com" # optional
upload_dir = "/var/lib/tileserver/uploads" # optional
upload_max_size_mb = 500
upload_max_total_mb = 5120
upload_max_files = 100
disable_render = false # optional — turn off raster routes
disable_ogc = false # optional — turn off OGC API routes
subfolder_mode = "proxy-strip" # optional — subfolder serving mode
| Key | Type | Default | Description |
|---|---|---|---|
host | string | "0.0.0.0" | Bind address for the public tile server |
port | u16 | 8080 | Bind port for the public tile server |
cors_origins | string | ["*"] | CORS allow-list — supports literals, glob (*), and regex (/.../); see Pattern syntax below |
admin_bind | string | "127.0.0.1:0" | Separate bind for admin endpoints (/__admin/reload, /__admin/oauth/*). :0 disables. Use 127.0.0.1:8081 to enable. |
admin_allowed_hosts | string | [] | Extra Host/Origin names the admin listener accepts besides loopback (localhost, 127.0.0.1, [::1]). Other names get 403, which blocks DNS-rebinding and cross-site requests. Add your proxy's host if it forwards its own Host header |
public_url | string? | (none) | Public URL embedded in TileJSON. Falls back to the bind address |
upload_dir | path? | system tmp | Directory for drag-and-drop uploads (creates a tmp source per upload) |
upload_max_size_mb | u32 | 500 | Maximum per-file upload size in megabytes. Larger uploads get 413 and leave no file behind |
upload_max_total_mb | u32 | 5120 | Total disk space all uploaded files may use, in megabytes |
upload_max_files | u32 | 100 | Maximum number of uploaded files kept at once |
extra_response_headers | table? | (none) | User-defined response headers applied to every HTTP response — see [server.extra_response_headers] below |
disable_render | bool | false | Unregister raster render routes (raster tiles + static images) at startup. Style metadata (style.json, sprites, WMTS) stays served. Disabled routes return 404. |
disable_ogc | bool | false | Unregister OGC API routes (/ogc/*) at startup. No effect unless built with the ogc feature. Disabled routes return 404. |
subfolder_mode | "proxy-strip" | "nested" | "proxy-strip" | How the embedded GUI + API are served under a URL subfolder — see Subfolder deployment below. Ignored for root deployments. |
Subfolder deployment
By default the server assumes it is mounted at the domain root (https://tiles.example.com/). To serve it under a URL subfolder (e.g. https://example.com/maps/), set the subfolder path in public_url — the server derives the base path from it and rebases the embedded GUI (asset URLs, API calls, and the Vue Router base) at startup, so no client rebuild is needed. A root deployment (no subfolder in public_url) serves byte-identical embedded assets, so this feature is a no-op unless you opt in.
subfolder_mode chooses where the subfolder prefix is stripped from incoming request paths:
| Mode | Who strips the prefix | Reverse-proxy config |
|---|---|---|
"proxy-strip" (default) | The reverse proxy | proxy_pass http://backend/; (trailing slash strips /maps) |
"nested" | The server itself | proxy_pass http://backend; (no trailing slash — prefix forwarded intact) |
proxy-strip (default) — the reverse proxy removes the /maps prefix before forwarding, so the server sees root paths (/ping, /_nuxt/x.js). The GUI is still rebased so the browser requests /maps/... URLs.
location /maps/ {
proxy_pass http://127.0.0.1:8080/; # trailing slash strips /maps
}
[server]
public_url = "https://example.com/maps"
# subfolder_mode defaults to "proxy-strip"
nested — the proxy forwards the prefix untouched and the server strips it itself. Useful when the proxy cannot rewrite the path, or for testing a subfolder locally with no proxy at all.
location /maps/ {
proxy_pass http://127.0.0.1:8080; # no trailing slash — prefix forwarded
}
[server]
public_url = "https://example.com/maps"
subfolder_mode = "nested"
With nested the server responds directly at http://127.0.0.1:8080/maps/ — you can verify a subfolder deployment end-to-end with no proxy.
CORS origin patterns
The cors_origins list accepts three syntaxes, dispatched per entry:
| Entry syntax | Interpretation |
|---|---|
"*" | Wildcard — allow any origin (default; emits a startup warning) |
"https://example.com" | Exact literal match (unchanged from previous behaviour) |
"*.example.com" | Glob — * matches one or more characters in the Origin URL |
"preview-*.example.com" | Glob — * can appear anywhere in the pattern |
"/^https://.+\\.example\\.com$/" | Regex — enclosed in /.../, matched against the full Origin |
[server]
cors_origins = [
"https://example.com",
"*.cdn.example.com",
"preview-*.example.com",
"/^https://.+\\.team-[a-z0-9]+\\.app\\.example\\.com$/",
]
Notes:
- Entries are tried in order; the first match short-circuits per request.
- A list containing
"*"ALWAYS resolves to wildcard regardless of other entries — that is the existing semantics, preserved. - Pure-literal lists (no
*, no/.../) use the same allocation-freeAllowOrigin::listfast-path as before. Adding a glob or regex switches the layer toAllowOrigin::predicate. - Invalid regex (e.g. unbalanced
[) fails fast at startup with the offending entry quoted in the error. - Glob entries are compiled by anchoring with
^...$and replacing*with.*— so*.x.commatchesfoo.x.comandhttps://foo.x.com, but NOTx.com(no leading subdomain) orfoo.x.com.evil.com(suffix injection blocked).
[server.extra_response_headers]
A user-defined map of HTTP response headers that are applied (in
SetResponseHeaderLayer::overriding mode) to every response served by
tileserver-rs — tile, style, OGC, admin, MCP, everything. Useful for:
| Use case | Example header |
|---|---|
| Edge / CDN cache control | CDN-Cache-Control, Surrogate-Control |
| Browser cache control | Cache-Control (overrides any default) |
| Block search-engine indexing | X-Robots-Tag: noindex, nofollow |
| HSTS for TLS terminators | Strict-Transport-Security |
| Content security | X-Content-Type-Options: nosniff |
| APM correlation | Server-Timing, custom X-* audit headers |
[server.extra_response_headers]
"Cache-Control" = "public, max-age=86400, immutable"
"CDN-Cache-Control" = "max-age=604800"
"X-Robots-Tag" = "noindex, nofollow"
"X-Content-Type-Options" = "nosniff"
"Strict-Transport-Security" = "max-age=31536000; includeSubDomains"
"Server-Timing" = "tileserver;dur=0"
Equivalent YAML:
server:
extra_response_headers:
Cache-Control: public, max-age=86400, immutable
CDN-Cache-Control: max-age=604800
X-Robots-Tag: noindex, nofollow
Rules:
- Header names must conform to RFC 7230 token grammar (alphanumeric +
!#$%&'*+-.^_\|~`). - The transport-managed headers
Content-Length,Transfer-Encoding,Date,Connectionare rejected at startup — the server fails fast. - An empty string value (
"X-Foo" = "") removes any pre-existingX-Fooheader from outgoing responses. - User values are
overriding— they win over anything an upstream middleware emits. - Hot reload (
POST /__admin/reload) picks up changes without a restart.
[[sources]]
Each [[sources]] block configures one tile source. The type field
determines which optional fields are read.
Common fields
| Key | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique identifier (becomes /data/<id>/* route) |
type | enum | yes | One of: pmtiles, mbtiles, postgres, cog, vrt, geoparquet, duckdb, stac (some feature-gated) |
path | string | yes | File path, HTTP(S) URL, cloud URL (s3://, gs://, az://), or SFTP URL (sftp://, feature-gated) |
name | string? | no | Display name shown in the viewer |
attribution | string? | no | Attribution text included in TileJSON |
description | string? | no | Free-form description |
minzoom | u8? | no | Override the minzoom from source metadata |
maxzoom | u8? | no | Override the maxzoom from source metadata |
serve_as | enum? | no | Transcode on the fly. E.g. serve_as = "mlt" on a PBF source emits MLT. Requires mlt feature |
options | table | no | Key-value map forwarded to cloud backends (S3 credentials, GCS keys, etc.) — see Cloud sources |
Type-specific fields
type = "pmtiles" / type = "mbtiles"
These read all metadata (zoom range, bounds, layers) from the file itself.
No extra config needed beyond id, type, and path.
type = "dir"
Serve a {z}/{x}/{y}.{ext} pyramid straight from disk — no PMTiles/MBTiles
packaging step. The lowest-friction source: point it at tippecanoe
--output-to-directory output, a wget --recursive mirror, or any on-disk
pyramid. Zero startup index cost; every tile fetch is a direct filesystem read.
[[sources]]
id = "tippecanoe-output"
type = "dir"
path = "/data/tiles/openmaptiles/"
# tile_path_template = "{z}/{x}/{y}@2x.png" # optional, default {z}/{x}/{y}.{ext}
# tms = true # optional, default false (XYZ)
minzoom, maxzoom, and bounds are derived lazily by walking the directory
on the first TileJSON request, then cached. Missing tiles behave like every
other source. For tilesets with millions of files, the natural
{z}/{x}/{y} sharding keeps per-directory entry counts manageable.
type = "tar"
Serve a .tar bundle of {z}/{x}/{y}.{ext} tiles — a single portable file,
ideal for airgapped / offline / scp-everywhere deployments. The archive is
decompressed once at startup and an in-memory (z, x, y) index is built; tiles
are then served via random access. Compression is auto-detected by extension:
.tar, .tar.gz / .tgz, .tar.br, .tar.zst.
[[sources]]
id = "regional-tiles"
type = "tar"
path = "/data/tiles.tar.gz" # or .tar / .tar.br / .tar.zst
Vector layer metadata is introspected from the first MVT tile, exactly like the PMTiles source. Tradeoff: the whole archive is held resident in memory (the index alone is ~16 bytes per tile). For planet-scale tilesets, PMTiles remains the production choice — its hierarchical directory avoids keeping every tile in memory.
dir / tar shared options
Both filesystem-style sources accept two extra fields:
| Option | Default | Description |
|---|---|---|
tile_path_template | {z}/{x}/{y}.{ext} | Layout template. Must contain {z}, {x}, {y}; {ext} is optional. Example: {z}/{x}/{y}@2x.png. |
tms | false | true flips the Y axis for TMS (south-up) archives. Default false serves XYZ (north-up), what tippecanoe emits and web clients expect. |
type = "postgres" (feature: postgres)
Combines the common fields with one of two patterns: functions or
tables. Defined inside the top-level [postgres] block,
not directly on the source. See the PostGIS guide.
type = "cog" / type = "vrt" (feature: raster)
| Key | Type | Default | Description |
|---|---|---|---|
resampling | enum? | bilinear | GDAL warp resampler. One of: nearest, bilinear, cubic, cubicspline, lanczos, average, mode. With a discrete colormap the default is nearest |
colormap | table? | (none) | See ColorMap below |
In v2.39.0 and earlier, resampling had no effect on COG, VRT, DEM, STAC and
PostGIS out-db tiles: GDAL always warped them with bilinear. The setting
now selects the warp algorithm.
Remote paths
path can be a local file or a remote file. Remote paths use these forms:
| You write | GDAL opens |
|---|---|
https://host/file.tif | /vsicurl/https://host/file.tif |
http://host/file.tif | /vsicurl/http://host/file.tif |
s3://bucket/file.tif | /vsis3/bucket/file.tif |
/vsicurl/…, /vsis3/…, /vsigs/… | the path as written |
tileserver-rs adds the GDAL prefix for you. With the prefix, GDAL reads only the byte ranges that a tile needs. Without it, GDAL downloads the full file each time it opens the file.
- The server that hosts the file must support HTTP range requests (
Accept-Ranges: bytes). s3://paths use the standard GDAL credentials (AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_REGION, orAWS_NO_SIGN_REQUEST=YESfor public buckets).- Other schemes (for example
gs://oraz://) are not rewritten. Write the GDAL prefix (/vsigs/,/vsiaz/) yourself.
[[sources]]
id = "sentinel"
type = "cog"
path = "https://example.com/imagery/TCI.tif"
Bands and transparency
The number of source bands sets the colour and the transparency of each tile:
| Source bands | Tile colour | Tile transparency |
|---|---|---|
1, with colormap | colour from the colormap | from the colormap colour |
1, no colormap | gray | opaque |
2, no colormap | band 1 = red, band 2 = green | opaque |
| 3 or more | bands 1–3 = red, green, blue | from the source data (see below) |
For 3 or more bands, GDAL calculates the alpha while it warps the tile
(the same as gdalwarp -dstalpha and TiTiler):
- Pixels outside the source data are transparent.
- If the last source band is an alpha band (for example an RGBA COG), the tile keeps that alpha.
- Other bands after band 3 are not used.
In v2.39.0 and earlier, RGB tiles were opaque black outside the source data, RGBA tiles were fully transparent, and 2-band tiles were fully transparent.
type = "dem" (feature: dem)
Reads float elevation from a GDAL raster (COG / GeoTIFF) and re-encodes each
pixel as a Terrarium or Mapbox-RGB (terrain-rgb) PNG tile that
MapLibre GL JS consumes directly as a raster-dem source for 3D terrain,
hillshading, and contour generation. Both encodings are bit-exact to what
MapLibre decodes.
| Key | Type | Default | Description |
|---|---|---|---|
path | string? | (none) | Source GDAL raster: a local file or a remote path. Omit when input_source is set |
input_source | string? | (none) | Id of another already-loaded cog/vrt source to read elevation from. Shares its cached GDAL dataset (no re-open) |
dem_encoding | enum? | terrarium | terrarium (precision 1/256 m) or mapbox_rgb (legacy terrain-rgb, precision 0.1 m) |
dem_band | u32? | 1 | 1-indexed GDAL band to encode |
dem_scale | f64? | 1.0 | Multiplier applied to elevation before encoding (e.g. feet → metres: 0.3048) |
dem_offset | f64? | 0.0 | Additive offset applied after dem_scale |
dem_nodata_color | u84? | (per-enc.) | RGBA sentinel for nodata pixels. MapLibre ignores alpha, so the RGB encodes "no data". Mapbox default [1,134,160], Terrarium [0,0,0] |
resampling | enum? | bilinear | Same GDAL resampler set as cog |
Use it in a style as a raster-dem source:
{
"sources": {
"terrain": {
"type": "raster-dem",
"tiles": ["https://tiles.example.com/data/terrain-terrarium/{z}/{x}/{y}.png"],
"encoding": "terrarium",
"tileSize": 256
}
},
"terrain": { "source": "terrain", "exaggeration": 1.5 }
}
type = "geoparquet" (feature: geoparquet)
| Key | Type | Required | Description |
|---|---|---|---|
layer_name | string? | no | Override the layer name in emitted MVT tiles |
geometry_column | string? | no | Geometry column name (auto-detected when GeoParquet metadata is present) |
query | string? | no | DuckDB SQL filter applied before tile materialization |
type = "duckdb" (feature: duckdb)
Same layer_name, geometry_column, query as GeoParquet.
type = "stac" (feature: stac)
| Key | Type | Default | Description |
|---|---|---|---|
collection | string? | (none) | STAC collection ID |
asset_role | string | "visual" | Which asset role to render (e.g. "visual", "thumbnail", "data") |
dynamic | bool | false | Enable on-demand STAC search per tile request (vs. one-time discovery at startup) |
max_items | usize | 100 | Max items considered per tile request when dynamic = true |
stac_bbox | f644? | (none) | Override the bbox passed to STAC search |
pixel_selection | enum | first | Mosaic strategy. See Pixel selection |
options.allow_local_hrefs | string | (unset) | "true" lets a remote (http(s)) catalog point at local paths, file:, /vsi… or s3:// assets. Off by default: such hrefs from a remote catalog are skipped, so a catalog cannot make the server open its own files. A local catalog file is always trusted |
Pixel selection (feature: stac or raster)
| Variant | Short-circuit | Description |
|---|---|---|
first (default) | yes | First valid pixel wins. Lowest latency |
highest | no | Per-pixel max across all bands. Highlights bright features |
lowest | no | Per-pixel min. Highlights shadows |
mean | no | Per-pixel arithmetic mean |
median | no | Per-pixel median. Robust to outliers |
stdev | no | Per-pixel std-dev. Change detection |
count | no | Per-pixel valid-input count (debug viz, encodes count in red channel) |
lowestcloudcover | yes | Pick the STAC asset with lowest eo:cloud_cover, then first ordering |
ColorMap (feature: raster)
[[sources]]
id = "ndvi"
type = "cog"
path = "/data/ndvi.tif"
[sources.colormap]
type = "discrete" # or "continuous"
rescale_mode = "static" # or "dynamic" / "none"
nodata_color = "#00000000"
[[sources.colormap.entries]]
value = -1.0
color = "#0033cc"
[[sources.colormap.entries]]
value = 0.0
color = "#888888"
| Key | Type | Default | Description |
|---|---|---|---|
type | enum | discrete | discrete = stepped, continuous = interpolated |
rescale_mode | enum | static | static = use entry values verbatim. dynamic = stretch to per-tile data range. none = no rescale |
entries | table | required | List of {value, color} stops |
nodata_color | string? | (none) | Hex color (incl. alpha) for nodata pixels |
[[styles]]
[[styles]]
id = "osm-bright"
path = "/data/styles/osm-bright/style.json"
name = "OSM Bright"
| Key | Type | Required | Description |
|---|---|---|---|
id | string | yes | Style identifier (becomes /styles/<id>/* route) |
path | string | yes | Path to a MapLibre style JSON file |
name | string? | no | Display name shown in the viewer |
attribution | string? | no | Attribution text |
[[composites]]
Named multi-source composites merge vector tiles from several sources into
one endpoint at /data/{id} (see the
Composite Sources guide):
[[composites]]
id = "world-base"
sources = ["protomaps", "zurich"]
| Key | Type | Required | Description |
|---|---|---|---|
id | string | yes | Composite identifier (becomes /data/<id>/* route) |
sources | string | yes | Member source ids merged into this composite |
Ad-hoc composites (/data/a+b+c/...) work without any config; a configured
[[composites]] id always wins over ad-hoc + parsing.
[sftp] (feature: sftp)
Global defaults for SFTP sources:
[sftp]
known_hosts_path = "/etc/tileserver/known_hosts"
strict_host_key = true
| Key | Type | Default | Description |
|---|---|---|---|
known_hosts_path | path? | ~/.ssh/known_hosts | known_hosts file used for host-key verification |
strict_host_key | bool | true | Fail-closed on unknown hosts; false accepts first-seen keys (TOFU) |
[render]
Native MapLibre raster renderer pool. See Static images.
[render]
pool_size = 4
render_timeout_secs = 30
queue_size = 256
| Key | Type | Default | Description |
|---|---|---|---|
pool_size | usize | 4 | Concurrent renderer worker threads |
render_timeout_secs | u64 | 30 | Per-request render timeout. Requests exceeding this are dropped |
queue_size | usize | 256 | Render requests that may wait for a free worker. More get 503 |
[cache]
Global in-process tile cache (moka backend).
[cache]
enabled = true
max_size_mb = 512
ttl_seconds = 3600
dir = "/var/lib/tileserver" # optional — scratch / state directory
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable the global tile cache |
max_size_mb | u64 | 512 | Maximum cache size in megabytes |
ttl_seconds | u64 | 3600 | Time-to-live for cache entries |
dir | path? | <tmp>/tileserver-rs | Scratch / state directory for on-disk subsystems (today: uploads). Storage location only — not a cache eviction policy. |
dir sets where on-disk state (e.g. uploads) lives, not the in-memory tile
cache. Resolution precedence (highest first): --cache-dir flag →
TILESERVER_CACHE_DIR env → [cache].dir → <tmp>/tileserver-rs.
[compression]
Negotiates Accept-Encoding per request and serves tile bodies as brotli or
zstd when the client accepts them. By default tiles are served in whatever
encoding the source stores them in (gzip for most PMTiles); enabling brotli or
zstd negotiation produces 15–40% smaller payloads on typical vector tiles.
[compression]
br_quality = 5 # brotli quality 0-11 (default 5)
zstd_level = 3 # zstd level 1-22 (default 3)
minimal_recompression = false # if true, never re-encode — always passthrough
| Key | Type | Default | Description |
|---|---|---|---|
br_quality | u8 | 5 | Brotli quality (0–11). Higher = smaller payload, slower encode. |
zstd_level | i32 | 3 | Zstandard level (1–22). Higher = smaller payload, slower encode. |
minimal_recompression | bool | false | When true, never decode/re-encode — serve the source encoding as-is. |
How negotiation works per request:
- If the source's stored encoding is already in the client's
Accept-Encodingset, it is served as-is (no decode/re-encode). - Otherwise the tile is decoded once and re-encoded to the highest-preference
acceptable encoding, then cached under
(source, z, x, y, encoding)so the re-encode cost is paid once per tile + encoding pair. - Tiles smaller than 200 bytes skip compression — the framing overhead exceeds the savings.
Every tile response carries Vary: Accept-Encoding so CDNs cache one copy per
encoding rather than serving a wrong-encoding copy to a client that cannot
decode it.
Brotli at quality 10–11 can exceed 100 ms per tile. The default q5 favours
first-paint latency; raise it only if you precompute tiles in batch. Set
minimal_recompression = true to disable negotiation entirely and serve source
bytes verbatim.
[live]
Live source updates over WebSocket. With enabled = true the server mounts
GET /ws and tells connected clients when a source's data changes, so maps
re-fetch its tiles without a page reload. The built-in viewer connects
automatically.
[live]
enabled = true
watch = ["live-tracking"] # or ["*"] for every source
interval_secs = 5
max_clients = 1000
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Mount GET /ws and broadcast source reloads |
watch | string | [] | Source ids to poll for data changes; ["*"] polls every source. Unknown ids fail validation |
interval_secs | u64 | 5 | Seconds between polls (minimum 1) |
max_clients | usize | 1000 | Maximum concurrent WebSocket clients; further upgrades get 503 |
A client receives a reload for a source when:
- a hot reload (
SIGHUP,POST /__admin/reload) changed, added or removed that source's[[sources]]entry (a forced reload sends every source); - the source is watched and its data changed: local files are compared by
modification time and size,
http(s)sources byETag,Last-ModifiedandContent-Length. The server then reloads its sources (likeSIGHUP, with a fresh tile cache) before it sends the message.
Protocol
JSON text frames on ws(s)://<host>/ws:
// server → client, once on connect
{ "type": "hello", "sources": ["live-tracking", "osm"] }
// server → client, when a source changes
{ "type": "reload", "source": "live-tracking" }
// client → server
{ "type": "subscribe", "source": "live-tracking" }
{ "type": "unsubscribe", "source": "live-tracking" }
A client with no subscriptions receives every source's messages; after its
first subscribe it receives only the sources it subscribed to. A client that
falls more than 256 messages behind gets a reload for each of its
subscriptions. Messages name a whole source; there are no per-tile
invalidations yet.
In MapLibre GL JS, re-fetch the tiles of the style sources that read from the
reloaded server source. Tiles are served with Cache-Control: max-age=86400,
so bypass the browser cache for them:
const reloaded = new Set();
map.setTransformRequest((url) =>
[...reloaded].some((id) => url.includes(`/data/${id}`))
? { url, cache: 'no-cache' }
: { url },
);
const ws = new WebSocket('wss://tiles.example.com/ws');
ws.onmessage = ({ data }) => {
const msg = JSON.parse(data);
if (msg.type !== 'reload') return;
reloaded.add(msg.source);
map.refreshTiles('my-source'); // the style source fed by msg.source
};
Behind a reverse proxy, forward the upgrade headers for /ws (nginx:
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";) and raise proxy_read_timeout.
/ping reports live_enabled.
[llm]
Server-side LLM proxy for the Map AI chat panel. When enabled, the panel offers
a Server provider option that sends chat requests to POST /api/llm/chat;
the server forwards them to your provider and streams the answer back. The API
key is read from an environment variable on every request, so it never appears
in the config file and never reaches the browser. See
AI Chat for the full setup.
[llm]
enabled = true
provider = "anthropic" # or "openai-compatible"
base_url = "https://api.anthropic.com"
api_key_env = "TILESERVER_LLM_API_KEY" # env var name, not the key itself
model = "claude-sonnet-4-5"
allow_user_keys = true # also allow bring-your-own-key in the browser
timeout_secs = 120
max_body_bytes = 1048576
rate_limit_per_minute = 30
max_output_tokens = 8192
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable POST /api/llm/chat. |
provider | enum | openai-compatible | Upstream API family: openai-compatible or anthropic. |
base_url | string | — | Upstream base URL. https:// only; http:// allowed for localhost. |
api_key_env | string | — | Environment variable holding the key. Omit for keyless local servers. |
model | string | — | Model sent upstream. Required when enabled; overrides the client's model. |
allow_user_keys | bool | true | Also show the bring-your-own-key providers in the panel. |
timeout_secs | u64 | 120 | Upstream timeout for one chat response. |
max_body_bytes | usize | 1048576 | Largest accepted request body (larger bodies get 413). |
rate_limit_per_minute | u32 | 30 | Proxy requests per minute across all clients (429 when exceeded); 0 = no limit. |
max_output_tokens | u32 | 8192 | Cap on max_tokens, max_completion_tokens and a thinking budget in proxied requests; n is forced to 1, so a client cannot multiply the cost of your key. |
Startup fails when the proxy is enabled without a valid base_url or model,
or when api_key_env names an unset variable.
[raster] (feature: raster)
[raster]
default_resampling = "bilinear"
tile_size = 256
| Key | Type | Default | Description |
|---|---|---|---|
default_resampling | enum | bilinear | Default resampler. Per-source resampling overrides this |
tile_size | u32 | 256 | Output tile size in pixels (set to 512 for retina-native tiles) |
Open-dataset cache
COG, VRT, DEM and STAC sources share one process-wide cache of open GDAL
datasets. Each file has one entry for the full-resolution base and one per
overview level (OVERVIEW_LEVEL=N). Each entry is a small pool of handles,
one per CPU core at most, so concurrent tiles from the same file render in
parallel.
The cache is bounded by an estimated byte budget, 256 MiB by default. Each base handle counts as 16 MiB and each overview handle as 8 MiB. A pool keeps at most 2 idle handles, and entries expire after 10 minutes.
When the budget is full, the server closes idle handles of other files. If that frees too little, the request waits up to 75 ms for a handle, then opens the file for this one tile only. A full budget therefore makes tiles slower, but it never fails them. These one-tile opens are limited to two per CPU core at a time.
Set TILESERVER_DATASET_CACHE_MAX_BYTES to change the budget, for example
for large STAC mosaics on a host with more memory. See
Environment variables.
[telemetry]
OpenTelemetry tracing + Prometheus metrics. See Telemetry.
[telemetry]
enabled = true
endpoint = "http://localhost:4317"
service_name = "tileserver-rs"
sample_rate = 1.0
metrics_enabled = true
metrics_export_interval_secs = 30
prometheus_bind = "127.0.0.1:9100"
prometheus_path = "/metrics"
metrics_label_cardinality = "strict"
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable OTLP trace export |
endpoint | string | "http://localhost:4317" | OTLP gRPC endpoint |
service_name | string | "tileserver-rs" | service.name resource attribute |
sample_rate | f64 | 1.0 | Sampling rate (0.0–1.0). 1.0 = export every span |
metrics_enabled | bool | true | Enable OTLP metrics export (requires enabled = true) |
metrics_export_interval_secs | u64 | 30 | OTLP metrics push interval |
prometheus_bind | string? | (none) | Bind for standalone Prometheus /metrics listener (independent of OTLP). E.g. "127.0.0.1:9100" |
prometheus_path | string | "/metrics" | HTTP path for the Prometheus exposition endpoint |
metrics_label_cardinality | enum | "strict" | strict (bucketed zoom, no tile coords), standard (alias of strict), verbose (full zoom 0..22) |
dashboard | bool | false | Collect per-request statistics for the admin analytics dashboard |
dashboard_recent_requests | usize | 200 | Requests kept in the dashboard's recent-requests list (max 10000) |
dashboard_heatmap_zoom | u8 | 10 | Zoom level (0-16) the dashboard heatmap aggregates requests to |
Analytics dashboard
With dashboard = true, the server keeps request statistics in memory and
the admin UI shows them at /admin/analytics, refreshed every 5 seconds:
- totals, cache hit rate, error rate and latency percentiles (p50/p95/p99);
- requests per minute for the last hour, and a latency histogram;
- per-source requests, hit rate, latency and average tile size;
- a request heatmap (tiles grouped into cells at
dashboard_heatmap_zoom) and requests per zoom level; - the most requested tiles and the most recent requests;
- the global tile cache size and capacity.
The data is bounded (10,000 tracked tiles, 20,000 heatmap cells, 24 hours of
per-minute counts) and is lost on restart or when a dashboard* setting
changes. The JSON behind the page is GET /__admin/stats on the
admin listener ([server].admin_bind), like the other /__admin
endpoints. Prometheus metrics (prometheus_bind) are separate and keep
working with the dashboard on or off.
[postgres] (feature: postgres)
Top-level PostgreSQL pool + per-source registries. See the Postgres + OutDB rasters guide.
[postgres]
connection_string = "postgres://user:pass@localhost:5432/db"
pool_size = 10
pool_wait_timeout_ms = 5000
pool_pre_warm = true
[postgres.cache]
size_mb = 256
ttl_seconds = 300
[[postgres.functions]]
id = "trip_aggregates"
schema = "public"
function = "mvt_trip_aggregates"
minzoom = 6
maxzoom = 14
[[postgres.tables]]
id = "buildings"
schema = "public"
table = "osm_buildings"
geometry_column = "geom"
minzoom = 12
maxzoom = 18
extent = 4096
buffer = 64
[postgres] root
| Key | Type | Default | Description |
|---|---|---|---|
connection_string | string | req | Postgres connection URI |
pool_size | usize | 20 | Connections in the pool |
pool_wait_timeout_ms | u64 | 30000 | Max ms to wait for a free connection |
pool_create_timeout_ms | u64 | 10000 | Max ms to wait when opening a new connection |
pool_recycle_timeout_ms | u64 | 5000 | Max ms to wait recycling a stale connection |
pool_pre_warm | bool | false | Open all pool connections at startup |
ssl_cert, ssl_key, ssl_root_cert | path? | (none) | mTLS / verify-full SSL material |
[postgres.cache]
| Key | Type | Default | Description |
|---|---|---|---|
size_mb | u64 | 256 | Max cache size for Postgres MVT tiles |
ttl_seconds | u64 | 300 | TTL per entry |
[[postgres.functions]]
| Key | Type | Default | Description |
|---|---|---|---|
id | string | req | Source ID |
schema | string | req | Postgres schema |
function | string | req | Function name (takes z/x/y, returns bytea) |
minzoom | u8 | 0 | Min zoom |
maxzoom | u8 | 22 | Max zoom |
bounds | f644? | (none) | Geographic bounds |
[[postgres.tables]]
| Key | Type | Default | Description |
|---|---|---|---|
id | string | req | Source ID |
schema | string | req | Postgres schema |
table | string | req | Table name |
geometry_column | string? | geom | Geometry column |
id_column | string? | (none) | Optional integer ID column carried into MVT features |
properties | string? | all | Column allow-list for MVT properties |
minzoom | u8 | 0 | Min zoom |
maxzoom | u8 | 22 | Max zoom |
extent | u32 | 4096 | MVT extent (4096 = standard) |
buffer | u32 | 64 | Per-tile geometry buffer in pixels (auto-set to 0 for POINT/MULTIPOINT) |
max_features | u32? | (none) | Hard cap on emitted features per tile |
writable | bool | false | Enable OGC API Features POST/PATCH/DELETE on this table |
[mcp] (feature: mcp)
See the MCP guide for transport + tool details.
[mcp]
enabled = true
auth_token = "supersecret" # bearer-token mode
cors_origins = ["https://claude.ai"]
[mcp.oauth]
enabled = false # mutually exclusive with auth_token
issuer_url = "https://tiles.example.com"
signing_key_path = "/etc/tileserver/mcp-jwt-key.pem"
approval_secret = "${MCP_APPROVAL_SECRET}" # operator code the consent page asks for
token_ttl_secs = 3600
# store_path = "/var/lib/tileserver-rs/oauth-store.sqlite" # requires mcp-persistence
[mcp] root
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Mount the /mcp Streamable HTTP service |
auth_token | string? | (none) | Static bearer token. Mutually exclusive with oauth.enabled = true. Startup fails if it is empty or an unset ${VAR}; under 16 characters logs a warning |
cors_origins | string | ["*"] | CORS allow-list for /mcp (lock down in production) |
[mcp.oauth]
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable RFC 7591 DCR + JWT RS256 OAuth flow |
issuer_url | string? | (none) | Required when enabled = true. Must match the public URL |
signing_key_path | path? | (none) | Required when enabled = true. RSA PKCS#8 PEM private key |
approval_secret | string? | (none) | Required when enabled = true. Operator code the consent page asks for before it issues an authorization code. Without it, anyone could approve themselves. Startup fails if it is empty or an unset ${VAR} |
token_ttl_secs | u64 | 3600 | Access-token TTL (clamped to 86400) |
store_path | path? | (none) | SQLite file persisting OAuth state across restarts. Requires mcp-persistence; fails fast without it |
Top-level fields
| Key | Type | Default | Description |
|---|---|---|---|
fonts | path? | (none) | Directory of PBF glyph files served at /fonts/{stack}/{range}.pbf |
files | path? | (none) | Directory of static files served at /files/{filename} |
Cloud sources
For PMTiles hosted on S3, GCS, or Azure, set the URL on path and pass
credentials via options:
[[sources]]
id = "global"
type = "pmtiles"
path = "s3://tiles-bucket/global.pmtiles"
[sources.options]
aws_region = "us-east-1"
aws_access_key_id = "..."
aws_secret_access_key = "..."
Keys in options are forwarded verbatim to
object_store::parse_url_opts.
See the object_store docs for the full list per backend.
SFTP sources
With the opt-in sftp feature, PMTiles can be served straight over SSH:
[[sources]]
id = "remote"
type = "pmtiles"
path = "sftp://[email protected]:22/var/data/planet.pmtiles"
[sources.options]
ssh_identity = "/home/tileserver/.ssh/id_ed25519" # optional override
Identity resolution precedence: per-source options.ssh_identity →
TILESERVER_SSH_IDENTITY env var → --ssh-identity CLI flag →
~/.ssh/id_ed25519 / ~/.ssh/id_rsa → SSH agent (SSH_AUTH_SOCK).
Host keys are verified against known_hosts (fail-closed); set a global
default via [sftp] known_hosts_path. See the
SFTP Sources guide for the full reference and security
guidance.
Cargo features
When building from source,
toggle feature flags to slim the binary or enable optional integrations.
The values below are the source of truth, mirrored from
crates/tileserver-rs/Cargo.toml.
| Feature | Default | Description |
|---|---|---|
postgres | Yes | PostgreSQL / PostGIS tile sources (tables + functions); OGC API Features; CQL2 filter |
raster | Yes | GDAL-based COG / VRT raster sources with colormap + band math |
mlt | Yes | MLT (MapLibre Tiles) ↔ MVT on-the-fly transcoding |
cloud | Yes | Cloud PMTiles (S3 / GCS / Azure / HTTPS) via object_store |
stac | Yes | STAC catalog source (implies raster) |
dem | Yes | DEM terrain-RGB tile encoding — Terrarium & Mapbox-RGB (implies raster) |
cel | Yes | Per-feature CEL filtering of vector tiles — see CEL Feature Filters |
sftp | No | PMTiles over SSH (sftp:// URLs) via russh — see SFTP Sources |
geoparquet | No | Serve tiles from GeoParquet files on-the-fly (Arrow + Parquet) |
duckdb | No | Embedded DuckDB SQL-driven tile source |
mcp | No | MCP server (stdio + Streamable HTTP) with optional OAuth |
mcp-persistence | No | Disk-backed SQLite store for the MCP OAuth state (implies mcp) |
frontend | No | Embed the Nuxt web UI into the binary (always-on for prebuilt artifacts) |
# Minimal API-only build (no GDAL, no Postgres, no MLT, no cloud):
cargo build --release --no-default-features
# Default features (postgres + raster + mlt + cloud + stac + dem + cel):
cargo build --release
# Everything, including the web UI and MCP server:
cargo build --release --all-features
The frontend feature is intentionally not a default feature so the
backend can be compiled without building the Nuxt frontend first.
Pre-built binaries, Docker images, and Homebrew bottles always ship with
it included.
Environment variables
Server (Rust binary)
| Variable | Type | Description |
|---|---|---|
TILESERVER_CONFIG | path | Equivalent to --config <FILE> |
TILESERVER_CACHE_DIR | path | Equivalent to --cache-dir <PATH> (overrides [cache].dir) |
TILESERVER_HOST | string | Equivalent to --host <HOST> |
TILESERVER_PORT | u16 | Equivalent to --port <PORT> |
TILESERVER_PUBLIC_URL | url | Equivalent to --public-url <URL> |
TILESERVER_UI | bool | Equivalent to --ui / --no-ui (string "true"/"false") |
TILESERVER_DATASET_CACHE_MAX_BYTES | u64 | Byte budget of the open-dataset cache (default 268435456, 256 MiB). Zero or an invalid value uses the default |
RUST_LOG | log spec | tracing_subscriber::EnvFilter directives, e.g. tileserver_rs=debug |
Client (Nuxt dev server)
These only affect pnpm dev:client. Production builds embed the SPA in
the Rust binary and serve same-origin, so no proxy is involved.
| Variable | Default | Description |
|---|---|---|
TILESERVER_BACKEND_PORT | 8080 | Port of the public Rust backend the Vite dev proxy forwards to |
TILESERVER_ADMIN_PORT | 8081 | Port of the admin backend ([server].admin_bind) for /__admin/* proxying |
The client env vars are deliberately not prefixed NUXT_. The
NUXT_* prefix is reserved by Nuxt for runtimeConfig auto-mapping;
these are build-time env vars read by nuxt.config.ts directly.
See Frontend development for more.