The Octavus Agent CLI (the octoagent command, published as @octavus/agent) runs one of your Octavus Agents on a Linux machine you control, with that machine as the agent's computer. The agent itself, its model, tools, skills, memory, and connections, keeps running on Octavus exactly as it does everywhere else; the CLI drives the browser, the screen, the files, and the shell on the machine you run it on. Every run is a normal Thread on the agent in the dashboard, live while it runs and afterward.
You need:
- A Linux machine with Node.js 22.23.4 or later, 24.22.1 or later, or 26.12.1 or later. The installer checks and tells you which release to upgrade to.
- An agent in your organization that you have access to, and an API key for it (see below).
- For the browser and computer-use tools, the display stack the installer sets up. On a Debian or Ubuntu machine it installs everything itself; elsewhere it tells you what to install.
When to use it
Reach for the CLI when the agent should act on a specific machine: a server, a CI runner, a benchmark harness, anything shaped like "install a tool, give it a key, run a prompt". A run is triggered locally and lasts for one prompt: the CLI starts the run, is the agent's computer while it works, and exits when it is done.
To drive an agent on its own managed computer over the network instead, use the Workforce Agents API. Both use the same API key.
Set up the agent
- In the dashboard, open the agent and go to Settings -> Computer.
- Open More options, choose Your own machine (CLI), and confirm.
- Go to Settings -> API and create an API key for the agent. It starts with
oct_agt_and is shown only once; see Create an API key.
An agent set to run from the CLI has no managed computer. Its manual chat, scheduled tasks, and notifications are turned off, and it is driven only from the CLI; its threads stay visible in the dashboard. Runs use your machine's own network identity. Switch the computer back in the same settings at any time.
Install
curl -fsSL https://octavus.ai/install/agent-cli.sh | shThe installer checks your Node.js release, installs the prerequisites a full agent computer needs on a Debian or Ubuntu machine (a headless display with Xvfb and a window manager, the AT-SPI accessibility bus, and the libraries Chrome needs), installs Chrome for Testing under ~/.octavus/browsers, and then installs the package. On another distribution it names the packages to install yourself. An agent that only uses the shell and the filesystem needs none of the display stack.
If you already have the prerequisites, install the package directly:
npm install -g @octavus/agentThe browser tools need Chrome for Testing, Google's automation build. Branded Google Chrome and the Chromium snap cannot load the automation extension. If you installed Chrome for Testing yourself, point the CLI at it with --chrome-path or OCTAVUS_CHROME_PATH.
Run your first task
Store the agent's API key once, then run a prompt from the directory the agent should work in:
octoagent auth --api-key oct_agt_...
cd ~/projects/my-task
octoagent run "Summarize the README and open the repo's homepage in the browser."The CLI prints a link to the thread as soon as the run starts, so you can watch it live in the dashboard, and again when the run ends.
- The working directory is the agent's workspace: its filesystem and shell root. Override it with
--workdir. Running with the workspace at your home directory or/needs--force. - Durable data lives under
~/.octavus/<env>/<agentId>/, never in the workspace: the browser profile, so logins persist from run to run, and cached skills. - In CI, set
OCTAVUS_API_KEYin the environment instead of runningoctoagent auth. An explicit--api-keywins over the variable, which wins over the stored key.
Commands
octoagent run "<prompt>"
Run one prompt to completion and exit.
| Flag | Description |
|---|---|
--workdir <dir> | The agent's filesystem and shell root (default: the current directory) |
--api-key <oct_agt_...> | Use this key for this run instead of the stored one |
--chrome-path <path> | Chrome for Testing to use (default: OCTAVUS_CHROME_PATH, else the installer's copy, else PATH) |
--model <provider/model-id> | The model for this run only; see Configure a run |
--backup-model <provider/model-id> | The backup model for this run only |
--thinking <level> | Reasoning effort for this run only: off, low, medium, high, xhigh, max, or auto |
--capability <slug>=<on|off> | Toggle one capability for this run; repeat the flag for several |
--config <file> | A JSON run configuration, for scripted runs |
--record | Record the run (the agent's work and its computer) to a video, stored privately |
--record-public | Record the run and store the video at a permanent, shareable URL |
--benchmark-tools | Enable the opt-in benchmark tools; see Benchmark tools |
--json | Print one JSON result to stdout and everything else to stderr; see Use it from scripts |
--force | Allow the workspace to be your home directory or / |
--verbose | Print diagnostics to stderr |
--env <name> | The environment to use; see Environments |
--platform-url <url>, --operator-url <ws-url> | Override where the CLI reaches Octavus, for a proxy, a container, or a tunnel |
Other commands
octoagent auth --api-key <oct_agt_...>: store the agent's API key.octoagent config: show the current configuration, with the key redacted.octoagent version: show the CLI's version and the oldest and latest versions Octavus supports.octoagent help: the built-in help.
Configure a run
Set the model, the backup model, the reasoning effort, or capability toggles for one run without changing the agent's settings in the dashboard. Anything you do not set keeps the agent's setting, and the agent's stored configuration is never changed by a run.
# The model and backup model for this run only
octoagent run --model anthropic/claude-sonnet-5 --backup-model openai/gpt-5.5 "..."
# Deeper reasoning for this run only
octoagent run --model anthropic/claude-opus-5-5 --thinking xhigh "..."
# Capability toggles; unlisted capabilities keep the agent's setting
octoagent run --capability memory=off --capability handbook=on "..."
# The same, from a file, for repeatable runs
octoagent run --config run.json "..."run.json:
{
"model": "anthropic/claude-sonnet-5",
"backupModel": "openai/gpt-5.5",
"thinking": "high",
"capabilities": { "memory": false }
}Explicit flags win over the file, and the file wins over the agent's settings. Any model in the catalog at octavus.ai/pricing/models whose provider your organization can use is accepted; a model that cannot run, or a capability the agent does not have, is refused before the run starts. The capability slugs an agent accepts are the ones its definition declares, the same ones the Workforce Agents API lists under capabilities when you read the agent.
Record a run
--record records the run's execution view, the agent's work beside its computer, to a video stored privately: you watch it in the thread, signed in. --record-public stores it at a permanent, unguessable URL you can share. The video is ready a few seconds after the run ends; open the thread in the dashboard, or read recording.url from the thread with the Workforce Agents API.
Use it from scripts
With --json, the CLI prints exactly one JSON object to stdout and routes everything else to stderr, so a script can read the result without parsing text:
{ "threadId": "cm5xyz123abc456def", "sessionId": "...", "status": "completed", "threadUrl": "https://octavus.ai/agents/.../chat/..." }The exit code tells you how the run ended:
| Code | Meaning |
|---|---|
0 | Completed |
1 | Failed; stderr has the reason |
2 | Bad usage |
3 | The CLI is older than Octavus supports; update it |
4 | Stopped from the dashboard |
To read what the agent did, its full transcript and the run's cost, read the thread with the same API key: GET /api/v1/workforce/agents/{agentId}/threads/{threadId} (see Get a thread).
For a long run, start the CLI detached (for example with nohup) so a closed terminal does not end it. A run does not resume: if the CLI stops, crashes, or loses its network mid-run, the run fails, and you start a new one.
Stop a run
A CLI run has no chat composer, but you can stop it from the dashboard: open the thread and select Stop. The run ends on the machine and the CLI exits with code 4; with --json, the result's status is cancelled.
Benchmark tools
--benchmark-tools adds one extra tool for the run, for harnesses that need a capability the agent's normal toolset lacks. It is off by default and never present on a normal run.
The tool, benchmark__ask_human, lets the agent ask the operator driving the run for an input only they can provide, a withheld form field or the location of a source file, and continue with the answer. The exchange goes through two files in the run's workspace: the agent's question appears in benchmark-ask.json, and your harness writes the reply to benchmark-answer.json. If no answer arrives within about two minutes, the agent is told to proceed on its own. Enable it only when your harness is set up to answer.
Environments
--env <name> (or OCTAVUS_ENV) selects an environment; the default is production, which reaches https://octavus.ai with no further setup. Each environment keeps its own credentials and browser profiles under ~/.octavus/<env>/, so two never interfere. An environment other than production needs its --platform-url set once, with octoagent auth.
Keep the CLI current
Octavus supports a range of CLI versions. octoagent version shows your version next to the oldest and latest supported ones; a CLI older than the oldest is refused when it starts a run, with exit code 3. Update with the installer command, or with npm install -g @octavus/agent@latest.
Verify
Open the agent in the dashboard. The run is in its Threads, with your prompt, the agent's work, and its reply, and octoagent version shows a CLI version within the supported range.
Troubleshooting
| What you see | What it means |
|---|---|
| "This agent is not set to run from the CLI" | Choose Your own machine (CLI) in the agent's Computer settings. |
Exit code 3, or a message that an update is required | Your CLI is older than Octavus supports. Update it. |
401 or an invalid key | The key is missing, mistyped, or was deleted. Run octoagent auth again, or check OCTAVUS_API_KEY. |
| The agent is paused | An owner paused the agent. Resume it in the dashboard. |
| A plan allowance or spending limit was reached | The run is refused with the reason, and a blocked thread records the attempt. Upgrade or raise the limit, then run again. |
| The browser tools fail or Chrome cannot start | Install Chrome for Testing (the installer does), or point the CLI at it with --chrome-path or OCTAVUS_CHROME_PATH. Branded Chrome and the Chromium snap do not work. |
| Two runs on one machine interfere | Runs on one machine share its browser profile and display. Run one at a time per machine; running the same agent on several machines at once is fine. |
| The run died when the terminal closed | Start it detached, for example with nohup. |