> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Computer Use

> Automate browser tasks using Anthropic's Claude with sophisticated computer use capabilities

Claude Computer Use enables Claude to interact with web browsers like a human by moving the cursor, clicking elements, typing text, and navigating pages. This lets you automate complex, multi-step workflows with natural language instructions.

Hyperbrowser provides a managed Claude Computer Use agent that handles session management, browser infrastructure, and task execution. You simply describe what you want done, and Claude figures out how to do it.

You can view your Claude Computer Use tasks in the [dashboard](https://app.hyperbrowser.ai/features/agents/claude-computer-use).

## How It Works

You can use Claude Computer Use in two ways:

1. **Start and Wait**: SDKs provide a `startAndWait()` method that blocks until the task completes and returns the result
2. **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

```bash npm theme={null}
npm install @hyperbrowser/sdk dotenv
```

```bash yarn theme={null}
yarn add @hyperbrowser/sdk dotenv
```

```bash pip theme={null}
pip install hyperbrowser python-dotenv
```

```bash uv theme={null}
uv add hyperbrowser python-dotenv
```

## Quick Start

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

```typescript Node.js theme={null}
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.claudeComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    llm: "claude-sonnet-5-5",
    maxSteps: 20,
  });

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

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

```python Python 1.0+ theme={null}
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.claude_computer_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "llm": "claude-sonnet-5-5",
        "max_steps": 20,
    }
)

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

```python Python (legacy) theme={null}
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartClaudeComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

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

result = client.agents.claude_computer_use.start_and_wait(
    params=StartClaudeComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post",
        llm="claude-sonnet-5-5",
        max_steps=20,
    )
)

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

```bash cURL theme={null}
# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/claude-computer-use \
  -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",
    "llm": "claude-sonnet-5-5",
    "maxSteps": 20
  }'

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

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

# Get full results
curl https://api.hyperbrowser.ai/api/task/claude-computer-use/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:

```typescript Node.js theme={null}
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.claudeComputerUse.start({
      task: "What is the title of the first post on Hacker News today?",
      llm: "claude-sonnet-5-5",
      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.claudeComputerUse.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.claudeComputerUse.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();
```

```python Python 1.0+ theme={null}
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.claude_computer_use.start(
            params={
                "task": "What is the title of the first post on Hacker News today?",
                "llm": "claude-sonnet-5-5",
                "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.claude_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.claude_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())
```

```python Python (legacy) theme={null}
import asyncio
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import StartClaudeComputerUseTaskParams
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.claude_computer_use.start(
            params=StartClaudeComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                llm="claude-sonnet-5-5",
                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.claude_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.claude_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:

```typescript Node.js theme={null}
await client.agents.claudeComputerUse.stop("job-id");
```

```python Python theme={null}
client.agents.claude_computer_use.stop("job-id")
```

```bash cURL theme={null}
curl -X PUT https://api.hyperbrowser.ai/api/task/claude-computer-use/job-id/stop \
  -H "x-api-key: YOUR_API_KEY"
```

## Parameters

**task** `string` *required*

Natural language description of what you want Claude to accomplish. Be specific for best results.

**llm** `string` (default: claude-sonnet-5-5)

See [Claude Computer Use model mappings](https://hyperbrowser.ai/docs/agents/model-mappings.md#claude-computer-use) for the alias reference.

Claude model to use. Available options:

* `"claude-opus-5-5"` - Opus 5.5 model
* `"claude-fable-5-2"` - Latest Fable 5.2 model
* `"claude-fable-5-1"` - Fable 5.1 model
* `"claude-opus-5"` - Opus 5 model
* `"claude-opus-4-8"` - Opus 4.8 model
* `"claude-opus-4-7"` - Opus 4.7 model
* `"claude-opus-4-6"` - Opus 4.6 model
* `"claude-opus-4-5"` - Opus 4.5 model
* `"claude-sonnet-5-5"` - Sonnet 5.5 model (default)
* `"claude-sonnet-5"` - Sonnet 5 model
* `"claude-sonnet-4-6"` - Sonnet 4.6 model
* `"claude-haiku-5-5"` - Haiku 5.5, the fastest and most cost-effective option
* `"claude-haiku-4-5-20251001"` - Haiku 4.5

**reasoningEffort** `string`

Optional reasoning effort for Claude. Omit this field to use the model's default. Available options depend on the selected model:

* `"low"`
* `"medium"`
* `"high"`
* `"xhigh"` — only supported by `"claude-opus-5-5"`, `"claude-fable-5-2"`, `"claude-fable-5-1"`, `"claude-opus-5"`, `"claude-opus-4-8"`, `"claude-opus-4-7"`, `"claude-sonnet-5-5"`, `"claude-sonnet-5"`, and `"claude-haiku-5-5"`
* `"max"` — supported by the models above, plus `"claude-opus-4-6"` and `"claude-sonnet-4-6"`

`"claude-opus-4-5"` supports `"low"`, `"medium"`, and `"high"` only. Other models, including `"claude-haiku-4-5-20251001"`, do not support reasoning effort.

**maxSteps** `number` (default: 20)

Maximum number of actions Claude can take (clicks, typing, navigation, etc.). Increase for complex tasks.

**maxFailures** `number` (default: 3)

Maximum consecutive failures before the task is aborted.

**sessionId** `string`

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

**keepBrowserOpen** `boolean` (default: false)

Keep the browser session alive after task completion.

**useComputerAction** `boolean` (default: false)

Allow the agent to interact by executing actions on the actual computer not just within the page. Allows the agent to see the entire screen instead of just the page contents.

**sessionOptions** `object`

[Session configuration](https://hyperbrowser.ai/docs/api-reference/start-a-claude-computer-use-task.md#body-session-options) (proxy, stealth, captcha solving, etc.). Only applies when creating a new session. If you provide an existing `sessionId`, these options are ignored.

**useCustomApiKeys** `boolean` (default: false)

Use your own Anthropic API key instead of consuming Hyperbrowser credits for LLM calls. You will only be charged for browser usage.

**apiKeys** `object`

API key for `anthropic`. Required when `useCustomApiKeys` is `true`.

```typescript theme={null}
{
  anthropic: "..."
}
```

> [!TIP]
>
> 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](https://app.hyperbrowser.ai/settings).

> [!NOTE]
>
> `useComputerAction` can often be better for completing tasks but may require more steps. It is especially useful when the agent needs to interact with elements on the page that might not be accessible by or visible to Playwright. Since it allows the agent to see and interact with the entire screen, it is much more powerful. Instead of executing actions with Playwright which can only interact with the page via CDP, computer actions allow the agent to interact directly with computer primitives (direct clicks, typing, scroll, etc.).

## Reuse Browser Sessions

You can pass in an existing `sessionId` to the Claude Computer Use 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.

```typescript Node.js theme={null}
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.claudeComputerUse.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.claudeComputerUse.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}`);
});
```

```python Python 1.0+ theme={null}
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.claude_computer_use.start_and_wait(
            {
                "task": "What is the title of the first post on Hacker News today?",
                "llm": "claude-sonnet-5-5",
                "session_id": session.id,
                "keep_browser_open": True,
            }
        )

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

        resp2 = client.agents.claude_computer_use.start_and_wait(
            {
                "llm": "claude-sonnet-5-5",
                "task": "Tell me how many upvotes the first post has.",
                "session_id": session.id,
            }
        )

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


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

```python Python (legacy) theme={null}
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartClaudeComputerUseTaskParams
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.claude_computer_use.start_and_wait(
            StartClaudeComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                llm="claude-sonnet-5-5",
                session_id=session.id,
                keep_browser_open=True,
            )
        )

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

        resp2 = client.agents.claude_computer_use.start_and_wait(
            StartClaudeComputerUseTaskParams(
                llm="claude-sonnet-5-5",
                task="Tell me how many upvotes the first post has.",
                session_id=session.id,
            )
        )

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


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

> [!WARNING]
>
> 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 Anthropic API key to avoid consuming Hyperbrowser credits for LLM calls. You'll still be charged for browser session usage, but save on token costs.

```typescript Node.js theme={null}
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.claudeComputerUse.startAndWait({
    task: "What is the title of the first post on Hacker News today?",
    llm: "claude-sonnet-5-5",
    useCustomApiKeys: true,
    apiKeys: {
      anthropic: "<ANTHROPIC_API_KEY>",
    },
  });

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

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

```python Python 1.0+ theme={null}
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.claude_computer_use.start_and_wait(
        {
            "task": "What is the title of the first post on HackerNews today?",
            "llm": "claude-sonnet-5-5",
            "use_custom_api_keys": True,
            "api_keys": {
                "anthropic": "<ANTHROPIC_API_KEY>",
            },
        }
    )

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


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

```python Python (legacy) theme={null}
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import (
    StartClaudeComputerUseTaskParams,
    ClaudeComputerUseApiKeys,
)
from dotenv import load_dotenv

load_dotenv()

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


def main():
    resp = client.agents.claude_computer_use.start_and_wait(
        StartClaudeComputerUseTaskParams(
            task="What is the title of the first post on HackerNews today?",
            llm="claude-sonnet-5-5",
            use_custom_api_keys=True,
            api_keys=ClaudeComputerUseApiKeys(
                anthropic="<ANTHROPIC_API_KEY>",
            ),
        )
    )

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


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

```bash cURL theme={null}
curl -X POST https://api.hyperbrowser.ai/api/task/claude-computer-use \
  -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?",
    "llm": "claude-sonnet-5-5",
    "useCustomApiKeys": true,
    "apiKeys": {
      "anthropic": "YOUR_ANTHROPIC_API_KEY"
    }
  }'
```

## Session Configuration

Customize the browser session used by Claude Computer Use with session options.

```typescript Node.js theme={null}
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.claudeComputerUse.startAndWait({
    task: "What is the title of the first post on Hacker News today?",
    llm: "claude-sonnet-5-5",
    sessionOptions: {
      acceptCookies: true,
    }
  });

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

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

```python Python 1.0+ theme={null}
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.claude_computer_use.start_and_wait(
        {
            "task": "What is the title of the first post on Hacker News today?",
            "llm": "claude-sonnet-5-5",
            "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}")
```

```python Python (legacy) theme={null}
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartClaudeComputerUseTaskParams, CreateSessionParams
from dotenv import load_dotenv

load_dotenv()

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


def main():
    resp = client.agents.claude_computer_use.start_and_wait(
        StartClaudeComputerUseTaskParams(
            task="What is the title of the first post on Hacker News today?",
            llm="claude-sonnet-5-5",
            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}")
```

```bash cURL theme={null}
curl -X POST https://api.hyperbrowser.ai/api/task/claude-computer-use \
  -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?",
      "llm": "claude-sonnet-5-5",
      "sessionOptions": {
          "acceptCookies": true
      }
  }'
```

> [!NOTE]
>
> `sessionOptions` only applies when creating a new session. If you provide a `sessionId`, these options are ignored.

> [!WARNING]
>
> Proxies and CAPTCHA solving add latency to page navigation. Only enable them when necessary for your use case.

## Best Practices

> [accordion] Write clear, specific task descriptions
>
> Be explicit about what you want Claude to do. Instead of "check the website", say "go to example.com, find the pricing page, and extract the cost of the Enterprise plan".

> [accordion] Set appropriate maxSteps
>
> Simple tasks need 10-20 steps. Complex multi-page workflows might need 50+ steps. Monitor failed tasks and adjust accordingly.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.