Octavus Agent CLI

The @octavus/agent package (the octoagent command). Run one of your cloud Octavus Agents on a Linux machine you control, using that machine as the agent's computer: the agent lives in the cloud (fully configured and observable) and the local machine only supplies the computer and the trigger.

The agent's brain (model, tools, sub-agents, skills, connections) runs on the Octavus platform exactly as it does everywhere else. The CLI just drives the browser, computer-use, filesystem, and shell on the machine you run it on, and every run shows up as a normal thread on the agent in the dashboard - live while it runs and afterward.

When to use it

This is the bring-your-own-computer way to run an agent: great for servers, CI, and benchmarks (ALE, OSWorld, and any "install a CLI, give it a key, run a prompt" harness). It is not the desktop app (an always-on, paired daemon) and not @octavus/cli (which manages platform agents) - it is locally triggered and ephemeral.

Set up the agent

In the dashboard, open the agent's Computer settings, choose "Your own machine (CLI)" (under "More options"), and confirm. That agent then has no managed computer, so its manual chat, schedule, and notifications are turned off - it is driven only from the CLI. Its threads stay visible.

Then mint an agent API key from the agent's Settings -> API tab.

Install

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

The installer sets up the prerequisites a full computer needs on a standard Linux box (Node, a headless X display via Xvfb, the AT-SPI accessibility bus, Chrome for Testing) so "install and run" just works. A shell + filesystem only agent needs none of the display stack.

Use

# Configure once with the agent's API key (the only credential you handle).
octoagent auth --api-key oct_agt_xxx

# Run a prompt in the current directory (the agent's filesystem/shell root).
cd ~/projects/my-task
octoagent run "Summarize the README and open the repo's homepage in the browser."

The working directory you launch in is the agent's workspace (override with --workdir). Durable per-agent operational data - the browser profile (so logins persist across runs) and cached skills - lives under ~/.octavus/<env>/<agentId>/, never in your working directory.

Commands

• octoagent run "<prompt>" - run one prompt to completion and exit.
  • --workdir <dir> - the agent's filesystem/shell root (default: current directory).
  • --api-key <oct_agt_...> - override the stored key for this run.
  • --platform-url <url> - override the platform base URL.
  • --env <name> - environment to use (default: production; see below).
  • --chrome-path <path> - path to Chrome for Testing (else resolved from PATH).
  • --model <provider/model-id> - model for this run only (else the agent's default).
  • --backup-model <provider/model-id> - backup model for this run only.
  • --capability <slug>=<on|off> - toggle one capability for this run (repeatable).
  • --config <file> - JSON run config for scripted sweeps (see below).
  • --json - print one machine-readable JSON result to stdout.
  • --force - allow running with the workspace at $HOME or /.
  • --verbose - print diagnostics to stderr.
• octoagent auth --api-key <oct_agt_...> [--platform-url <url>] [--env <name>] - store credentials.
• octoagent config [--env <name>] - show the current configuration.
• octoagent version [--env <name>] - show the CLI and platform-supported versions.

Exit codes: 0 completed, 1 failed, 2 bad usage, 3 update required, 4 stopped from the dashboard.

Stopping a run

A run has no live chat, but you can still stop it from the dashboard: open its thread and click Stop. The run is aborted on the machine and the CLI exits with code 4 (its --json output reports "status": "cancelled"). Useful when you fan out several runs from a server and want to halt some of them.

Run configuration

Configure how the agent runs for a single invocation, without changing its dashboard settings. Any field you omit inherits the agent's configured default; the agent's stored configuration is never modified by a run.

# Choose the model + backup model for this run only.
octoagent run --model openrouter/moonshotai/kimi-k2 --backup-model anthropic/claude-sonnet-5 "..."

# Toggle capabilities for this run (repeatable). Unlisted capabilities inherit the agent default.
octoagent run --capability memory=off --capability handbook=on "..."

# Or carry it all in a JSON file for scripted/repeatable sweeps.
octoagent run --config run.json "..."

run.json:

{ "model": "openrouter/moonshotai/kimi-k2", "backupModel": "anthropic/claude-sonnet-5", "capabilities": { "memory": false } }

Precedence: explicit flags > --config file > the agent's dashboard defaults. Any model is allowed as long as a key resolves for its provider (your project/org BYOK or the platform default); an unrunnable or malformed model is rejected up front, before the run starts. Capability toggles are bounded to the capabilities the agent's protocol declares. A run with no run config behaves exactly as before.

Machine-readable output

--json prints exactly one JSON object to stdout - { "threadId", "sessionId", "status", "threadUrl" } - with all human/progress output routed to stderr, so a benchmark harness can capture and correlate a run without scraping text. The exit code signals completed (0), failed (1), or stopped from the dashboard (4). Read the full transcript and a per-run cost/usage summary from GET /api/v1/workforce/agents/{agentId}/threads/{threadId} with the same agent key.

Environments

--env <name> (or OCTAVUS_ENV, default production) selects an environment. Each keeps its own credentials and browser profile under ~/.octavus/<env>/, so you can configure and run more than one side by side without them clobbering each other:

octoagent auth --api-key oct_agt_prod                                  # production (default)
octoagent auth --env staging --api-key oct_agt_stg --platform-url <staging-url>
octoagent run --env staging "..."

production targets https://octavus.ai with no extra config; any other environment needs its --platform-url set once (stored per environment).

Notes

• One run per machine. Runs on one machine share that machine's computer (browser profile, display), so running the same agent twice on one machine can collide. Running the same agent from many machines at once is fine and independent.
• No resume (v1). If the CLI stops, crashes, or loses its network mid-run, the run fails - start a new one. For long runs, run detached (e.g. nohup) so a closed terminal doesn't kill it.
• Network identity is the machine's own. Nothing is manufactured; a residential machine can pass strict logins, a datacenter box may be challenged.
• Billing is unchanged - the same hourly agent-time plus platform/provider cost as any run. Bringing your own computer doesn't change the bill.