Skip to main content

Run an agent on your own machine with the Agent CLI

Install the Octavus Agent CLI on a Linux machine you control and run one of your agents with that machine as its computer.

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

  1. In the dashboard, open the agent and go to Settings -> Computer.
  2. Open More options, choose Your own machine (CLI), and confirm.
  3. 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

bash
curl -fsSL https://octavus.ai/install/agent-cli.sh | sh

The 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:

bash
npm install -g @octavus/agent

The 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:

bash
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_KEY in the environment instead of running octoagent auth. An explicit --api-key wins over the variable, which wins over the stored key.

Commands

octoagent run "<prompt>"

Run one prompt to completion and exit.

FlagDescription
--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
--recordRecord the run (the agent's work and its computer) to a video, stored privately
--record-publicRecord the run and store the video at a permanent, shareable URL
--benchmark-toolsEnable the opt-in benchmark tools; see Benchmark tools
--jsonPrint one JSON result to stdout and everything else to stderr; see Use it from scripts
--forceAllow the workspace to be your home directory or /
--verbosePrint 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.

bash
# 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:

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:

json
{ "threadId": "cm5xyz123abc456def", "sessionId": "...", "status": "completed", "threadUrl": "https://octavus.ai/agents/.../chat/..." }

The exit code tells you how the run ended:

CodeMeaning
0Completed
1Failed; stderr has the reason
2Bad usage
3The CLI is older than Octavus supports; update it
4Stopped 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 seeWhat 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 requiredYour CLI is older than Octavus supports. Update it.
401 or an invalid keyThe key is missing, mistyped, or was deleted. Run octoagent auth again, or check OCTAVUS_API_KEY.
The agent is pausedAn owner paused the agent. Resume it in the dashboard.
A plan allowance or spending limit was reachedThe 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 startInstall 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 interfereRuns 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 closedStart it detached, for example with nohup.