Install Agents locally
npx dimo list and npx dimo install list Agents and install Runtime and ACP on this machine. They open the same Host data directory (the same SQLite) as npx dimo serve. No port is bound. DIMO_TOKEN is unused. The HTTP service can stay down.
npx dimo agent list calls a Host that is already running and reads auth and enabled state for members already added. The commands on this page read and write the local Installation lock.
The first run still downloads the Host-family archive when needed, then forwards arguments to dimo-server. npx omits Starting Dimo Host for these utilities.
npx dimo list
List Agents this Host can install. The first group is the 13 built-in Agents. The second group is official ACP Registry entries whose identity sits outside the built-in table.
npx dimo listThe default read uses the Registry snapshot already cached on this machine. If it has never been refreshed, the ACP Registry section prints:
(refresh with `dimo-server list --refresh`)Each row has four columns: Agent id, display name, status, component detail. Example:
Built-in
claude_code Claude Code uninstalled adapter claude + claude-agent-acp
codex Codex ready adapter codex + codex-acp
...
ACP Registry
some-agent Some Agent available npxStatus comes from the local Installation lock:
ready: Runtime and ACP are in the lock;npx dimo servecan create a session with that Agent.needs_repair: a lock exists and components need repair.uninstalled: a built-in identity has no lock yet.available: the Registry has the entry; membership / lock are not in place yet.
The last column on a built-in row is topology, for example adapter claude + claude-agent-acp or native …. A Registry row lists distribution kinds: npx, uvx, binary, or a combination.
Pass the Agent id (for example claude_code) to npx dimo install.
npx dimo list --refresh
npx dimo list --refreshFetch a snapshot from the official ACP Registry, write it into the Host database, then print the catalog. Use this when a script needs the latest Registry entries. If refresh fails and a cache exists, the terminal prints registry refresh failed; using the cached snapshot and lists the cache. With no cache it fails: ACP Registry is unavailable.
npx dimo list --json
npx dimo list --json
npx dimo list --refresh --jsonPrint an indented JSON array. Each object has agent_id, display_name, description, group (built_in or registry), status, and detail. --refresh and --json combine.
npx dimo install
Install that Agent’s Runtime and ACP into the user environment. After a successful ACP handshake, write the Installation lock.
npx dimo install claude_code
npx dimo install claude_code --yes
npx dimo install claude_code -y
npx dimo install claude_code -y -g
npx dimo install some-agent --yes<agent-id> is required and comes from the first column of npx dimo list. A missing id prints Usage: dimo-server install <agent-id> [--yes] and exits non-zero. An unknown id prints unknown Agent …; run dimo-server list.
With a terminal and without --yes, the CLI prints the Plan (component id, distribution kind, source) and asks:
Install these user-environment packages? [y/N]y / yes continues. Any other answer cancels with installation canceled.
npx dimo install --yes / npx dimo install -y
npx dimo install claude_code --yes
npx dimo install claude_code -ySkip the prompt and install the Plan. When there is no terminal, --yes or -y is required; otherwise the CLI prints pass --yes to install without a prompt. Use this in CI, pipes, and any non-TTY script.
npx dimo install -g
npx dimo install claude_code -y -g
npx dimo install claude_code --yes --global-g and --global are accepted and ignored. Install already writes the user environment (the user npm prefix, uv tools, ~/.local/bin). There is no second global/local mode.
What install does
npx dimo install runs these steps:
- Open the Host data directory (
DIMO_DATA_DIRoverrides it) and use the same SQLite asnpx dimo serve. - A built-in Agent goes straight into the plan. A Registry Agent is added to membership first, then planned.
- Components already on PATH at a version at least as new as the lock are reused, with
Reusing … at …. When the whole plan is already satisfied, it printsUsing the user-environment CLI that already matches the locked versions. - Remaining components are written into the user environment:
npm install -g --prefix …,uv tool install, or a Binary download into~/.local/bin. - Handshake the installed ACP. On success, write the Installation lock and set lifecycle to
ready. A success line looks likeInstalled claude_code runtime … / ACP …. npx dimo servecan then create a session with that Agent.
Missing Node/npm prints npm was not found; install Node.js and npm first. Missing uv prints uv was not found; install uv first. The CLI uses the toolchain already on this machine. A hosted Node stays out of this path.
User-declared Agents are installed from desktop Settings → Agents. A retired identity fails this command.
Calling the binary
npx dimo forwards these arguments to dimo-server. With an extracted Host family you can invoke the binary directly:
dimo-server list
dimo-server list --refresh
dimo-server list --json
dimo-server install claude_code --yes
dimo-server agents list
dimo-server agents install codex
dimo-server agents install claude_code --yesdimo-server agents list matches dimo-server list. dimo-server agents install matches dimo-server install. On Windows the executable is dimo-server.exe.
Help
npx dimo help list
npx dimo list --help
npx dimo help install
npx dimo install --helpThese forms print usage only. The data directory stays closed. The Registry stays untouched.
Common failures
pass --yes to install without a prompt: there is no terminal. Add npx dimo install AGENT_ID --yes.
installation canceled: the confirm prompt was not answered with y / yes.
npm was not found; install Node.js and npm first / uv was not found; install uv first: install that toolchain on this machine, then rerun npx dimo install.
ACP Registry is empty: run npx dimo list --refresh first.
unknown Agent: the id is missing from the built-in table and from the current Registry snapshot. Run npx dimo list or npx dimo list --refresh.
could not open the Host data directory: the data directory could not be created or opened. Check DIMO_DATA_DIR and disk permissions.
ACP process exited before initialize: the installed ACP failed handshake. Inspect that Agent’s install output, fix it, then run npx dimo install again.