Skip to content

Accomplish a browser goal with Run

vibium run uses the live browser to carry out a goal and returns COMPLETED or NOT_COMPLETED, with concise evidence. Use Check separately when you want a fresh assessment of the result.

For coding agents, Run guidance is part of the browser skill. The separate check skill handles independent verification.

Run and Check use the same VIBIUM_AI_* defaults. For OpenAI, with your API key already exported:

Terminal window
export VIBIUM_AI_PROVIDER=openai
export VIBIUM_AI_MODEL=gpt-5.6-sol
export VIBIUM_AI_REASONING_EFFORT=none
vibium ready

Wait for READY. For Anthropic, Google, or a local server, see model providers. Each command also loads empty AI variables from ~/.config/vibium/ai.env, which vibium setup ai writes. Exported values win. Set VIBIUM_LOAD_AI_ENV=0 to skip the file.

For one run, use --provider, --model, --ai-base-url, and --reasoning-effort instead of changing environment defaults. These options also work with ready and ready ai. See per-call settings.

--base-url names the site under test: it is opened first unless the current page already shares its origin, and relative navigation targets resolve against it. Not the AI provider endpoint; that is --ai-base-url.

Terminal window
vibium run "add a battery pack to the cart" --base-url http://localhost:3000

Navigate to your app, then describe the change you want:

Terminal window
vibium go http://localhost:3000/account
vibium run "change my timezone to America/Chicago and save it"

Example result:

RUN: change my timezone to America/Chicago and save it
COMPLETED
The timezone was changed and saved.
- The account page reports the saved timezone as America/Chicago.

Read the evidence. COMPLETED is the model’s assessment, not proof. If the goal is ambiguous or required information is missing, Run can return NOT_COMPLETED, with a machine-readable reason in the JSON result: action_limit, missing_information, or safety_stop. Provider, browser, and configuration failures are errors.

Run reuses the existing session and selected page. It can change page state and does not undo its actions. Supply a clear goal and appropriate test data. It can enter explicitly supplied test credentials through its browser tools; Check retains its stricter restriction on password fields.

A connected Browser or Page in JavaScript/TypeScript and Python is callable: vibe(goal, options) delegates to vibe.run(goal, options) (Python uses keyword options). Use await with async APIs. It preserves the same browser session. Java uses the explicit run() method.

import { browser } from 'vibium';
const vibium = await browser.start();
try {
await vibium("Open https://example.com");
// Equivalent: await vibium.run("Open https://example.com");
await vibium.check("The page shows Example Domain");
} finally {
await vibium.stop();
}

Here vibium is a connected browser object; importing the package does not create a browser session.

The CLI accepts one quoted multiword prompt:

Terminal window
vibium "open example.com and find its contact page"
# Equivalent to vibium run "open example.com and find its contact page".

Known subcommands take precedence. Unknown single words and multiple positional arguments are errors; use vibium run "stop" for a one-word prompt.

For shared settings, callable examples in both languages, checkbox methods, and skills, see Introducing Run and Check.

Terminal window
vibium run "change my timezone to America/Chicago and save it" -o run.zip

The recording contains a Run group with generated browser actions and the result. Open the ZIP in Record Player. Recording output, Firefox WebM capture, existing-recording exports, and privacy rules work as they do for Check. Use a new filename; existing files are never overwritten.

If Run starts a browser, it closes it after saving evidence, including when it returns NOT_COMPLETED or encounters an error. A browser already running stays open. Add --keep-open to preserve one it starts:

Terminal window
vibium run "open https://example.com" -o example.zip --keep-open

Close it later with vibium stop. Run is live-only: it has no --input option. --report saves the result and evidence as a new JSON file:

Terminal window
vibium run "change my timezone to America/Chicago and save it" --report result.json

The report holds the result object with status, goal, summary, and evidence. The path MUST be new and MUST differ from --output. An execution error leaves no report. --json prints the structured result instead of text. Completed operations exit 0 for either status; execution errors exit 1. In automation, add --expect completed so NOT_COMPLETED exits 2 while errors keep exit 1, or inspect result.status == "completed" in JSON stdout or the report file.

Keep the session open for a separate acceptance check:

Terminal window
vibium run "change my timezone to America/Chicago and save it" --keep-open
vibium check "The saved timezone is America/Chicago after refresh. Inspect without editing the form."

Run and Check can use different providers and models. Check starts a fresh conversation and does not inherit Run’s model history.

All inference runs in the existing Go runtime. Configure environment defaults before starting the MCP server or SDK; restart it after changing those defaults. Per-call model overrides need no restart. Browser and Page instances expose run(goal); Page pins the operation to that page. SDK calls preserve the caller’s browser.

MCP:

{"name":"vibium_run","arguments":{"goal":"change my timezone to America/Chicago and save it"}}

An optional page context ID selects a specific tab. record is not accepted.

JavaScript/TypeScript:

const result = await page.run('change my timezone to America/Chicago and save it');
console.log(result.status, result.evidence);

The synchronous API has the same method without await.

Python:

result = page.run("change my timezone to America/Chicago and save it")
print(result["status"], result["evidence"])

Use await page.run(...) with the async API.

Java:

RunResult result = page.run("change my timezone to America/Chicago and save it");
System.out.println(result.status());

Import com.vibium.types.RunResult. Start and stop an SDK recording around these calls to save evidence. All interfaces use the same three-minute model budget, 24-action limit, tool policies, and completed | not_completed contract.