Skip to content

For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to documentation page URLs. Read the agent handbook.

Zortex Docs
Start searching Install Vision
Use a browser

Use a browser

Open a page from the terminal, inspect its contents, act on current controls, and close the session.

On this page

This guide starts with a public page so you can check the browser without connecting a personal account. It then shows how to use the page's returned controls for a longer task.

Before you start

Install Indra and use your existing Vault directory. The commands below use a macOS or Linux shell; see CLI commands for shell conventions.

Shell
indra_root='/absolute/path/to/your-existing-vault'
indra --root "$indra_root" actions --json '{"source":"browser-use"}'

Replace the path with the Vault you already use. Commands can start the configured background host; its automatic-sync settings still apply. If you want to avoid full collection, read Sync information before starting the host.

The catalog should include browser.open, browser.observe, and browser.close. If the source is absent or unavailable, follow Troubleshooting before continuing.

Open, inspect, and close a page

  1. Open a public page

    Shell
    indra --root "$indra_root" action --json '{"name":"browser.open","params":{"url":"https://example.com/","sessionMode":"isolated"}}'
    

    An isolated session uses an owned headless browser. It does not inherit your personal browser login.

    A successful result contains a sessionId. The response shape is illustrated below; the ID on your computer will be different:

    JSON
    {"ok":{"sessionId":"<returned-sessionId>","url":"https://example.com/","mode":"headless"}}
    

    Keep that ID for the remaining commands. Opening a session does not read the page for you.

  2. Read the page

    Replace <returned-sessionId> with the value from the previous result:

    Shell
    indra --root "$indra_root" action --json '{"name":"browser.observe","params":{"sessionId":"<returned-sessionId>"}}'
    

    The result contains snapshot, with the current URL, title, text, and controls. For this example, check that the page is the expected Example Domain page. For your own task, verify the URL and relevant account or document before acting.

    You have now completed a browser read without an agent. To finish this example, go to step 4.

  3. Use the current controls

    For an interactive task, choose a control from the latest snapshot. Copy the whole returned control object; do not make one from a label, old ID, or guessed coordinate.

    Inspect the operation's arguments:

    Shell
    indra --root "$indra_root" actions --json '{"source":"browser-use","method":"browser.click"}'
    

    The following is a command template. Replace the session ID and replace the empty control object with the exact object you selected before running it:

    Shell
    indra --root "$indra_root" action --json '{"name":"browser.click","params":{"sessionId":"<returned-sessionId>","control":{}}}'
    
    Operation What to supply What to inspect afterward
    browser.click sessionId and the current control. New snapshot and feedback.effect.
    browser.type sessionId, current control, and value; use inputName instead when a continuation retains that input. The changed field and page state.
    browser.scroll sessionId only. Whether moved is true and what the new snapshot shows.

    Clicking, typing, and scrolling return a fresh snapshot. Select the next control from that result. The built-in scroll operation does not accept direction or pixel arguments.

    feedback.effect can report page_changed, controls_changed, or unchanged. None of those alone proves that a purchase, edit, or submission completed. Check the destination state required by your task.

  4. Close the session

    Shell
    indra --root "$indra_root" action --json '{"name":"browser.close","params":{"sessionId":"<returned-sessionId>"}}'
    

    Successful cleanup returns cleanup: "confirmed". A cleanup error needs attention; do not infer successful cleanup merely because a later call cannot find the session.

Recover from a problem

Symptom Next step
The control was stale or unavailable Observe again and select a control from the new snapshot.
The page asks for sign-in Check whether the task needs a different account/session; use Sign-in and recovery.
The session cannot be found It may have expired or its owner restarted. Check the task's current result before opening another session.
A submit action lost its response Inspect the target page or provider object before submitting again.
The browser connection is unavailable Check the reported missing component or connection; another supported browser or computer route may be available.

Use the same tools through an agent

MCP uses the same Action arguments:

Text
indra.action({"name":"browser.observe","params":{"sessionId":"<returned-sessionId>"}})

For a bounded delegated page task, browser.run_goal takes a URL, a goal, and an independent expectedText check. Inspect its schema first. If it returns continuation.actor: "agent", continue the returned live session with the individual browser operations, verify the result, then close it. A continuation is unfinished work, not a successful task.

Read Browser sessions and profiles before reusing a login or holding a session open.

Suggested