Jev Computer Use

Jev Computer Use is a native CDP browser agent. It observes the current page, chooses one operation and target, then executes that action. Jev works from page text and DOM controls rather than screenshots. Hyperbrowser runs Jev tasks in managed cloud browsers. Start a task with a single API call, then poll for results or use our SDK’s blocking methods that handle everything automatically. You can view your Jev tasks in the dashboard.

How It Works

You can use Jev in two ways:

Start and Wait: SDKs provide a startAndWait() method that blocks until the task completes and returns the result
Async Pattern: Start a task, get a job ID, then poll for status and results—useful for long-running tasks or when you want more control

Installation

npm install @hyperbrowser/sdk dotenv

yarn add @hyperbrowser/sdk dotenv

pip install hyperbrowser python-dotenv

uv add hyperbrowser python-dotenv

Quick Start

The simplest way to run a Jev task is with the startAndWait() method, which handles everything for you:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.jevComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});

from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.jev_computer_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "max_steps": 20,
    }
)

print(f"Output:\n{result.data.final_result}")

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.jev_computer_use.start_and_wait(
    params=StartJevComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post", max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")

# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/jev \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "task": "Go to Hacker News and tell me the title of the top post",
    "maxSteps": 20
  }'

# Response: {"jobId": "abc123", "liveUrl": "https://..."}

# Check status
curl https://api.hyperbrowser.ai/api/task/jev/abc123/status \
  -H "x-api-key: YOUR_API_KEY"

# Get full results
curl https://api.hyperbrowser.ai/api/task/jev/abc123 \
  -H "x-api-key: YOUR_API_KEY"

Async Pattern

When you need more control, use the async pattern to start a task and poll for results:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  try {
    // Start the task
    const task = await client.agents.jevComputerUse.start({
      task: "What is the title of the first post on Hacker News today?",
      maxSteps: 20,
    });

    console.log(`Task started: ${task.jobId}`);
    console.log(`Watch live: ${task.liveUrl}`);

    // Poll for completion
    let result;
    while (true) {
      result = await client.agents.jevComputerUse.getStatus(task.jobId);
      console.log(`Status: ${result.status}`);

      if (result.status === "completed" || result.status === "failed") {
        break;
      }

      await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5s
    }

    const fullResult = await client.agents.jevComputerUse.get(task.jobId);

    if (fullResult.status === "completed") {
      console.log("Result:", fullResult.data?.finalResult);
      console.log("Steps taken:", fullResult.data?.steps?.length);
    } else {
      console.error("Task failed:", fullResult.error);
    }
  } catch (err) {
    console.error(`Error: ${err.message}`);
  }
}

main();

import asyncio
from hyperbrowser import AsyncHyperbrowser
from dotenv import load_dotenv
import os

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    try:
        # Start the task
        task = await client.agents.jev_computer_use.start(
            params={
                "task": "What is the title of the first post on Hacker News today?",
                "max_steps": 20,
            }
        )

        print(f"Task started: {task.job_id}")
        print(f"Watch live: {task.live_url}")

        # Poll for completion
        while True:
            result = await client.agents.jev_computer_use.get_status(task.job_id)
            print(f"Status: {result.status}")

            if result.status in ["completed", "failed"]:
                break

            await asyncio.sleep(5)  # Wait 5s

        full_result = await client.agents.jev_computer_use.get(task.job_id)

        if full_result.status == "completed":
            print("Result:", full_result.data.final_result)
            print(
                "Steps taken:",
                len(full_result.data.steps) if full_result.data.steps else 0,
            )
        else:
            print("Task failed:", full_result.error)
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

import asyncio
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams
from dotenv import load_dotenv
import os

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    try:
        # Start the task
        task = await client.agents.jev_computer_use.start(
            params=StartJevComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                max_steps=20,
            )
        )

        print(f"Task started: {task.job_id}")
        print(f"Watch live: {task.live_url}")

        # Poll for completion
        while True:
            result = await client.agents.jev_computer_use.get_status(task.job_id)
            print(f"Status: {result.status}")

            if result.status in ["completed", "failed"]:
                break

            await asyncio.sleep(5)  # Wait 5s

        full_result = await client.agents.jev_computer_use.get(task.job_id)

        if full_result.status == "completed":
            print("Result:", full_result.data.final_result)
            print(
                "Steps taken:",
                len(full_result.data.steps) if full_result.data.steps else 0,
            )
        else:
            print("Task failed:", full_result.error)
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

Stop a Running Task

Stop a task before it completes:

await client.agents.jevComputerUse.stop("job-id");

client.agents.jev_computer_use.stop("job-id")

curl -X PUT https://api.hyperbrowser.ai/api/task/jev/job-id/stop \
  -H "x-api-key: YOUR_API_KEY"

Parameters

string

required

Natural language description of what you want Jev to accomplish. Be specific for best results. The task must be at most 8000 UTF-8 bytes.

string

default:"jev-1.13.0"

Jev decision model to use. Available options:

"jev-1.13.0" - Pinned Jev 1.13.0 decision model (default)
"jev-latest" - Latest hosted Jev decision model

string

default:"gemini-3.5-flash-lite"

Text helper model used for field values and the final result. Currently "gemini-3.5-flash-lite" is the only supported option.

number

default:"100"

Maximum number of executed policy actions. Allowed range is 1-300.

number

default:"3"

Accepted for compatibility with other agents. Jev does not add controller-level retries from this value.

string

ID of an existing browser session to reuse. Useful for multi-step workflows that need to maintain the same browser session.

boolean

default:"false"

Keep the browser session alive after task completion.

object

Session configuration (proxy, stealth, captcha solving, etc.). Only applies when creating a new session. If you provide an existing sessionId, these options are ignored.

boolean

default:"false"

Use your own Jev and Google API keys instead of consuming Hyperbrowser credits for model calls. You will only be charged for browser usage.

object

API keys for jev and google. Both are required when useCustomApiKeys is true.

{
  jev: "...",
  google: "..."
}

The agent may not complete the task within the specified maxSteps. If that happens, try increasing the maxSteps parameter.Additionally, the browser session used by the AI Agent will time out based on your team’s default Session Timeout settings or the session’s timeoutMinutes parameter if provided. You can adjust the default Session Timeout in the Settings page.

Jev does not send screenshots to either model. It reads visible page text and common HTML/ARIA controls, then dispatches native CDP clicks, typing, and selects.

Reuse Browser Sessions

You can pass in an existing sessionId to the Jev task so that it can execute the task on an existing session. Also, if you want to keep the session open after executing the task, you can supply the keepBrowserOpen parameter.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create();

  try {
    const result = await client.agents.jevComputerUse.startAndWait({
      task: "What is the title of the first post on Hacker News today?",
      sessionId: session.id,
      keepBrowserOpen: true,
    });

    console.log(`Output:\n${result.data?.finalResult}`);

    const result2 = await client.agents.jevComputerUse.startAndWait({
      task: "Tell me how many upvotes the first post has.",
      sessionId: session.id,
    });

    console.log(`\nOutput:\n${result2.data?.finalResult}`);
  } catch (err) {
    console.error(`Error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});

import os
from hyperbrowser import Hyperbrowser
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    session = client.sessions.create()

    try:
        resp = client.agents.jev_computer_use.start_and_wait(
            {
                "task": "What is the title of the first post on Hacker News today?",
                "session_id": session.id,
                "keep_browser_open": True,
            }
        )

        print(f"Output:\n{resp.data.final_result}")

        resp2 = client.agents.jev_computer_use.start_and_wait(
            {
                "task": "Tell me how many upvotes the first post has.",
                "session_id": session.id,
            }
        )

        print(f"\nOutput:\n{resp2.data.final_result}")
    finally:
        client.sessions.stop(session.id)


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    session = client.sessions.create()

    try:
        resp = client.agents.jev_computer_use.start_and_wait(
            StartJevComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                session_id=session.id,
                keep_browser_open=True,
            )
        )

        print(f"Output:\n{resp.data.final_result}")

        resp2 = client.agents.jev_computer_use.start_and_wait(
            StartJevComputerUseTaskParams(
                task="Tell me how many upvotes the first post has.",
                session_id=session.id,
            )
        )

        print(f"\nOutput:\n{resp2.data.final_result}")
    finally:
        client.sessions.stop(session.id)


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

Always set keepBrowserOpen: true on tasks that you want to reuse the session from. Otherwise, the session will be automatically closed when the task completes.

Using Your Own API Keys

Bring your own Jev and Google API keys to avoid consuming Hyperbrowser credits for model calls. You’ll still be charged for browser session usage, but save on token costs. Jev BYOK requires both keys: jev for decisions and google for text generation.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const result = await client.agents.jevComputerUse.startAndWait({
    task: "What is the title of the first post on Hacker News today?",
    useCustomApiKeys: true,
    apiKeys: {
      jev: "<JEV_API_KEY>",
      google: "<GOOGLE_API_KEY>",
    },
  });

  console.log(`Output:\n\n${result.data?.finalResult}`);
};

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});

import os
from hyperbrowser import Hyperbrowser
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    resp = client.agents.jev_computer_use.start_and_wait(
        {
            "task": "What is the title of the first post on HackerNews today?",
            "use_custom_api_keys": True,
            "api_keys": {
                "jev": "<JEV_API_KEY>",
                "google": "<GOOGLE_API_KEY>",
            },
        }
    )

    print(f"Output:\n\n{resp.data.final_result}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams, JevComputerUseApiKeys
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    resp = client.agents.jev_computer_use.start_and_wait(
        StartJevComputerUseTaskParams(
            task="What is the title of the first post on HackerNews today?",
            use_custom_api_keys=True,
            api_keys=JevComputerUseApiKeys(
                jev="<JEV_API_KEY>",
                google="<GOOGLE_API_KEY>",
            ),
        )
    )

    print(f"Output:\n\n{resp.data.final_result}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

curl -X POST https://api.hyperbrowser.ai/api/task/jev \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_HYPERBROWSER_API_KEY" \
  -d '{
    "task": "What is the title of the first post on Hacker News today?",
    "useCustomApiKeys": true,
    "apiKeys": {
      "jev": "YOUR_JEV_API_KEY",
      "google": "YOUR_GOOGLE_API_KEY"
    }
  }'

Session Configuration

Customize the browser session used by Jev with session options.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const result = await client.agents.jevComputerUse.startAndWait({
    task: "What is the title of the first post on Hacker News today?",
    sessionOptions: {
      acceptCookies: true,
    }
  });

  console.log(`Output:\n\n${result.data?.finalResult}`);
};

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});

import os
from hyperbrowser import Hyperbrowser
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    resp = client.agents.jev_computer_use.start_and_wait(
        {
            "task": "What is the title of the first post on Hacker News today?",
            "session_options": {
                "accept_cookies": True,
            },
        }
    )

    print(f"Output:\n\n{resp.data.final_result}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams, CreateSessionParams
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    resp = client.agents.jev_computer_use.start_and_wait(
        StartJevComputerUseTaskParams(
            task="What is the title of the first post on Hacker News today?",
            session_options=CreateSessionParams(
                accept_cookies=True,
            ),
        )
    )

    print(f"Output:\n\n{resp.data.final_result}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

curl -X POST https://api.hyperbrowser.ai/api/task/jev \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -d '{
      "task": "What is the title of the first post on Hacker News today?",
      "sessionOptions": {
          "acceptCookies": true
      }
  }'

sessionOptions only applies when creating a new session. If you provide a sessionId, these options are ignored.

Proxies and CAPTCHA solving add latency to page navigation. Only enable them when necessary for your use case.

Best Practices

Write clear, specific task descriptions

Be explicit about what you want Jev to do. Instead of “check the website”, say “go to example.com, find the pricing page, and extract the cost of the Enterprise plan”.

Set appropriate maxSteps

Simple tasks often finish in well under the default of 100 steps. Complex multi-page workflows can use up to 300. Monitor failed tasks and adjust accordingly.

Reuse sessions for multi-step workflows

It is usually better to split up complex tasks into smaller, more manageable ones and execute them as separate agent calls on the same session.

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

How It Works

Installation

Quick Start

Async Pattern

Stop a Running Task

Parameters

Reuse Browser Sessions

Using Your Own API Keys

Session Configuration

Best Practices

​How It Works

​Installation

​Quick Start

​Async Pattern

​Stop a Running Task

​Parameters

​Reuse Browser Sessions

​Using Your Own API Keys

​Session Configuration

​Best Practices

How It Works

Installation

Quick Start

Async Pattern

Stop a Running Task

Parameters

Reuse Browser Sessions

Using Your Own API Keys

Session Configuration

Best Practices