> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox de Navegador

> Inicie sessões de sandbox de navegador e execute Python, JavaScript ou bash remotamente via agent-browser, API, CLI, SDKs e MCP.

O Firecrawl Browser Sandbox oferece para seus agentes um ambiente de navegador seguro e totalmente gerenciado. Sem configuração local, sem instalações de Chromium, sem problemas de compatibilidade de drivers. Agent browser e Playwright já vêm pré-instalados. Cada sessão é executada em um sandbox isolado e descartável, que escala sem necessidade de gerenciar infraestrutura.

Disponível via [API](/pt-BR/api-reference/endpoint/browser-create), [CLI](/pt-BR/sdks/cli#browser) (Bash / agent-browser, Python, Node), [Node SDK](/pt-BR/sdks/node#browser), [Python SDK](/pt-BR/sdks/python#browser), [Vercel AI SDK](/pt-BR/developer-guides/llm-sdks-and-frameworks/vercel-ai-sdk) e [MCP Server](/pt-BR/mcp-server).

Para adicionar suporte de navegador a um agente de código de IA (Claude Code, Codex, Open Code, Cursor, etc.), instale a skill do Firecrawl:

```bash theme={null}
npx -y firecrawl-cli@latest init --all --browser
```

Você também pode instalar o Firecrawl CLI ou deixar que o agente o instale para você, como mostrado acima:

```bash theme={null}
npm install -g firecrawl-cli
```

<div id="quick-start">
  ## Início rápido
</div>

Crie uma sessão, execute código e feche-a:

<CodeGroup>
  ```js Node theme={null}
  // npm install @mendable/firecrawl-js
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  // 1. Iniciar uma sessão
  const session = await firecrawl.browser();
  console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...

  // 2. Execute code
  const result = await firecrawl.browserExecute(session.id, {
    code: `
      await page.goto("https://news.ycombinator.com");
      const title = await page.title();
      console.log(title);
    `,
    language: "node",
  });
  console.log(result.result); // "Hacker News"

  // 3. Close
  await firecrawl.deleteBrowser(session.id);
  ```

  ```python Python theme={null}
  # pip install firecrawl
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  # 1. Iniciar uma sessão
  session = app.browser()
  print(session.cdp_url)  # wss://cdp-proxy.firecrawl.dev/cdp/...

  # 2. Execute code
  result = app.browser_execute(
      session.id,
      code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
      language="python",
  )
  print(result.result)  # "Hacker News"

  # 3. Close
  app.delete_browser(session.id)
  ```

  ```bash CLI theme={null}
  # Install the Firecrawl CLI
  npm install -g firecrawl-cli

  # Atalho - inicia uma sessão automaticamente, sem necessidade de "execute"
  firecrawl browser "open https://news.ycombinator.com"
  firecrawl browser "snapshot"
  firecrawl browser "scrape"

  # Close when done
  firecrawl browser close
  ```

  ```bash cURL theme={null}
  # 1. Iniciar uma sessão
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json"

  # 2. Execute code
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://news.ycombinator.com\")\ntitle = await page.title()\nprint(title)"
    }'

  # 3. Close
  curl -X DELETE "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

* **Sem instalação de drivers** - Sem binário do Chromium, sem `playwright install`, sem problemas de compatibilidade de drivers
* **Python, JavaScript e Bash** - Envie código via API, CLI ou SDK e receba os resultados de volta. As três linguagens são executadas remotamente no sandbox
* **agent-browser** - CLI pré-instalada com mais de 40 comandos. Agentes de IA escrevem comandos Bash simples em vez de código Playwright
* **Playwright carregado** - Playwright vem pré-instalado no sandbox. Agentes podem escrever código Playwright se preferirem.
* **Acesso ao CDP** - Conecte sua própria instância do Playwright via WebSocket quando precisar de controle total
* **Visualização em tempo real** - Assista às sessões em tempo real por meio de uma URL de transmissão incorporável
* **Visualização em tempo real interativa** - Permita que os usuários interajam diretamente com o navegador por meio de uma transmissão interativa incorporável

<div id="launch-a-session">
  ## Iniciar uma sessão
</div>

Retorna um ID de sessão, uma URL do CDP e uma URL de visualização em tempo real.

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const session = await firecrawl.browser({
    ttl: 120,
    activityTtl: 60,
  });

  console.log(session.id);
  console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
  console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  session = app.browser(
      ttl=120,
      activity_ttl=60,
  )

  print(session.id)
  print(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...
  print(session.live_view_url)  # https://liveview.firecrawl.dev/...
  ```

  ```bash CLI theme={null}
  # Iniciar com visualização em tempo real e TTL personalizado
  firecrawl browser launch-session --stream --ttl 120 --ttl-inactivity 60

  # Iniciar e salvar informações da sessão em arquivo
  firecrawl browser launch-session -o session.json --json
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ttl": 120,
      "activityTtl": 60
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-e29b-41d4-a716-446655440000",
  "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000?interactive=true"
}
```

<div id="execute-code">
  ## Executar código
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const result = await firecrawl.browserExecute("YOUR_SESSION_ID", {
    code: 'await page.goto("https://example.com"); const title = await page.title(); console.log(title);',
    language: "node",
  });

  console.log(result);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  result = app.browser_execute(
      "YOUR_SESSION_ID",
      code='await page.goto("https://example.com")\ntitle = await page.title()\nprint(title)',
      language="python",
  )

  print(result)
  ```

  ```bash CLI theme={null}
  # comandos agent-browser (padrão - "agent-browser" é prefixado automaticamente)
  firecrawl browser execute "open https://example.com"
  firecrawl browser execute "snapshot"
  firecrawl browser execute "scrape"

  # Execute Playwright Python code
  firecrawl browser execute --python 'await page.goto("https://example.com")
  print(await page.title())'

  # Execute Playwright JavaScript code
  firecrawl browser execute --node 'await page.goto("https://example.com"); document.title'

  # Execute arbitrary bash in the sandbox
  firecrawl browser execute --bash 'ls /tmp'

  # Target a specific session
  firecrawl browser execute --session <id> "snapshot"
  ```

  ```bash cURL theme={null}
  # Execute Playwright Python code
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://example.com\")\ntitle = await page.title()\nprint(title)",
      "language": "python"
    }'

  # Executar código Playwright JavaScript
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://example.com\"); const title = await page.title(); console.log(title);",
      "language": "node"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "result": "Example Domain"
}
```

<div id="agent-browser-bash-mode">
  ## agent-browser (Modo Bash)
</div>

[agent-browser](https://github.com/vercel-labs/agent-browser) é uma CLI de navegador headless pré-instalada em cada sandbox. Em vez de escrever código em Playwright, os agentes enviam comandos bash simples. A CLI injeta automaticamente `--cdp` para que o agent-browser se conecte automaticamente à sua sessão ativa.

<div id="shorthand">
  ### Forma abreviada
</div>

A maneira mais rápida de usar o browser. Tanto a forma abreviada quanto `execute` enviam comandos para o agent-browser automaticamente. A forma abreviada apenas ignora o `execute` e inicia uma sessão automaticamente, se necessário:

```bash theme={null}
firecrawl browser "open https://example.com"
firecrawl browser "snapshot"
firecrawl browser "click @e5"
```

<div id="cli">
  ### CLI
</div>

A forma explícita usa `execute`. Os comandos são enviados automaticamente ao agent-browser — você não precisa digitar `agent-browser` nem usar `--bash`:

<CodeGroup>
  ```bash Navigate & Snapshot theme={null}
  firecrawl browser execute "open https://example.com"
  firecrawl browser execute "snapshot"
  ```

  ```bash Interact theme={null}
  firecrawl browser execute "click @e5"
  firecrawl browser execute "fill @e3 'termo de busca'"
  firecrawl browser execute "scrape"
  ```
</CodeGroup>

<div id="api-sdk">
  ### API & SDK
</div>

Use `language: "bash"` para executar comandos do agent-browser por meio da API ou dos SDKs:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "agent-browser snapshot",
      "language": "bash"
    }'
  ```

  ```javascript Node theme={null}
  const result = await app.browserExecute(sessionId, {
    code: "agent-browser snapshot",
    language: "bash",
  });
  ```

  ```python Python theme={null}
  result = app.browser_execute(
      session_id,
      code="agent-browser snapshot",
      language="bash",
  )
  ```
</CodeGroup>

<div id="session-management">
  ## Gerenciamento de sessões
</div>

<div id="persistent-sessions">
  ### Sessões persistentes
</div>

Por padrão, cada sessão do navegador começa em um estado limpo. Com `profile`, você pode salvar e reutilizar o estado do navegador entre sessões. Isso é útil para permanecer logado e preservar preferências.

Para salvar ou selecionar um perfil, use o parâmetro `profile` ao criar uma sessão.

<CodeGroup>
  ```js Node theme={null}
  const session = await firecrawl.browser({
    ttl: 300,
    profile: {
      name: "my-profile",
      saveChanges: true,
    },
  });
  ```

  ```python Python theme={null}
  session = app.browser(
      ttl=300,
      profile={
          "name": "my-profile",
          "save_changes": True,
      },
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ttl": 300,
      "profile": {
        "name": "my-profile",
        "saveChanges": true
      }
    }'
  ```

  ```bash CLI theme={null}
  # Iniciar com um perfil (salva alterações por padrão)
  firecrawl browser launch-session --profile my-profile

  # Iniciar com um perfil em modo somente leitura
  firecrawl browser launch-session --profile my-profile --no-save-changes

  # Atalho: iniciar com perfil + executar em uma etapa
  firecrawl browser --profile my-profile "open https://example.com"
  ```
</CodeGroup>

| Parâmetro     | Padrão | Descrição                                                                                                                                                                                            |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | —      | Um nome para o perfil persistente. Sessões com o mesmo nome compartilham o armazenamento.                                                                                                            |
| `saveChanges` | `true` | Quando `true`, o estado do navegador é salvo de volta no perfil ao fechar. Defina como `false` para carregar dados existentes sem gravar — útil quando você precisa de vários leitores concorrentes. |

<Note>
  Apenas uma sessão pode salvar em um perfil por vez. Se outra sessão já estiver salvando, você receberá um erro `409`. Você ainda pode abrir o mesmo perfil com `saveChanges: false` ou tentar novamente mais tarde.
</Note>

O estado da sessão do navegador só é salvo quando a sessão é encerrada. Portanto, recomendamos fechar a sessão do navegador quando terminar de usá-la, para que ela possa ser reutilizada. Para salvar e fechar:

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  await firecrawl.deleteBrowser("YOUR_SESSION_ID");
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  app.delete_browser("YOUR_SESSION_ID")
  ```

  ```bash CLI theme={null}
  # Fecha a sessão ativa
  firecrawl browser close

  # Fecha uma sessão específica
  firecrawl browser close --session <id>
  ```

  ```bash cURL theme={null}
  curl -X DELETE "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id": "YOUR_SESSION_ID"}'
  ```
</CodeGroup>

<div id="list-sessions">
  ### Listar sessões
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const { sessions } = await firecrawl.listBrowsers();
  console.log(sessions);

  // Filtrar por status
  const { sessions: active } = await firecrawl.listBrowsers({ status: "active" });
  console.log(active);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  response = app.list_browsers()
  print(response.sessions)
  ```

  ```bash CLI theme={null}
  firecrawl browser list
  firecrawl browser list active
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"

  # Filtrar por status
  curl -X GET "https://api.firecrawl.dev/v2/browser?status=active" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-e29b-41d4-a716-446655440000",
      "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000",
      "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000?interactive=true",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}
```

<div id="ttl-configuration">
  ### Configuração de TTL
</div>

As sessões têm dois controles de TTL:

| Parâmetro     | Padrão       | Descrição                                           |
| ------------- | ------------ | --------------------------------------------------- |
| `ttl`         | 300s (5 min) | Tempo máximo de duração da sessão (30-3600s)        |
| `activityTtl` | 120s (2 min) | Encerramento automático após inatividade (10-3600s) |

<div id="close-a-session">
  ### Encerrar a sessão
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  await firecrawl.deleteBrowser("YOUR_SESSION_ID");
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  app.delete_browser("YOUR_SESSION_ID")
  ```

  ```bash CLI theme={null}
  # Fecha a sessão ativa
  firecrawl browser close

  # Fecha uma sessão específica
  firecrawl browser close --session <id>
  ```

  ```bash cURL theme={null}
  curl -X DELETE "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id": "YOUR_SESSION_ID"}'
  ```
</CodeGroup>

<div id="live-view">
  ## Live View
</div>

Toda sessão retorna uma `liveViewUrl` na resposta que você pode incorporar para acompanhar o navegador em tempo real. Útil para depuração, demonstrações ou para criar interfaces baseadas em navegador.

```json Response theme={null}
{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-...",
  "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-...?interactive=true"
}
```

```html theme={null}
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />
```

<div id="interactive-live-view">
  ### Visualização Interativa Ao Vivo
</div>

A resposta também inclui um `interactiveLiveViewUrl`. Diferente da visualização ao vivo padrão, que é apenas para consulta, a visualização interativa ao vivo permite que os usuários cliquem, digitem e interajam com a sessão do navegador diretamente por meio do streaming incorporado. Isso é útil para construir interfaces de navegador voltadas para o usuário final, depuração colaborativa ou qualquer cenário em que quem estiver visualizando precise controlar o navegador.

```html theme={null}
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
```

<div id="connecting-via-cdp">
  ## Conectando-se ao CDP
</div>

Cada sessão expõe uma URL de WebSocket do CDP. A API `execute` e a opção `--bash` cobrem a maioria dos casos de uso, mas, se você precisar de controle local total, pode se conectar diretamente.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Firecrawl from '@mendable/firecrawl-js';
  import { chromium } from "playwright-core";

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
  const session = await firecrawl.browser();

  const browser = await chromium.connectOverCDP(session.cdpUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || (await context.newPage());

  await page.goto("https://example.com");
  console.log(await page.title());

  await browser.close();
  await firecrawl.deleteBrowser(session.id);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl
  from playwright.sync_api import sync_playwright

  app = Firecrawl(api_key="fc-YOUR-API-KEY")
  session = app.browser()

  with sync_playwright() as p:
      browser = p.chromium.connect_over_cdp(session.cdp_url)
      context = browser.contexts[0]
      page = context.pages[0] if context.pages else context.new_page()

      page.goto("https://example.com")
      print(page.title())

      browser.close()

  app.delete_browser(session.id)
  ```

  ```bash agent-browser theme={null}
  # Use o cdpUrl retornado na resposta da sessão
  agent-browser open https://example.com --cdp "$CDP_URL"
  agent-browser snapshot --cdp "$CDP_URL"
  ```
</CodeGroup>

<div id="when-to-use-browser">
  ## Quando usar o Browser
</div>

| Caso de uso                                                                | Ferramenta recomendada              |
| -------------------------------------------------------------------------- | ----------------------------------- |
| Extrair conteúdo de uma URL conhecida                                      | [Scrape](/pt-BR/features/scrape)    |
| Pesquisar na web e obter resultados                                        | [Search](/pt-BR/features/search)    |
| Navegar por paginações, preencher formulários e seguir fluxos de navegação | **Browser**                         |
| Fluxos de trabalho com múltiplas etapas e interação                        | **Browser**                         |
| Navegação paralela em vários sites ao mesmo tempo                          | **Browser** (cada sessão é isolada) |

<div id="use-cases">
  ## Casos de uso
</div>

* **Inteligência competitiva** - Navegar em sites de concorrentes, usar formulários de busca e filtros, extrair preços e funcionalidades em dados estruturados
* **Ingestão de base de conhecimento** - Navegar por centrais de ajuda, documentação e portais de suporte que exigem cliques, paginação ou autenticação
* **Pesquisa de mercado** - Iniciar sessões de navegador em paralelo para criar conjuntos de dados a partir de sites de vagas, anúncios de imóveis ou bancos de dados jurídicos

<div id="pricing">
  ## Preços
</div>

A cobrança é simples: 2 créditos por minuto de uso do navegador. Usuários gratuitos recebem 5 horas de uso grátis.

<div id="rate-limits">
  ## Limites de taxa
</div>

No lançamento inicial, todos os planos poderão ter até 20 sessões de navegador simultâneas.

<div id="api-reference">
  ## Referência da API
</div>

* [Criar sessão do navegador](/pt-BR/api-reference/endpoint/browser-create)
* [Executar código no navegador](/pt-BR/api-reference/endpoint/browser-execute)
* [Listar sessões do navegador](/pt-BR/api-reference/endpoint/browser-list)
* [Excluir sessão do navegador](/pt-BR/api-reference/endpoint/browser-delete)

***

Tem alguma sugestão ou precisa de ajuda? Envie um e-mail para [help@firecrawl.com](mailto:help@firecrawl.com) ou fale com a gente no [Discord](https://discord.gg/gSmWdAkdwd).