Configuration

Calculon resolves configuration from three levels with increasing priority:

Hardcoded defaults < Config file < CLI arguments

CLI arguments

calculon [OPTIONS]

Options:
  -t, --tile-dir <TILE_DIR>          Path to the tile directory
      --tile-archive <PATH_OR_URL>   .gphx archive instead of a tile dir (local path or http(s) URL)
      --tile-cache-dir <DIR>         Disk cache of decompressed tiles, mapped back from disk
                                     (keeps resident memory at tile-directory levels)
  -b, --bind <BIND>                  Address to bind (default: 0.0.0.0:8002)
      --cache-size <CACHE_SIZE>      Shared tile cache budget in MB (default: 4096, archives only)
  -c, --config <CONFIG>              Path to config file (default: calculon.toml in CWD)

A tile source is required: exactly one of --tile-dir or --tile-archive. Setting both is an error rather than a silent preference, so a typo cannot leave the server quietly pointed at the wrong data. See Tile Archives for what an archive is and when to use one.

Config file

Calculon looks for calculon.toml in the current working directory by default. Use --config to specify a different path.

tile_dir = "/data/valhalla/tiles"

# Or read a .gphx archive instead: a local path, or an http(s) URL served with
# range requests (e.g. S3/CloudFront):
# tile_archive = "https://tiles.example.com/france-2026-08.gphx"
# tile_cache_dir = "/var/cache/calculon/tiles"

bind = "0.0.0.0:8002"

# Shared tile cache budget in MB. Bounds archive-backed sources only: directory
# tiles are memory-mapped and bounded by the OS page cache.
cache_size = 4096

[costing.auto]
use_highways = 0.5
use_tolls = 0.5
top_speed = 140

[costing.bicycle]
cycling_speed = 20.0
use_roads = 0.5

[costing.pedestrian]
walking_speed = 5.1

Values in [costing.*] sections set server-wide defaults that apply to every request unless overridden by per-request costing_options.

Auto (driving) options

Option	Range	Default	Description
`use_highways`	0.0 - 1.0	0.5	Highway preference (0 = avoid, 1 = prefer)
`use_tolls`	0.0 - 1.0	0.5	Toll road preference (0 = avoid, 1 = prefer)
`use_distance`	0.0 - 1.0	0.0	Distance vs time trade-off (0 = fastest, 1 = shortest)
`top_speed`	10 - 252	140	Maximum speed in kph
`toll_booth_cost`	0+	15.0	Seconds added at toll booths
`destination_only_penalty`	0+	600.0	Penalty for destination-only edges (seconds)
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`signal_penalty`	0+	0.5	Traffic signal penalty (seconds)
`surface_factor`	0.0 - 1.0	0.5	Surface quality impact on cost
`service_penalty`	0+	75.0	Penalty for service roads (seconds)
`shortest`	bool	false	Pure distance-based routing

Bicycle options

Option	Range	Default	Description
`cycling_speed`	5 - 60	18.0	Base cycling speed in kph
`use_roads`	0.0 - 1.0	0.25	Road preference (0 = avoid roads, 1 = prefer)
`use_hills`	0.0 - 1.0	0.25	Hill preference (0 = avoid, 1 = prefer)
`avoid_bad_surfaces`	0.0 - 1.0	0.25	Bad surface avoidance penalty
`use_living_streets`	0.0 - 1.0	0.5	Living street preference
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`gate_penalty`	0+	300.0	Penalty for passing through a gate (seconds)
`shortest`	bool	false	Pure distance-based routing

Pedestrian options

Option	Range	Default	Description
`walking_speed`	0.5 - 25	5.1	Base walking speed in kph
`walkway_factor`	0.1+	1.0	Cost factor for walkways (lower = prefer)
`sidewalk_factor`	0.1+	1.0	Cost factor when sidewalk present (lower = prefer)
`alley_factor`	0.1+	2.0	Cost factor for alleys (higher = avoid)
`driveway_factor`	0.1+	5.0	Cost factor for driveways (higher = avoid)
`step_penalty`	0+	30.0	Penalty for steps (seconds)
`use_hills`	0.0 - 1.0	0.5	Hill preference (0 = avoid, 1 = prefer)
`max_hiking_difficulty`	0 - 6	1	Maximum SAC hiking scale
`use_lit`	0.0 - 1.0	0.0	Preference for lit roads (0 = don't care)
`use_living_streets`	0.0 - 1.0	0.6	Living street preference
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`shortest`	bool	false	Pure distance-based routing

Option merge

Options are merged in order: hardcoded defaults < config file < per-request costing_options.

Config filePer-request override

[costing.auto]
use_highways = 0.8
use_tolls = 0.2

{
  "locations": [...],
  "costing": "auto",
  "costing_options": {
    "auto": {
      "use_highways": 0.3
    }
  }
}

In this example, use_highways is 0.3 (request wins), use_tolls is 0.2 (config wins over hardcoded 0.5), and all other options use hardcoded defaults.