Installation

Routeframe ships as a single self-contained binary. No runtime dependencies, no Python required for basic use.

Supported platforms

Install

$ curl -fsSL https://www.routeframe.com/install.sh | bash

$ curl -fsSL https://www.routeframe.com/install.sh | bash

# or with sudo explicitly
$ curl -fsSL https://www.routeframe.com/install.sh | sudo bash

# PowerShell
PS> Invoke-WebRequest -Uri https://www.routeframe.com/releases/latest/routeframe-windows-amd64.exe `
     -OutFile routeframe.exe
PS> Move-Item routeframe.exe C:\Windows\System32\routeframe.exe

Verify the installation

$ routeframe --version
routeframe version v0.7.3

$ routeframe --help
Run time series foundation models locally.

Usage:
  routeframe [flags]
  routeframe [command]

Available Commands:
  auto        Probe pulled models on your data and recommend the winner
  env         Manage the Python runtime environment
  finetune    Fine-tune a model on your data
  forecast    Forecast from a file or URL
  list        List downloaded models
  monitor     Live forecast monitoring with chart
  pull        Download a model from the registry
  rm          Remove a downloaded model
  run         Run a time series forecast
  serve       Start the Routeframe API server
  upgrade     Upgrade routeframe to the latest version

Quick start

Once installed, pull a model and run your first forecast. routeframe pull toto with no flags grabs the latest version and smallest parameter count -- currently Toto 2.0 / 4M (~16 MB).

# 1. Download the default Toto model (16 MB, Toto 2.0 / 4M)
$ routeframe pull toto
Pulling toto  2.0 4m f32  16 MB
  [██████████████████████████████] 16.0 / 16 MB  12.3 MB/s  100%
  SHA256 verified ✓
  Saved to ~/.routeframe/models/toto.gguf

# 2. Run a forecast
$ routeframe run toto --input "45,48,52,49,55,58,62,59,64,67" --horizon 4
Model:   Toto (toto)
Input:   10 timesteps, 1 variate
Horizon: 4 steps

Predictions:
  t+1: 68.4200
  t+2: 71.0500
  t+3: 69.8800
  t+4: 72.3100

# 3. Have a CSV but unsure which model to use? Auto-select.
# Probes every pulled model on a held-out portion of your data,
# adds daily/weekly naive baselines, and prints a recommendation.
$ routeframe auto data.csv --column sales --horizon 24

# 4. Or open the interactive TUI
$ routeframe

Where models are stored

Downloaded models are saved to ~/.routeframe/models/. This directory is preserved across upgrades.

$ ls ~/.routeframe/models/
chronos2.gguf   timesfm.gguf   toto.gguf

$ routeframe list
NAME       ARCH       VERSION         SIZE
toto       toto       2.0/4m/f32      16 MB
toto       toto       2.0/1b/f32      3.9 GB
timesfm    timesfm    -               441.6 MB
chronos2   chronos2   -               228.0 MB

Each variant of a model gets its own row -- pulling a new variant of toto doesn't replace the others.

Upgrading

Update to the latest version with a single command. The binary is replaced in-place; models are not affected.

$ routeframe upgrade
Upgrading routeframe...
Routeframe installed successfully!

Uninstalling

# Remove the binary
$ sudo rm $(which routeframe)

# Remove downloaded models and settings (optional)
$ rm -rf ~/.routeframe

Python environment (optional)

The vast majority of Routeframe commands need no Python at all. The native Go engine handles:

• All inference (run, serve, monitor, TUI)
• Auto-select (auto) on CSV / TSV / Parquet / SQLite / HTTP URLs
• Batch forecasting (forecast) on CSV / TSV / Parquet / SQLite / HTTP URLs
• Model management (pull, list, rm)

Python is only needed for two things:

• Reading DuckDB files (rare; users typically already have Python)
• The finetune command (training PyTorch + LoRA pipelines)

First time you trigger a Python-dependent command

Routeframe checks what Python environment you already have, then asks how you want to install the dependencies. If you have an active virtual environment ($VIRTUAL_ENV or $CONDA_PREFIX), it offers to use that:

$ routeframe finetune --data sales.csv --targets revenue --output my-model

Fine-tuning needs the following Python packages: torch, lightning, peft, ...

Detected active Python environment: /Users/you/proj/.venv (venv)

How would you like to install the packages?
  [1] Install into your active env (.venv) -- fast if dependencies overlap.
  [2] Install Routeframe's managed env (~/.routeframe/python, ~2 GB, isolated).

Choose [1/2]:

If you pick [1], Routeframe runs pip install against your active venv. Faster, reuses anything you already have, and doesn't double-download PyTorch. If pip fails (PEP 668 lock, version conflict, etc.), Routeframe falls back to option 2 with a clear explanation.

If you pick [2], Routeframe creates an isolated environment at ~/.routeframe/python/ using uv (auto-installed if missing). Predictable, version-pinned, deletable with one rm. Your system Python is never touched.

The choice is cached in ~/.routeframe/python_choice.json, so subsequent commands use the same setup without prompting again. To reset, delete that file.

If no active environment is detected

Routeframe defaults to creating the managed environment, since installing scientific packages directly into bare system Python is blocked on most modern Linux distros (PEP 668) and risks breaking your other projects:

$ routeframe finetune --data sales.csv --targets revenue --output my-model

No active Python virtual environment detected.

Fine-tuning will install Routeframe's managed env at:
  ~/.routeframe/python (~2 GB, one-time, ~3 min)

Continue? [Y/n]

You can also set up ahead of time:

$ routeframe env setup