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.
Configure Run
Section titled “Configure Run”Run and Check use the same VIBIUM_AI_* defaults.
For OpenAI, with your API key already exported:
export VIBIUM_AI_PROVIDER=openaiexport VIBIUM_AI_MODEL=gpt-5.6-solexport VIBIUM_AI_REASONING_EFFORT=nonevibium readyWait 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.
vibium run "add a battery pack to the cart" --base-url http://localhost:3000Accomplish the goal
Section titled “Accomplish the goal”Navigate to your app, then describe the change you want:
vibium go http://localhost:3000/accountvibium 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.
Shorthand
Section titled “Shorthand”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:
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.
Save the run
Section titled “Save the run”vibium run "change my timezone to America/Chicago and save it" -o run.zipThe 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:
vibium run "open https://example.com" -o example.zip --keep-openClose 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:
vibium run "change my timezone to America/Chicago and save it" --report result.jsonThe 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.
Follow with Check
Section titled “Follow with Check”Keep the session open for a separate acceptance check:
vibium run "change my timezone to America/Chicago and save it" --keep-openvibium 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.
Use MCP or a language API
Section titled “Use MCP or a language API”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.