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 their public pages with sources. Conversations and encrypted connections persist across restarts.

The home page starts a new chat. Its first message saves the conversation at /chat/{threadId}. History links, browser back and forward, and refresh use that same address. Opening it requires the same browser's cookie and any configured server sign-in. Guidelines has its own page: /guidelines for a new chat, or /chat/{threadId}/guidelines for a saved conversation. Refreshing the latter restores that conversation's selection.

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.

Launch from an env fileCopy Anchor Link

OpenRouter routes requests to a chosen model provider. Create chat.env with a model that supports images and tool calls:

CHARTCOACH_TEXT_PROVIDER=openrouter
CHARTCOACH_TEXT_MODEL=your-vision-model
CHARTCOACH_TEXT_API_KEY=your-private-key
CHARTCOACH_OPEN=false
CHARTCOACH_GUIDELINE_URL_TEMPLATE=https://chartcoach.dev/guidelines/{id}

CHARTCOACH_TRACING=true
LANGFUSE_PUBLIC_KEY=your-public-project-key
LANGFUSE_SECRET_KEY=your-secret-project-key
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Use your Langfuse project's host and keys to record model and tool traces. Traces can include messages and images. Keep this file private and outside version control. Set CHARTCOACH_TRACING=false when operating with tracing disabled.

npx chartcoach doctor --env-file ./chat.env --json
npx chartcoach chat --env-file ./chat.env

The provider preset supplies OpenRouter's API endpoint. An explicitly selected file overrides inherited settings. The app starts at http://127.0.0.1:4273, and guideline links open https://chartcoach.dev/guidelines/{id}. Changing CHARTCOACH_GUIDELINE_URL_TEMPLATE changes citation, evidence, and catalog links. The template requires one URL-encoded {id} in its path. Preview images use /og.png below that URL, or CHARTCOACH_GUIDELINE_IMAGE_URL_TEMPLATE for a separate image location.

For a GitHub preview, replace chartcoach after npx --yes with the release's .tgz download URL. The same chat --env-file ./chat.env arguments apply.

Select a catalogCopy Anchor Link

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 modelCopy Anchor Link

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_TEXT_PROVIDER=compatible
export CHARTCOACH_TEXT_BASE_URL=http://127.0.0.1:1234/v1
export CHARTCOACH_TEXT_MODEL=my-vision-model
export CHARTCOACH_TEXT_AUTH=none
npx chartcoach

Set CHARTCOACH_TEXT_API_KEY for an authenticated text connection. Native OpenAI, Anthropic, and Gemini adapters use the same dedicated key setting. CHARTCOACH_TEXT_API_KEY_ENV selects another credential variable.

The model connection guide owns the complete shared text and embedding settings and profile-build workflow. Both launchers load .env from their working directory, or an explicit --env-file.

Questions, images, and retrieved guidance go to the chosen model endpoint. Query embeddings run locally by default; a configured compatible embedding connection uses its own endpoint and must match the selected catalog profile. Browser-entered keys are encrypted in the data directory.

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

Share a serverCopy Anchor Link

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 a public deployment without sign-in, pass --public or set CHARTCOACH_PUBLIC=true instead of a password. Every visitor can then use the configured server model, so cap its spend with the provider.

For containers, the repository includes infra/chat.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.

To show chartcoach in an iframe on another page, such as a slide deck, list that page's origin in CHARTCOACH_EMBED_ORIGINS. A password-protected server opens in a frame with CHARTCOACH_EMBED_KEY. The chat README covers sandboxed hosts and the cookie scope.

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

Diagnose startupCopy Anchor Link

npx chartcoach doctor --json

The report includes software and catalog identity, model availability, storage locations, guideline URL templates, tracing configuration, 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.