Config Files and State

This page is for lookup, not onboarding. If you are still setting things up for the first time, go back to the guided chapters.

Current live state

Location	Purpose
~/.config/track/cli.json	CLI-side settings such as the backend URL and local model override.
backend state directory	Stores the live SQLite database plus managed remote-agent secrets.
backend state track.sqlite	Registered projects, tasks, runs, reviews, settings, and migration status.
backend state remote-agent/id_ed25519	Managed SSH private key used by the backend for remote work.
backend state remote-agent/known_hosts	Managed known_hosts file for remote SSH calls.

Where the backend state lives

When you run the shipped Docker Compose setup, the backend state bind-mounts from:

${HOME}/.track/backend

Compose creates that host directory if it is missing.

When you run the backend outside Docker, the default state directory is:

~/.track/backend

You can override that with TRACK_STATE_DIR.

CLI config example

The smallest useful ~/.config/track/cli.json file looks like this:

{
  "backendBaseUrl": "http://127.0.0.1:3210"
}

With a custom local model override:

{
  "backendBaseUrl": "http://127.0.0.1:3210",
  "llamaCpp": {
    "modelPath": "/home/user/.models/custom.gguf"
  }
}

Legacy material

Older versions of track used ~/.config/track/config.json and a ~/.track data layout more directly.

The current code still knows how to import that legacy material, but it is no longer the primary live configuration surface. If you see older setup notes talking about config.json as the main place to edit everything, treat them as migration-era documentation.