Skip to content

Command line

handler is the command line client of handlerd, the daemon that runs your agents. The web UI is where you set up projects, contexts and folders; the command line runs agents from a shell, an editor or a script, and manages the rest. Each command has its own page, linked below; handler -h and handler <command> -h print the same in short.

How the commands are organised

  • Working with an agent is a verb: handler run, attach, terminal, acp. These are the commands you type every day.
  • Everything you manage is a noun followed by what to do with it: handler session list, handler agent show ID, handler provider add …. The same words come back everywhere: list, show, add, rm.
  • Handler itself: setup, daemon, ui; handler --version prints the version installed, even when the daemon is down.

Three ways to work with an agent

run terminal acp
What you get Handler's terminal client the harness's own UI (Claude Code's, Codex's…) the agent inside your editor (Zed)
A session, kept by the daemon yes: survives the terminal, shown in the web UI and on your phone no: gone when you exit in a project: yes; elsewhere: no
Come back to it attach, even once stopped --resume, the harness's own your editor's threads

All three run the agent in its own container, seeing only its folder.

Which agent runs: the folder decides

  • In a project's folder (or below), commands use that project's agents with their settings: the one you name, or the one on the account you name, or the default agent.
  • Elsewhere, name an account or a provider: Handler makes an agent outside projects for that folder, from a safe preset. The same command in the same folder finds the same agent again.

Projects are created in the web UI. project and agent list what exists.

Rules every command follows

  • An option is never ignored. When an agent option differs from the agent's settings (--network open on a filtered agent), Handler says so and asks "Save this to the agent?". Yes saves it, no starts nothing. Without a terminal (an editor, a script): --save, else it is refused.
  • Contexts are enforced. An account or provider not made for the project's context (a personal account in a Work project) is refused. --anyway runs it there outside the project, after you type yes: the only thing the command line can do that the web UI cannot.
  • What widens the sandbox is said. --network open, --log-only and --containers are printed on stderr when the agent starts.

I want to…
install and start Handler handler setup
open the web UI handler ui
connect my Claude, ChatGPT or Mistral subscription handler account add
use an API key or a local model handler provider add
ask an agent something in this folder handler run
use one of a project's agents by name handler run NAME
keep typing claude, but sandboxed handler terminal
get back to a session, running or stopped handler attach
follow a session from my phone handler session share
use an agent in Zed handler acp
give an agent a browser or the Shopify CLI handler addon add, handler binding list
find out why an agent cannot reach a host handler agent network
update Claude Code in the images handler image rebuild
run something each time a session stops handler automation

Every command

Working with an agent

  • run: a session in the current folder
  • attach: back to a session, running or stopped
  • terminal: the harness's own UI, sandboxed
  • acp: an agent for your editor
  • Agent options: what run, terminal and acp take to set up the agent

What runs

Model access

  • account list | add | token | login | import | rm: subscriptions
  • provider list | templates | add | rm: API keys and local models
  • secret list | set | rm: the secret store

What an agent can get

  • addon list | catalog | add | rm
  • binding list: addons with their settings and secrets
  • knowledge list: knowledge folders

Images, apps, automations

  • image list | rebuild
  • app list | add | deploy | rollback | open | shortcut | stop | log | secret | rm
  • automation list | examples | new | show | try | enable | disable | delete | runs | log | cancel
  • inbox: what Handler told you

Handler itself

  • setup: start the daemon, check the machine, build the images
  • daemon status | install | uninstall | log
  • ui: open the web UI

Environment

Variable
HANDLER_URL the daemon's address (default http://127.0.0.1:<HANDLER_PORT>)
HANDLER_PORT its port, when HANDLER_URL is not set
HANDLER_CONFIG_DIR where the UI's access token is read (default ~/.config/handler-ai)
HANDLER_ACP_CLIENT another terminal client for sessions, {bridge} standing for handler attach --stdio <session>: HANDLER_ACP_CLIENT='toad acp "{bridge}"'
HANDLER_APP_BROWSER how app open opens an app: firefox, chromium or default