Firecrawl + Docker Sandboxes: Live Web Data for Sandboxed Agents

Erik EngervallErik Engervall
Nov 18, 2026
Firecrawl + Docker Sandboxes: Live Web Data for Sandboxed Agents image

Firecrawl turns any website into clean, LLM-ready data. Docker Sandboxes run coding agents like Claude Code and Codex inside an isolated VM, where the sandbox decides which hosts the agent can reach and credentials never leave the host. Together, you get an agent that can search, scrape, and crawl the live web without the sandbox opening up to the rest of the internet.

Firecrawl is a launch partner for Docker Sandboxes kits, and the Firecrawl kit is now on Kits v3, with an official guide on Docker's docs and a walkthrough on the Docker blog. The kit adds live web access to any sandboxed agent through one allowed host, and your API key never enters the sandbox. It is available now on Docker Hub.

[ Firecrawl kit for Docker Sandboxes ]

Give any Docker Sandbox agent live web access. One allowed host, and your API key stays out of the sandbox.

Kits are in Early Access, so the steps below are current for November 2026, and the repo README has the latest.

Live web data, inside the sandbox

A sandbox with no network is safe, and it leaves the agent unable to open a docs page, check a changelog, or look up an API that shipped after its training cutoff, so the agent answers from memory and gets current APIs wrong. The usual fix is to widen network access until the agent can fetch whatever it wants, which gives back most of what the sandbox took away.

Docker's kits fix this by declaring what a sandbox adds: tools to install, domains to allow, credentials to inject, and instructions for the agent. Docker introduced Kits v3 at the WeAreDevelopers keynote in San Jose on September 24.

In v3, a kit is a plain OCI image built with docker build, its declarations live in the image manifest, and Docker is proposing it as an open format. The Firecrawl kit ships as a v3 mixin, published as docker.io/firecrawl/sbx-kit-firecrawl, and passes Docker's kit conformance suite.

The Firecrawl kit is a mixin, so it layers onto the workload and agent you already run. With it in place, your sandboxed agent can:

All of it goes through one added host, api.firecrawl.dev. The kit adds to the sandbox's allowlist and does not narrow it, so what else the agent can reach is set by your global sbx policy. Docker's balanced preset allows package registries, GitHub, and a curated list of vendor domains, and returns a 403 for general websites, including most documentation sites. Firecrawl is the agent's route to those.

How it works

The kit does four things when a sandbox starts:

  1. Installs the Firecrawl Python SDK at a pinned version, and fails sandbox creation if the install or the import check fails.
  2. Declares a firecrawl credential. Your API key lives in the sbx secret store on the host. Inside the sandbox the agent sees a placeholder, and the proxy swaps in the real key on requests to api.firecrawl.dev.
  3. Allows outbound traffic to api.firecrawl.dev at runtime, and PyPI only during install.
  4. Gives the agent instructions so it knows the capability exists, how to call it, and which limits come from the sandbox rather than from Firecrawl.

The API key never enters the sandbox: the secret store on the host, the agent with firecrawl-py and its proxy-managed key, and the egress policy all feed the sbx proxy, which swaps in the real key for requests to api.firecrawl.dev and reaches PyPI only at install time

You need the sbx CLI, version 0.46 or later (on macOS, brew trust docker/tap && brew install docker/tap/sbx, then sbx login and, once, sbx policy init balanced), and a Firecrawl API key from firecrawl.dev/app/api-keys. In this walkthrough, Claude Code reads a library changelog. Under the balanced policy the sandbox proxy blocks documentation sites with a 403, so the agent has to go through Firecrawl.

1. Store the key once on the host. The kit holds no key, and sbx run takes no -e flag for it. Run the command with no input and it prompts for the key; paste the fc-... value from your Firecrawl dashboard. If the key is already in an environment variable, pipe it in instead with echo "$FIRECRAWL_API_KEY" | sbx secret set firecrawl. Service secrets apply to every sandbox by default.

sbx secret set firecrawl
sbx secret ls

The kit's credential is required, so in v3 sbx refuses to create the sandbox until the key is stored.

2. Start a sandbox with the kit. v3 mixins compose onto a v3 workload. This command starts Docker's shell workload, adds the Claude Code mixin, and adds the Firecrawl mixin. The trailing . mounts your project directory, so run it from the project, since sbx refuses to mount your home folder.

sbx run docker.io/docker/sbx-kit-shell:1.0.0 --name firecrawl-claude \
  --kit docker.io/docker/sbx-kit-claude-mixin:2.1.285 \
  --kit docker.io/firecrawl/sbx-kit-firecrawl:1.0.0 .

On the first run, sbx asks you to approve sending the firecrawl credential to api.firecrawl.dev. Accept the defaults, since the value already lives in the secret store. Claude Code can use an Anthropic key stored with sbx secret set anthropic, or you can sign in when it first starts. v3 kits are versioned images, so you reference them by tag.

3. Check that the pieces are in place. The shell workload opens a shell inside the sandbox. This scrapes a page through the API and exercises the SDK, the credential, and the network rule in one call:

python3 - <<'PY'
from firecrawl import Firecrawl
fc = Firecrawl()
doc = fc.scrape("https://docs.pydantic.dev/latest/changelog/", formats=["markdown"])
print(doc.markdown[:300])
PY

You should see the page as markdown, with its # Changelog heading and the latest version near the top. The same URL returns a 403 to curl from inside the sandbox. To confirm the key never entered the sandbox:

echo "$FIRECRAWL_API_KEY"

The value is the literal proxy-managed, the placeholder the SDK sends and the proxy replaces.

4. Give the agent a task. Start Claude Code with claude in the same shell, then ask:

Use the Firecrawl Python SDK to read https://docs.pydantic.dev/latest/changelog/ and list what changed in the latest Pydantic release. Quote the page, don't answer from memory.

The agent scrapes the page through Firecrawl and answers from the live changelog rather than from its training data.

To build the kit from source instead of pulling it from Docker Hub, clone the repo and point --kit at its firecrawl/ directory. The README covers this and the v2 form of the kit for the built-in sbx run claude shortcut.

What you can build with Firecrawl + Docker Sandboxes

Coding agents that read current docs. The agent scrapes the docs page for the library version you are on and writes code against that, instead of the version it remembers from training.

Safe dependency upgrades. Before an upgrade, the agent crawls the release notes and lists the breaking changes.

Research agents in locked-down environments. Teams with managed sandbox policy can allow one host and give every agent web search, rather than approving domains one at a time.

Parallel agents on one key. Store the key once, and every sandbox on the machine can use it, while the proxy keeps the value out of each one.

Good to know

A few limits come from the sandbox, and they look like Firecrawl errors when you first hit them:

  • The kit adds one host; it does not open the web. Under the balanced policy, general websites return a proxy 403 to curl, so a URL the agent finds in a scrape result has to be scraped through Firecrawl too. Firecrawl fetches pages on its servers, so the sandbox never needs direct access to them. Under a deny-all policy, api.firecrawl.dev is the only web host.
  • Screenshot and media formats return links on Firecrawl's storage host, which is outside the kit's network rules, so the file cannot be downloaded from inside the sandbox.
  • Organization governance controls which domains can be allowed. Under it, kit allow rules are inactive, so the org needs to allow api.firecrawl.dev. The Docker guide explains how policy and the kit interact.
  • Detached and CI runs cannot answer the credential prompt. Approve the firecrawl binding in one interactive run first, or write it to ~/.config/sbx/credentials.yaml. The README has the snippet.
  • A 402 on a scrape means the account is out of credits. The agent is told to stop rather than retry.

Get started

  1. Install the sbx CLI, sign in with sbx login, run sbx policy init balanced once, and get a Firecrawl API key at firecrawl.dev/app/api-keys
  2. Store the key with sbx secret set firecrawl
  3. Add the kit to a v3 workload with --kit docker.io/firecrawl/sbx-kit-firecrawl:1.0.0, as in the Docker guide

Issues and feature requests for the kit go to the GitHub repo. Feedback on the kit format itself belongs with Docker in docker/sandbox-kit-spec.


Ready to give your sandboxed agents live web data?

Get the kit on Docker Hub, follow the Firecrawl guide on Docker's docs, or get your free API key at firecrawl.dev.

Use Firecrawl in your agent

Add Firecrawl to ChatGPT, Claude, Cursor and more in one click.

Frequently Asked Questions

What is a Docker Sandboxes kit?

A kit packages what a sandbox adds: tools to install, domains the agent may reach, credentials to inject through the host-side proxy, and instructions for the agent. In Kits v3 a kit is an OCI image with its declarations in the image manifest. A workload kit provides the environment, and mixin kits such as Firecrawl layer onto it. Kits are in Early Access and the format may change.

Does the Firecrawl API key end up inside the sandbox?

No. The key is stored on the host with sbx secret set. Inside the sandbox the FIRECRAWL_API_KEY variable holds a placeholder, and the sandbox proxy swaps in the real key on requests to api.firecrawl.dev. The key is never written into the image or the sandbox filesystem.

Which agents work with the Firecrawl kit?

The v3 kit composes onto any v3 workload that ships python3 and pip, such as Docker's shell workload with the Claude Code mixin, or the Codex workload. The built-in sbx shortcuts such as sbx run claude still use v2 kits, so Firecrawl also publishes a v2 form of the kit for them.

Is the Firecrawl kit production ready?

The kit is experimental and follows Docker's Early Access status for kits. It is pinned to a specific firecrawl-py release and validated in CI, but the kit file format and sbx commands can change as Docker evolves the feature.

//
Get started
//
Ready to build?
Start getting web context for free and scale seamlessly as your project expands. No credit card needed.
Are you an AI agent? See setup options
Erik Engervall
Erik Engervall @firenoaa
Member of Technical Staff at Firecrawl
About the Author
Erik Engervall is a Member of Technical Staff at Firecrawl, where he works on partnerships and distribution. He has over ten years of experience as a software engineer.