Chat locally

Start ChartCoach with Node.js 24 or later:

npx chartcoach

Alternatively, use Bun 1.4.2+ or Deno 2.9.6+:

bunx --bun chartcoach
deno x -A chartcoach

bunx chartcoach uses Node.js. Add --bun to run with Bun itself. Deno's -A grants access to storage, native catalog engines, the network, and worker processes. All three runners accept the same ChartCoach flags and environment variables.

Choose Model settings to connect a provider and select a model that supports images and tool calls. Upload a chart or ask about a visualization choice. Guideline citations open locally with their sources. Conversations and encrypted connections persist across restarts.

The default URL is http://127.0.0.1:4273. Press Ctrl+C to stop the server. Use --no-open to keep the browser closed and --port to choose another port.

Select a catalog

npx chartcoach chat --catalog ./my-catalog-release

Supply a release directory, an immutable release.json URL, or a catalog.json selection URL. The default official selection resolves to one verified release at startup. Changing the catalog requires restarting and selecting guidelines for a new conversation.

Use a local model

Configure the connection directly with flags:

npx chartcoach --provider compatible --base-url http://127.0.0.1:1234/v1 \
  --model my-vision-model --model-auth none

Replace my-vision-model with a model served by your endpoint. The same settings can come entirely from the environment:

export CHARTCOACH_PROVIDER=compatible
export CHARTCOACH_BASE_URL=http://127.0.0.1:1234/v1
export CHARTCOACH_MODEL=my-vision-model
export CHARTCOACH_MODEL_AUTH=none
npx chartcoach

For OpenAI, set OPENAI_API_KEY and run npx chartcoach --model my-vision-model. Use --provider anthropic with ANTHROPIC_API_KEY, or --provider google with GEMINI_API_KEY. --api-key-env selects another credential variable.

Questions, images, and retrieved guidance go to the chosen model endpoint. Query embeddings run locally. Browser-entered keys are encrypted in the data directory.

Configuration files are optional. --config ./chartcoach.json loads saved settings. Flags override environment variables, which override the selected JSON file. T3 Env validates environment values and identifies invalid variables without printing secrets. --data-dir chooses persistent storage.

Share a server

export CHARTCOACH_PASSWORD='choose-a-long-private-password'
npx chartcoach chat --host 0.0.0.0 --no-open \
  --public-url https://chat.example.org

Terminate HTTPS at a reverse proxy that preserves the public Host header and streams responses to port 4273. Sign in as chartcoach with the configured password. Each browser has its own history and model connections. The server operator can access stored credentials.

For containers, the repository includes infra/Dockerfile and infra/compose.yml:

export CHARTCOACH_PASSWORD='choose-a-long-private-password'
docker compose -f infra/compose.yml up --build -d

Compose publishes 127.0.0.1:4273 and retains data in named volumes. Set CHARTCOACH_PUBLIC_URL when accessing it through an HTTPS proxy. Model endpoints must be reachable from inside the container.

The chat README lists all configuration fields, environment variables, storage paths, and deployment options.

Diagnose startup

npx chartcoach doctor --json

The report includes software and catalog identity, model availability, storage locations, and native DuckDB loading. Credentials are excluded.

If Bun or Deno cannot find an executable, check which package version it selected. A release-age policy can temporarily select the 0.0.0 name reservation, which has no CLI. Pin an exact released version to see the age-policy error, then wait until it is eligible or adjust your runner's policy.