Docker Sandboxes Firecrawl Kit: Give a Sandboxed Agent Live Web Search Without Widening Its Allowlist

Set up Docker Sandboxes Firecrawl kit: store the key once, pick v3 or v2, approve the binding, and prove in sbx policy log that only api.firecrawl.dev opened.

Hero diagram for the Docker Sandboxes Firecrawl kit: a sandbox VM holding FIRECRAWL_API_KEY = proxy-managed, an fc.scrape call and a blocked curl; a host proxy wall with three doors for PyPI hosts (install only), api.firecrawl.dev (runtime, key swapped in) and any other host (403); and host-side cards for the OS keychain secret, Firecrawl servers and the approved binding.Hero diagram for the Docker Sandboxes Firecrawl kit: a sandbox VM holding FIRECRAWL_API_KEY = proxy-managed, an fc.scrape call and a blocked curl; a host proxy wall with three doors for PyPI hosts (install only), api.firecrawl.dev (runtime, key swapped in) and any other host (403); and host-side cards for the OS keychain secret, Firecrawl servers and the approved binding.
The sandbox keeps one door to the web, api.firecrawl.dev, and the real key is added on the host side of the proxy. Pattern from Docker's Firecrawl kit blog post and Docs guide, November 16, 2026.

Your coding agent runs inside a Docker sandbox, the global network policy is set to balanced, and the first time it tries to read a library changelog it gets a proxy 403. The Docker Sandboxes Firecrawl kit fixes that problem without the usual escape hatch of switching the sandbox to allow-all. It adds one runtime host, api.firecrawl.dev, installs the Firecrawl Python SDK, and has the host-side proxy attach your API key on the way out, so the real key never enters the VM. Docker announced the kit on its blog on November 16, 2026, alongside a matching Docker Docs guide.

This tutorial is for a developer who already runs Claude Code, Codex or a plain shell workload under sbx and wants the agent to search, scrape and crawl current pages. It builds one worked sandbox, sandbox:firecrawl-shell-01, from an empty secret store to a scrape you can account for in sbx policy log, and then returns the host to where it started. If you have never run sbx, read our Docker Sandboxes setup guide first. It covers workspaces, the base network policy and teardown. This article starts where that one stops: adding a third-party capability to an isolated agent without loosening the isolation.

By the end you should be able to show four things on your own machine:

  • the sandbox reaches pypi.org and files.pythonhosted.org while the kit installs, and api.firecrawl.dev at runtime;
  • FIRECRAWL_API_KEY inside the VM reads proxy-managed, never a real fc- value;
  • a direct curl to a documentation site from inside the sandbox still fails with a proxy 403;
  • after rollback, no secret, binding, sandbox or rule for Firecrawl remains.

What the kit adds to a sandbox you already run

The Firecrawl kit is a mixin. It does not define a new sandbox. It extends whichever workload you already run. Docker’s blog lists the four typed capabilities its descriptor declares, and the kit repository README explains how each one can be checked independently:

  • lifecycle@1 installs firecrawl-py pinned to 4.44.0 as the agent user (uid 1000). If the install or the post-install import check fails, sandbox creation fails.
  • credential@1 requests the key stored under the firecrawl service. Inside the sandbox the variable holds the literal placeholder proxy-managed, and the proxy writes Authorization: Bearer <key> only on requests to api.firecrawl.dev.
  • network-policy@1 is split by phase: PyPI hosts during install, api.firecrawl.dev at runtime.
  • agent-context@1 ships a context file that tells the agent the SDK exists, how to call it and which sandbox limits apply. The workload indexes it from its own AGENTS.md.

The Kit v3 specification explains why this is reviewable. A kit is one ordinary OCI image whose manifest annotation carries the declarations, so pinning a version or digest pins the content and the authority it asks for together. The spec also says unknown fields are errors and a required capability the host cannot grant refuses the launch. A permission is never dropped silently.

Below is the shape of those declarations. It is an illustrative reconstruction, built from the credential@1 and network-policy@1 schema in Docker’s credentials documentation and the hosts the blog names. It is not a copy of firecrawl/firecrawl.yaml. Read the real descriptor inside the sandbox, as shown later.

# syntax=docker/sandbox-kit:3
# Illustrative shape only. The published descriptor is printed by:
#   cat /usr/share/sandbox/kit/firecrawl/kit.yaml
schemaVersion: "3"
kind: mixin
capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      install:
        allow: [pypi.org, files.pythonhosted.org]   # only while the hook runs
      runtime:
        allow: [api.firecrawl.dev]                  # the one host the agent keeps
  - type: com.docker.sandbox/credential@1
    config:
      service: firecrawl            # must match: sbx secret set firecrawl
      phase: runtime
      apiKey:
        name: FIRECRAWL_API_KEY     # what the SDK reads inside the VM
        proxyManaged: true          # VM sees the sentinel proxy-managed
        inject:
          - domain: api.firecrawl.dev
            header: Authorization
            format: "Bearer %s"
  # lifecycle@1 (pip install firecrawl-py==4.44.0) and
  # agent-context@1 (firecrawl-context.md) omitted here

Three choices in that shape do the security work. The install and runtime allow lists are separate, so PyPI access is meant for the install hook, not for the agent afterwards. The service name is the join key between the kit’s request and your stored secret, which is why you store the key as firecrawl and nothing else. And proxyManaged: true with an explicit inject domain means the key can only be written into a header on requests to api.firecrawl.dev. Requests to other hosts never carry it, according to the Docker guide.

One more property matters for planning: kit network rules add to your sandbox policy and never narrow it. Under Docker’s balanced preset, general websites, including most documentation sites, return a proxy 403, so Firecrawl becomes the agent’s route to them. Under deny-all, api.firecrawl.dev is the only web host the agent can reach.

Before you start: what the kit needs on your host

Work through this checklist on the host, not inside a sandbox. Each item maps to a failure you will otherwise meet later.

  • [ ] sbx 0.46 or later for the v3 kit. Run sbx version. The README says the v2 kit works from 0.45, but the worked example uses v3. The sbx CLI reference lists version, secret, policy, run and rm, which are the only verbs this guide needs.
  • [ ] Signed in. Run sbx login once. Docker Desktop is not required.
  • [ ] A global network policy. Run sbx policy init balanced if you have never set one. The sbx policy init reference describes this as one-time setup that fails once a preset exists; until it runs, every sbx run fails with global network policy has not been initialized.
  • [ ] A Firecrawl API key. Keys start with fc-. Scrapes, searches and crawls use Firecrawl credits.
  • [ ] A project directory that is not your home directory. sbx run mounts the current directory, and the README notes that mounting your whole home directory fails with mount policy denied.
  • [ ] To use the v2 path from the published image: the Docker CLI with Buildx on the host, because that path resolves :latest to a digest with docker buildx imagetools inspect.

Check the active preset before you change anything. Docker’s getting-started page shows sbx policy ls as the command that lists the rules in effect, and notes that with Balanced common development services are permitted while other destinations are blocked unless you approve them.

Choose the kit line: v3 mixin or v2 for built-in agents

The kit ships in two formats with the same declarations, and you cannot mix them. The README is blunt about it: a v3 mixin only composes onto a v3 workload, and the v2 mixin only onto the built-in agents. The spec repository adds the naming rule that makes this easy to spot: the docker organization publishes v3 kits and the sbx organization still carries the older v2 line.

You run Kit line Kit reference Base you compose onto Pinning rule
A v3 workload such as docker/sbx-kit-shell v3 docker.io/firecrawl/sbx-kit-firecrawl:1.0.0 docker/sbx-kit-shell:1.0.0, optionally --kit docker/sbx-kit-claude-mixin:2.1.285 A version tag is fine; a digest is stricter
A built-in agent: sbx run claude, codex, copilot, gemini, opencode, shell and others v2 docker.io/firecrawl/firecrawl-docker-sandbox The agent name as the trailing argument :latest is rejected; resolve it to a digest, or pin a 40-hex git commit
You want to read or modify the kit first Either, from source ./firecrawl-docker-sandbox/firecrawl (v3) or ./firecrawl-docker-sandbox/ (v2) Same as the matching row Your local clone is the pin

Pick v3 when you are starting fresh. The descriptor travels in the image, so a version tag works, the kit describes itself inside the sandbox, and v3 refuses to create the sandbox when the required credential has no secret, instead of letting the agent hit a 401 mid-task.

Pick v2 when your team already launches built-in agents with sbx run claude or sbx run codex and you do not want to change the base. The trade-off is pinning. Kit references must pin a commit SHA or a digest; branches, tags and :latest are rejected. The README’s two documented forms are:

# Published image: resolve :latest to a digest first (plain inspect output;
# the README warns that the --format path fails on the kit's YAML config)
digest=$(docker buildx imagetools inspect docker.io/firecrawl/firecrawl-docker-sandbox:latest | awk '/^Digest:/ {print $2}')
sbx run --kit "oci://docker.io/firecrawl/firecrawl-docker-sandbox@$digest" claude

# Straight from git, pinned to a commit
git ls-remote https://github.com/firecrawl/firecrawl-docker-sandbox.git main
sbx run --kit "git+https://github.com/firecrawl/firecrawl-docker-sandbox.git#ref=<commit-sha>" codex

What happens if you get the line wrong is not documented as a specific error message. The README states the composition is unsupported, and the spec says resolution fails closed. If a launch fails right after you add the kit, check the organization in each reference before you debug anything else.

Store the Firecrawl key without putting it in the VM

Providing a value and approving its use are separate steps in sbx. This section does the first one.

  1. Store the key under the service name the kit declares:

    sbx secret set firecrawl
    

    sbx prompts for the value. Prefer the prompt to the README’s piped form (echo "$FIRECRAWL_API_KEY" | sbx secret set firecrawl) on shared machines, because it keeps the key out of your shell’s environment and history.

  2. Decide the scope. Service secrets are global by default, so every sandbox that requests the firecrawl service can use the key once you approve it. To limit it to the worked example, add --sandbox firecrawl-shell-01. The credentials documentation says sandbox-scoped secrets take precedence over global ones, and that adding, updating or removing a service secret takes effect in existing local sandboxes without a restart. Note that sbx before 0.46 needed -g for global scope.

  3. Confirm the store:

    sbx secret ls
    

    Expect a row with SCOPE (global) or your sandbox name, SERVICE firecrawl and a masked value.

  4. Know where it lives. On macOS it is the system Keychain, on Windows the Credential Manager, and on Linux the desktop Secret Service. On headless Linux without a Secret Service, sbx falls back to a file under ~/.config/com.docker.sandboxes protected by file permissions, and prints a notice saying so. Treat that directory as sensitive.

The secret is now on the host and nowhere else. Nothing has been approved yet, so no sandbox can use it.

Launch sandbox:firecrawl-shell-01 and approve the binding

The worked example uses Docker’s plain shell workload, so you can test the SDK directly before any agent touches it.

  1. From your project directory, start the sandbox with the v3 kit:

    sbx run docker/sbx-kit-shell:1.0.0 --name firecrawl-shell-01 \
      --kit docker.io/firecrawl/sbx-kit-firecrawl:1.0.0 .
    

    The trailing . mounts the current directory. The --name flag comes from the Docker Docs guide, which names its sandbox firecrawl-shell; the blog and README forms omit it. Combining the two documented forms is our choice, so if your sbx version rejects the flag in this position, drop it and read the generated name from sbx ls.

  2. Approve the credential request. On first run sbx asks you to approve sending the firecrawl credential to api.firecrawl.dev. The blog and README both say to accept the defaults, since the value already lives in the secret store. sbx writes the approval to ~/.config/sbx/credentials.yaml (%APPDATA%\sbx\credentials.yaml on Windows).

  3. Watch the install. sbx pulls both images, runs the install hook as the agent user and opens a shell. If the hook cannot install or import the SDK, creation stops. The README says a custom base without python3 and python3-pip fails with a message saying so.

  4. Add the agent when the plumbing works. For Claude Code on the same workload, add its mixin alongside the Firecrawl kit:

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

The binding sbx records looks like this, per the README:

bindings:
  firecrawl:
    apiKey:
      domains: [api.firecrawl.dev]

That file is only an approval record. It does not hold the key. The credentials documentation says third-party kits need an approved binding for each credential regardless of schema version, while the built-in kits shipped with sbx do not. Declining writes no entry at all.

The Docker Docs guide uses a shorter launch, sbx run shell --name firecrawl-shell --kit docker.io/firecrawl/sbx-kit-firecrawl:1.0.0, and says sbx pulls both kits. That reads as the shell name resolving to a kit workload in current sbx, while the README pairs the built-in shell agent with the v2 line. The documentation does not reconcile the two forms, so the worked example uses the explicit docker/sbx-kit-shell:1.0.0 reference that the blog, README and spec all show.

Sequence diagram with four lanes, Agent in VM, Host proxy, Firecrawl API and Docs site. Seven numbered messages: the agent sends Bearer proxy-managed to the proxy; the proxy checks the rule and swaps in the key; the proxy sends Bearer with the real key to Firecrawl; Firecrawl fetches the page from the docs site; the docs site returns HTML; Firecrawl returns the page as markdown to the agent; a red curl from the agent to the docs site stops at the proxy with a 403.Sequence diagram with four lanes, Agent in VM, Host proxy, Firecrawl API and Docs site. Seven numbered messages: the agent sends Bearer proxy-managed to the proxy; the proxy checks the rule and swaps in the key; the proxy sends Bearer with the real key to Firecrawl; Firecrawl fetches the page from the docs site; the docs site returns HTML; Firecrawl returns the page as markdown to the agent; a red curl from the agent to the docs site stops at the proxy with a 403.
The real key exists only to the right of the proxy, and Firecrawl, not the sandbox, contacts the documentation site. Mechanism from Docker's Firecrawl sandbox kit guide and the Docker Sandboxes credentials documentation.

Prove each layer from inside the sandbox

Each check below covers a separate layer, from a cheap import to a full scrape. Run them in the shell that sbx run opened. In a Claude Code session, prefix each command with ! to run it inside the sandbox. The expected results are the ones the Docker guide and README document; they are illustrative expected observations for sandbox:firecrawl-shell-01, not output we captured.

Input Action Expected result (illustrative)
sandbox:firecrawl-shell-01, host terminal, key stored as service firecrawl sbx secret ls A row for service firecrawl with scope (global) or firecrawl-shell-01 and a masked secret; no row means step 1 of the store section did not run
sandbox:firecrawl-shell-01, shell inside the VM, kit 1.0.0 installed python3 -c "import firecrawl, importlib.metadata as m; print(m.version('firecrawl-py'), firecrawl.__file__)" 4.44.0 /home/agent/.local/lib/python3.14/site-packages/firecrawl/__init__.py, the user-site path that matches an install as uid 1000
sandbox:firecrawl-shell-01, shell inside the VM echo "$FIRECRAWL_API_KEY" proxy-managed; a real fc- value means the key came from somewhere other than the kit; an empty line means sbx predates per-credential proxyManaged, so update the CLI
sandbox:firecrawl-shell-01, binding approved, credits available Run the scrape script below against https://docs.docker.com/ai/sandboxes/ The first 300 characters of that page as Markdown; Unauthorized means the proxy added no key; PaymentRequiredError means the key worked and credits ran out
sandbox:firecrawl-shell-01, balanced preset, no extra allow rules curl https://docs.pydantic.dev/latest/changelog/ A proxy 403: the sandbox itself still cannot reach general documentation sites
sandbox:firecrawl-shell-01, v3 kit cat /usr/share/sandbox/kit/firecrawl/kit.yaml The published descriptor, with firecrawl-context.md alongside it in the same directory

The end-to-end scrape is the one to run if you run only one, because it exercises the package, the network rule and credential injection at once:

python3 - <<'EOF'
from firecrawl import Firecrawl

fc = Firecrawl()
doc = fc.scrape("https://docs.docker.com/ai/sandboxes/", formats=["markdown"])
print(doc.markdown[:300])
EOF

Read the pair of results together. The scrape returns Markdown while the variable says proxy-managed, and the direct curl to a docs site fails. Those three facts together are your evidence that the key was injected outside the VM and that the agent’s web access runs through one host. The blog makes the same argument: the same URL that returns a 403 to curl comes back as Markdown through the SDK.

Read sbx policy log: forwarded, blocked and absent hosts

The policy log is the host-side record of what the sandbox actually contacted. Run it on the host, not in the VM.

  1. Print the log for the worked sandbox:

    sbx policy log firecrawl-shell-01
    
  2. Compare it with Docker’s sample, which the guide prints for its firecrawl-shell sandbox:

    ALLOWED REQUESTS
    SANDBOX          TYPE     HOST                    PROXY    RULE            REASON   LAST SEEN        COUNT
    firecrawl-shell  network  api.firecrawl.dev       forward  domain-allowed           10:16:02 15-Oct  1
    firecrawl-shell  network  files.pythonhosted.org  forward  domain-allowed           10:15:41 15-Oct  6
    firecrawl-shell  network  pypi.org                forward  domain-allowed           10:15:40 15-Oct  4
    
  3. Check each row against the decision table below.

What you see Meaning Action
pypi.org and files.pythonhosted.org forwarded, timestamps before the first scrape The install hook fetched the pinned SDK None; this is the install phase
api.firecrawl.dev forwarded with domain-allowed The runtime rule matched and the request left the host Confirm a scrape succeeded; that success is what shows the key was added
No row for the page you scraped Firecrawl fetched that page on its servers None; this is the point of the kit
A row for a docs host you did not expect Something in the VM tried to reach it directly Find the process; under balanced it should have been refused
PyPI rows appearing after the agent started working Runtime traffic to PyPI from another source, such as the agent running pip Decide whether your preset should allow it; the kit’s install rule is not meant for this

Horizontal bar chart titled Install traffic outnumbers the one scrape 10 to 1. Amber install-phase bars: files.pythonhosted.org 6 requests, pypi.org 4. Indigo runtime bar: api.firecrawl.dev 1. docs.docker.com has no bar, labelled 0, not in the log because Firecrawl fetched it.Horizontal bar chart titled Install traffic outnumbers the one scrape 10 to 1. Amber install-phase bars: files.pythonhosted.org 6 requests, pypi.org 4. Indigo runtime bar: api.firecrawl.dev 1. docs.docker.com has no bar, labelled 0, not in the log because Firecrawl fetched it.
In Docker's sample sbx policy log, the kit's install hook made 10 PyPI requests and the scrape made one request to api.firecrawl.dev; the scraped page never appears. Source: Docker Docs Firecrawl sandbox kit guide, sample output dated 15-Oct.

Two limits on what this log proves. First, the documented sample prints only the allowed section; the docs page does not show what a blocked entry looks like, so treat the absence of a blocked section in your own output as unverified rather than as a clean bill. Second, the log columns show forwarding and the matching rule, not whether a credential was injected. Injection is proven by the combination in the previous section: a successful scrape while the VM holds only the placeholder. If you need a stricter record, the getting-started page points to sbx policy ls for rules in effect, and the network rules page documents sbx policy ls --wide for rule IDs.

The network rules page also lists hostname-matching limits worth knowing before you rely on a log: a denied host that shares an IP address with an allowed host can still be reached, and on connections the proxy does not decrypt, the HTTP Host inside the encrypted stream is not checked. We covered why sandbox boundaries need this kind of skepticism in The Sandbox Is a Suggestion.

Give the agent a dated, live-web task

With the plumbing proven, give the agent work that cannot be answered from training data. The kit’s context file tells the agent to scrape blocked hosts through Firecrawl, so it should call the SDK without being told how.

  1. Start the Claude Code variant from the launch section, or attach to an agent workload that composes the kit.

  2. Ask for something dated and checkable. The blog uses this prompt:

    Read <https://docs.pydantic.dev/latest/changelog/> and list what changed in the latest Pydantic release. Quote the page, don't answer from memory.
    
  3. Check the answer for a quoted heading with a version and date. In Docker’s own run, the agent reported v2.13.4 (2026-05-06) and quoted the changelog lines. That is Docker’s observation from its post, not one we reproduced.

  4. Keep requests cheap. The Docker guide’s calls are fc.scrape(url, formats=["markdown"]) for one page, fc.search("docker sandboxes kits", limit=5) for search results and fc.crawl("https://docs.example.com", limit=20) for a site section. Each crawled page uses credits, so keep limit low and prefer a search followed by one targeted scrape when the agent needs a single fact.

  5. Tell the agent what not to do. URLs found in a scrape result must also be scraped through Firecrawl, because curl to them still returns 403. Screenshot and other media formats return links on Firecrawl’s storage host, which the allowlist does not include, so those files cannot be downloaded inside the sandbox.

If you are deciding whether a Markdown fetch is enough or a task really needs browser automation, our comparison of web-to-Markdown pipes versus computer use lays out the trade. For a different search API wired straight into an agent rather than through a sandbox kit, see the DeepSeek Search API tool guide.

Run it unattended without a silent 401

The approval prompt is the part that breaks CI. A detached run cannot answer it, and the docs describe two different outcomes depending on what is missing.

  1. No secret stored at all. The v3 kit refuses to create the sandbox. The blog says this is deliberate, so the agent does not hit a 401 mid-task. Store the key first.
  2. Secret stored, no binding. The credentials documentation says that in non-interactive contexts the sandbox starts with the credential withheld and, for a required credential, sbx prints a warning rather than failing creation. The README quotes it: WARN: credential not sent: no binding authorizes this service. Scrapes then fail with 401 because the literal proxy-managed reaches Firecrawl.
  3. Pre-create the binding by running the kit interactively once, or by writing the bindings block shown earlier into ~/.config/sbx/credentials.yaml before the unattended run.
  4. Make the run fail loudly. The sbx CLI has a global --no-input option: commands that need an answer fail with the command to run instead of prompting. Add the scrape check from the proof section as the first job step, so a withheld credential fails the job before the agent starts.
  5. Mind the flag spelling. The credentials page writes --detach and the README writes --detached. Confirm the spelling with sbx run --help on your version before you script it.

For fleets, this is the same principle as treating permission modes as policy rather than per-session choices, which we argued in restricted mode as fleet policy: the binding file is a reviewed artifact, not something a prompt approves at 2 a.m.

Troubleshooting: match the symptom to the layer

Find the symptom, then fix the layer it points to. Do not widen the network policy to make a symptom go away.

Symptom Layer Fix
global network policy has not been initialized Host policy sbx policy init balanced (or deny-all) once
Launch fails right after adding the kit Kit line or pin Check that v3 kits pair with docker/* workloads and v2 with built-in agents; replace :latest with a version, digest or commit
v3 create refused, credential required Secret store sbx secret set firecrawl, then rerun
Scrape raises Unauthorized / HTTP 401 Binding Confirm the secret is under firecrawl and that the binding for api.firecrawl.dev exists; rerun interactively to approve
Scrape raises PaymentRequiredError / HTTP 402 Firecrawl account Authentication worked; add credits or lower limit. The agent instructions tell it to stop, not retry
WebsiteNotSupportedError ... Blocked by network policy: domain api.firecrawl.dev:443 Organization governance sbx policy ls firecrawl-shell-01 and look for Managed by <org>; only the organization can add an api.firecrawl.dev allow rule
Scrape blocked after you added a deny rule Local deny Intended: a sandbox deny beats the kit’s allow. Remove it with sbx policy rm network --sandbox firecrawl-shell-01 --resource api.firecrawl.dev
FIRECRAWL_API_KEY is empty sbx version Update the sbx CLI; per-credential proxyManaged is missing
mount policy denied: /Users/<you> Workspace Run from a project directory, not your home directory

The governance row deserves a note. Docker’s guide says that under organization governance, local and kit-defined allow rules are inactive while deny rules still restrict access. The README adds that the SDK install and the proxy-injected credential still work in that state; only the outbound scrape is gated. Ask the governance owner for one api.firecrawl.dev rule rather than trying to work around it locally.

You can rehearse the deny override on purpose. The network rules page shows the pattern for a kit-allowed host, and changes take effect immediately:

sbx policy deny network --sandbox firecrawl-shell-01 api.firecrawl.dev
# rerun the scrape: illustrative expectation is a proxy-side block, not Markdown
sbx policy rm network --sandbox firecrawl-shell-01 --resource api.firecrawl.dev

That drill is also your emergency stop: one command cuts the agent’s web access without touching the secret or the kit. If you are also using Claude Code’s own command sandbox inside the VM, keep the two apart when debugging; our Claude Code sandbox troubleshooting guide covers failures that happen only inside that layer.

Roll back: secret, binding, sandbox and rules

Roll back in this order so nothing is left half-removed.

  1. Exit the sandbox. Sandboxes persist after you exit.
  2. If you scoped the secret to the sandbox, remove it while the sandbox still exists: sbx secret rm firecrawl --sandbox firecrawl-shell-01. The credentials page notes that removing a sandbox-scoped secret restores the global secret for that service if one exists, so also remove the global one if you want Firecrawl gone entirely.
  3. Remove the global secret: sbx secret rm firecrawl.
  4. Remove the sandbox: sbx rm firecrawl-shell-01. Files in your workspace are unaffected; packages and state inside the VM are deleted. The network rules page says removing a sandbox also removes the rules scoped to it.
  5. Delete the firecrawl entry from ~/.config/sbx/credentials.yaml. The docs say you can write entries by hand; the binding holds no key, but leaving it pre-approves the next kit that requests the same service for the same domain.
  6. Verify: run sbx secret ls and sbx policy ls, and confirm there is no Firecrawl secret and no allow rule for api.firecrawl.dev that you added. The docs state that sandbox-scoped rules go with the sandbox; they do not explicitly say how kit-declared rules are listed after removal, so this check is the evidence.
  7. Avoid the sledgehammers. sbx policy reset deletes all local rules, restarts the daemon and stops running sandboxes. sbx reset deletes every stored secret along with all sandbox state. Neither is needed to remove one kit.

What the documentation leaves open

Kits are experimental and in Early Access, the v3 specification is targeted for a final release in Q4 2026, and the blog says its steps were current for October 2026. Keep these gaps in mind:

  • The Docker Docs guide launches with sbx run shell while the README and blog use docker/sbx-kit-shell:1.0.0. Confirm which form your sbx version resolves; the kit repository README carries the latest.
  • The documented sbx policy log sample shows no blocked section and no injection column. Confirm on the sbx CLI reference for policy log.
  • The non-interactive flag is spelled two ways. Check sbx run --help.
  • How credential injection behaves on connections the proxy does not decrypt is not described for kit credentials. The credentials page and network rules page are where to confirm.

If you run several sandboxes with different kits, record which kit versions and bindings each one carries. The broader habit of keeping that inventory visible is the subject of our AgentOps guide.

Docker Docs page titled Give sandboxed agents live web access with Firecrawl, as captured from docs.docker.com.
Docker Docs: the official Firecrawl sandbox kit guide page, captured with JavaScript disabled. · Original source

GitHub repository page for firecrawl/firecrawl-docker-sandbox, as captured from github.com.
GitHub: the firecrawl/firecrawl-docker-sandbox repository page, source of the v2 and v3 kit formats, captured with JavaScript disabled. · Original source

Sources

  1. Give sandboxed agents live web access with the Firecrawl kit for Docker Sandboxes, Docker blog, November 16, 2026.
  2. Give sandboxed agents live web access with Firecrawl, Docker Docs guide.
  3. firecrawl/firecrawl-docker-sandbox, kit source and README, GitHub.
  4. docker/sandbox-kit-spec, Docker Sandbox Kit Specification v3, GitHub.
  5. Manage credentials, Docker Docs.
  6. Manage local network rules, Docker Docs.
  7. sbx policy init, Docker CLI reference.
  8. sbx, Docker CLI reference.
  9. Get started with local Docker Sandboxes, Docker Docs.
YOU'RE THROUGH THIS ONE.

Keep connecting the dots.

Back to the library

Many assistants.
One place to remember.

Bring your AI sessions, context, and usage together with Automater.

Meet Automater