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:

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 , , , , , and .

Precedence

When the same value is supplied in multiple places, later sources override earlier ones:

1. Hard-coded defaults (lowest priority)
2. Config file in TOML or YAML (--config)
3. Environment variables (TILESERVER_*)
4. CLI flags (highest priority)

Config file lookup

If --config is not provided, the server resolves what to load in this order:

1. --config <FILE> — explicit config path (fails if the file does not exist)
2. Positional PATH — auto-detect sources/styles from that path (see )
3. Default locations, tried in order: ./config.toml, ./config.yaml, ./config.yml, then /etc/tileserver-rs/config.{toml,yaml,yml}
4. CWD auto-detect — scan the current directory for .pmtiles, .mbtiles, style.json, and font directories

CLI flags

tileserver-rs [OPTIONS] [PATH] [SUBCOMMAND]

Subcommands

[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
disable_render = false                     # optional — turn off raster routes
disable_ogc = false                        # optional — turn off OGC API routes

CORS origin patterns

The cors_origins list accepts three syntaxes, dispatched per entry:

[server]
cors_origins = [
  "https://example.com",
  "*.cdn.example.com",
  "preview-*.example.com",
  "/^https://.+\\.team-[a-z0-9]+\\.app\\.example\\.com$/",
]

Notes:

1. Entries are tried in order; the first match short-circuits per request.
2. A list containing "*" ALWAYS resolves to wildcard regardless of other entries — that is the existing semantics, preserved.
3. Pure-literal lists (no *, no /.../) use the same allocation-free AllowOrigin::list fast-path as before. Adding a glob or regex switches the layer to AllowOrigin::predicate.
4. Invalid regex (e.g. unbalanced [) fails fast at startup with the offending entry quoted in the error.
5. Glob entries are compiled by anchoring with ^...$ and replacing * with .* — so *.x.com matches foo.x.com and https://foo.x.com, but NOT x.com (no leading subdomain) or foo.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:

[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:

1. Header names must conform to RFC 7230 token grammar (alphanumeric + !#$%&'*+-.^_\|~`).
2. The transport-managed headers Content-Length, Transfer-Encoding, Date, Connection are rejected at startup — the server fails fast.
3. An empty string value ("X-Foo" = "") removes any pre-existing X-Foo header from outgoing responses.
4. User values are overriding — they win over anything an upstream middleware emits.
5. 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

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:

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 .

type = "cog" / type = "vrt" (feature: raster)

type = "geoparquet" (feature: geoparquet)

type = "duckdb" (feature: duckdb)

Same layer_name, geometry_column, query as GeoParquet.

type = "stac" (feature: stac)

Pixel selection (feature: stac or raster)

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"

[[styles]]

[[styles]]
id = "osm-bright"
path = "/data/styles/osm-bright/style.json"
name = "OSM Bright"

[render]

Native MapLibre raster renderer pool. See .

[render]
pool_size = 4
render_timeout_secs = 30

[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

[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

How negotiation works per request:

1. If the source's stored encoding is already in the client's Accept-Encoding set, it is served as-is (no decode/re-encode).
2. 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.
3. 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.

[raster] (feature: raster)

[raster]
default_resampling = "bilinear"
tile_size = 256

[telemetry]

OpenTelemetry tracing + Prometheus metrics. See .

[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"

[postgres] (feature: postgres)

Top-level PostgreSQL pool + per-source registries. See the .

[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

[postgres.cache]

[[postgres.functions]]

[[postgres.tables]]

[mcp] (feature: mcp)

See the 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"
token_ttl_secs = 3600

[mcp] root

[mcp.oauth]

Top-level fields

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.

Cargo features

When , 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.

# 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):
cargo build --release

# Everything, including the web UI and MCP server:
cargo build --release --all-features

Environment variables

Server (Rust binary)

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.

See for more.