Docs

CLI reference

Usage

text

tokmine [start] [flags]    discover local models and open the tunnel (default)
tokmine install [runner]   install a local model server and a model (ollama, llamacpp)
tokmine login [--token T]  store an agent token (or set TOKMINE_TOKEN)
tokmine endpoints          list your endpoints and their machines
tokmine logout             remove the stored token
tokmine status             show configuration, providers and reachability
tokmine models             list discovered models
tokmine version

tm is an alias for tokmine and takes the same arguments.

Commands

Command	Description
`tokmine [start]`	Default. Discover local model servers, open the tunnel, print the public URL and stay running.
`tokmine install [runner\|family]`	Install a local model server (`ollama` by default, or `llamacpp`) and pull a model that fits this machine. Families such as `glm` or `qwen` pick a model from that family. Options below. See Install a local model.
`tokmine login [--token T]`	Store your agent token in the config file. Without `--token` it reads `TOKMINE_TOKEN`, then prompts. Also saves `--name`, `--endpoint` and `--server` if given.
`tokmine endpoints`	List your workspace's endpoints: name, slug, public URL and machines online/total. Needs a logged-in machine. See Static endpoints.
`tokmine logout`	Remove the stored token. The machine id is kept.
`tokmine status`	Show version, mode (anonymous or authenticated), machine name and id, endpoint and whether it is reachable, config path, and discovered providers.
`tokmine models`	One-off scan: list discovered providers, dialects and models.
`tokmine update`	Not available yet. Re-run the install command to upgrade.
`tokmine version`	Print version, commit, build date and OS/arch.
`tokmine help`	Print usage.

Flags

For start, status and models:

Flag	Description
`--name <name>`	Machine name. Defaults to the hostname.
`--provider <url>`	Add a model server manually (for example `http://gpu-box:8000`). Repeatable. See runners.
`--dialect <d>`	Force the dialect of `--provider` servers: `openai`, `anthropic`, `gemini` or `ollama`.
`--endpoint <slug>`, `-e`	Join this endpoint (a static endpoint of your workspace, or `default`). Authenticated machines only. Without it the CLI auto-selects your only static endpoint, asks you to choose among several, or uses the default endpoint. See Static endpoints.
`--server <url>`	Override the Tokmine server (default `https://tunnel.tokmine.ai`). For development. This was `--endpoint <url>` in earlier versions; a URL passed to `--endpoint` or `TOKMINE_ENDPOINT` still works as the server but prints a deprecation notice.
`--app-url <url>`	Web portal used for the chat link (default `https://app.tokmine.ai`). See Browser chat.
`--no-discover`	Skip probing the well-known local ports. Only `--provider` servers are used.
`--json`	Emit machine-readable events, one JSON object per line.
`--verbose`	More output. Tokens are never logged.
`--token <t>`	Agent token (`login`).

Flags for `install`

Flag	Description
`--model <name>`	Pull this model instead of choosing one from RAM and GPU.
`--method <m>`	`auto` (default), `script`, `brew`, `winget` or `docker`.
`--yes`	Skip confirmation prompts, including before running an installer script.
`--dry-run`	Show the plan and change nothing.
Without a terminal, `--yes` is required. Details in Install a local model.

Environment variables

Precedence is flags, then environment, then the config file.

`TOKMINE_TOKEN`	Agent token. Alternative to `tokmine login`.
`TOKMINE_NAME`	Machine name.
`TOKMINE_PROVIDERS`	Comma or space separated provider URLs.
`TOKMINE_DIALECT`	Forced dialect for manual providers.
`TOKMINE_ENDPOINT`	Endpoint slug to join, same as `--endpoint`.
`TOKMINE_SERVER`	Tokmine server URL override (formerly `TOKMINE_ENDPOINT`).
`TOKMINE_APP_URL`	Web portal URL for the chat link. Can also be set as `appUrl` in the config file.
`TOKMINE_CONFIG_DIR`	Directory for the config and session files.
`OLLAMA_HOST`	Honoured during discovery.
`NO_COLOR`	Disable coloured output.
`HTTPS_PROXY`, `HTTP_PROXY`	Standard proxy settings.

Config file

Location: ~/.config/tokmine/config.json on Linux and macOS (or $XDG_CONFIG_HOME/tokmine), %APPDATA%\tokmine\config.json on Windows, or $TOKMINE_CONFIG_DIR/config.json. It is written atomically with owner-only permissions.

json

{
  "token": "<agent-token>",
  "machineId": "3f0c...",
  "name": "gpu-box-1",
  "endpoint": "acme-prod",
  "server": "https://tunnel.tokmine.ai",
  "appUrl": "https://app.tokmine.ai",
  "providers": ["http://gpu-box:8000"],
  "dialect": "openai"
}

machineId is generated on first run and identifies this machine across restarts. endpoint is the endpoint slug to join and server the Tokmine server URL (before this release, endpoint held the server URL). An anonymous session is kept next to it in anon-session.json and deleted when it expires.

Behaviour

Reconnects automatically after network loss or sleep, with exponential backoff and jitter (1 to 30 seconds). The delay resets once a connection is stable.
Fatal errors stop it rather than retrying: rejected agent token, plan limit reached, an endpoint that does not exist, was disabled or deleted, or needs a paid plan, an outdated CLI, or another process using the same machine id. The message says what to do.
Anonymous sessions resume across restarts and end after 30 minutes, when the CLI exits.
Prints a chat link once online (and when an anonymous session resumes), to try the endpoint in the browser. --json adds it to the online event as chatUrl. See Browser chat.
With no local model server (and no --provider), suggests tokmine install ollama and, in an interactive terminal, asks Install Ollama now? [y/N] before connecting. A server with no models gets a tokmine install --model hint.
Endpoints (logged-in machines): the CLI prints the endpoint name and public URL on start and in status. If the endpoint is deleted or disabled while it runs, or your plan no longer includes static endpoints, the CLI prints why, does not reconnect and exits with code 1; pick another with --endpoint. The chat link becomes https://app.tokmine.ai/chat?endpoint=<slug> (no token in it).
Reports CPU, RAM and GPU load so traffic can be balanced across machines.
Ctrl-C (or SIGTERM) drains in-flight requests before exiting.

Exit codes

`0`	Normal exit (including Ctrl-C) or a successful command.
`1`	Runtime error or fatal tunnel error (bad token, plan limit, endpoint not found, disabled or not allowed, session refused).
`2`	Invalid usage: unknown command, flag, dialect or provider URL, or several endpoints and none chosen in a non-interactive run.

Flags and commands may change until the first stable release.