Environment and troubleshooting
Variables read when starting the Host
These apply when running npx dimo or npx dimo serve.
DIMO_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.
DIMO_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/DimoADE/Dimo/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.
DIMO_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, dimo-server, web/). When set, download is skipped.
DIMO_GITHUB_REPO: GitHub owner/name, default DimoADE/Dimo.
DIMO_STATIC_ROOT: Web UI static file root. npx dimo points it at packaged web/. When you start dimo-server yourself and need the browser UI, point this at a web/ tree.
DIMO_SERVER_ALLOW_LAN: set to 1 and even npx dimo (loopback start) listens on every NIC. npx dimo serve --local on the command line still binds loopback only.
DIMO_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.
DIMO_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.
DIMO_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.
DIMO_DATA_DIR: Host data directory. npx dimo serve, npx dimo list, and npx dimo install share this SQLite. Unset, the machine default data directory is used.
Variables read by control commands
DIMO_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.
DIMO_TOKEN: Bearer token, required. Missing it raises DIMO_TOKEN is required. Copy it from the Token block of npx dimo serve, or from desktop Settings → Remote connection.
Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.
Common failures
Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.
Host family download failed: network, firewall, or a bad tag. Check DIMO_HOST_FAMILY_TAG and open the Release page for dimo-host-family-<platform>.tar.gz.
Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.dimo/host-family/<tag>/ and retry, or point at a verified DIMO_HOST_FAMILY_DIR.
Host family is missing dimo-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.
DIMO_TOKEN is required: the token is unset. Run npx dimo serve and copy from the terminal, or copy from the desktop remote-connection page.
Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx dimo conversation show / npx dimo workflow show.
Missing required --x: a required flag is absent. Compare with npx dimo help conversation (or the matching resource).
Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx dimo plugin pack again.
Port in use: switch to npx dimo serve --port 18080, or stop the process holding 17891.
pass --yes to install without a prompt: npx dimo install ran without a terminal and without --yes. Use npx dimo install AGENT_ID --yes.
npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx dimo install. Full write-up: Install Agents locally.
npx dimo help
npx dimo --version