Ga naar inhoud

Sandboxbeleid configureren

Of een agentrun in een sandbox draait, wordt op de server beslist, bij het opstarten (--sandbox). De schakelaar Sandboxing inschakelen en de kiezer Backend onder Instellingen → Server → Diagnose en privacy zijn voorkeuren die op je apparaat zijn opgeslagen. De hostdetectie van de kaart Sandboxing meldt wat de serverhost kan omhullen.

Twee besturingselementen bereiken een run, en deze gids behandelt ze beide: de actieregels onder Instellingen → Werkruimte → Agentmachtigingen, die bepalen wat een agent mag pushen, openen of bereiken, en de eigen --sandbox-vlag van de server.

Zes dingen begrenzen een agent. Het eerste is de OS-sandbox, en dat is het voorwaardelijke — de andere vijf gelden op elke host.

Grens Wat het doet
De OS-sandbox Seatbelt op macOS, bubblewrap op Linux en WSL2. Omhult de Claude Code CLI, ACP-adapters en de bash-tool van de harness. Ontbreekt op Windows en op Linux zonder bwrap en socat, waar alleen de runs van de servereigenaar starten
Zijn eigen worktree Elk gesprek krijgt een copy-on-write-checkout. De oorspronkelijke checkout wordt als deny-write-pad in de run opgenomen, en de sandbox is wat dat afdwingt
Inloggegevens via de broker De inloggegevensbroker maakt per run een omgeving aan en trekt die weer in bij het afbreken. Het GitHub-token daarin kan lezen maar niet pushen: een push loopt via Control Center, dat eerst de pushregel raadpleegt
Actiebeveiligingen Elke muterende tool verklaart zijn effectklassen en de beveiliging herleidt ze voordat de aanroep draait. Een prompt zonder verbonden goedkeurder wordt geweigerd
Sanering van de omgeving ACP en de bash-tool van de harness krijgen een gefilterde omgeving. Claude Code via NoSandboxAdapter erft de omgeving van de host
Het tooloppervlak van de modus Een alleen-lezen modus haalt de worktree-muterende tools volledig weg en zet het eigen uitvoerwerkwoord van de modus vast, zodat die toch kan opleveren

Drie dingen blijven zwakker dan ze lijken:

  • Alleen de ingebouwde harness handhaaft de toolpoort, afrondingscontracten en structurele modusregels. De Claude Code-adapter doet dat niet. Claude Code wordt in het bijzonder gestart met --dangerously-skip-permissions, omdat een niet-interactieve claude -p anders voor altijd blijft hangen op zijn eigen prompt — de lees-, schrijf- en bewerkingsaanroepen van Claude zelf worden dus niet door Control Center gezien of door een poort gehaald, en zijn bash-opdrachten controleert alleen een hook die de opdrachtregel leest. Waar de sandbox aan staat, is die de grens eromheen.
  • De in-process bestandstools van de harness (read, write, edit, apply patch, search, find, search_files) draaien in het serverproces, dus geen enkel sandboxprofiel beperkt ze. Alleen de bash-tool gaat door de gesandboxte opdrachtuitvoerder. Die tools worden begrensd door hun eigen padbeperking plus de actiebeveiligingen.
  • Op een host zonder backend starten alleen runs waarvoor de servereigenaar verantwoordelijk is, en voor die runs geldt de eerste rij helemaal niet. Runs van alle anderen worden geweigerd. Onder --sandbox off starten de runs van elk lid zonder de eerste rij. In beide gevallen vallen ACP en de bash-tool van de harness terug op sanering van de omgeving plus het opdrachtbeleid, en erft Claude Code via NoSandboxAdapter de omgeving van de host. De server zegt in zijn opstartlog in welk geval je zit. Controleer het jouwe hieronder.

Er is geen schakelaar per agent voor git push, GitHub, ticketing of het netwerk. Elk daarvan is een actieregel:

Regel Standaardwaarde Wat die dekt
Naar een remote pushen Eerst vragen Elke git push naar GitHub, welke adapter ook
Een pull request openen Eerst vragen De pull-requesttools van Control Center. gh pr create werkt niet in een run
Een pull request bijwerken of samenvoegen Eerst vragen Reacties van een agent op zijn pull request, wijzigingen aan de titel of beschrijving ervan en gepubliceerde reviews, via de tools van Control Center. gh pr comment, gh pr edit, gh pr review, gh pr merge en gh pr close werken niet in een run
Naar een externe tracker schrijven Eerst vragen Ticketschrijfacties via de tools van Control Center en gh issue
Toegang tot het netwerk Toestaan Of de sandbox überhaupt een netwerk heeft, en de webtools van de harness
  1. Ga naar Instellingen → Werkruimte → Agentmachtigingen
  2. Kies het bereik — Werkruimte, Agent of Ruimte — en kies op de rij van de regel Toestaan, Eerst vragen of Weigeren

Pushregels die tot branches zijn beperkt, zoals een regel die pushes naar main weigert, gelden ook: zie Beveiligingen.

Controlepunt: vraag de agent een branch te pushen. Bij Eerst vragen krijg je een goedkeuringsverzoek met de repo en de refs; bij Weigeren toont git ! [remote rejected] <ref> (Control Center policy: …).

Hoe elke regel de run bereikt:

  • Pushen wordt afgedwongen via wat de run bezit. Het GitHub-token dekt de ene repository van de run en kan niet pushen: het kan inhoud lezen en, als het verantwoordelijke lid mag pushen, opmerkingen plaatsen op pull requests. De git-configuratie stuurt elke GitHub-push naar een loopback-gateway op cc_server, die de regel raadpleegt en de push pas daarna doorstuurt met een schrijftoken dat de agent nooit ziet. De gateway stuurt alleen door naar de eigen repo van de worktree of naar een aan de werkruimte gekoppelde GitHub-repo. Dit geldt voor elke adapter.
  • Pull requests en issues vanuit een shell worden herkend aan de opdrachtregel, in de bash-tool van de harness en, via een hook, in de Bash-tool van Claude Code. Een agent die de opdracht verbergt (een script, eval, een directe API-aanroep) komt langs deze controle, maar niet langs de push-gateway.
  • Ticketingsleutels komen nooit in de sandbox. Agenten schrijven tickets via de MCP-tools van Control Center, die de regel raadplegen.
  • Netwerk wordt één keer bepaald, wanneer de run start. Weigeren zet het netwerk van de sandbox uit; Toestaan en Eerst vragen laten het aan, en bij Eerst vragen blijven de tools web_fetch en web_search van de harness bij elke aanroep vragen. Zolang het netwerk aan staat, staat GitHub altijd op de uitgaande allowlist.

Controleren of je agentruns in een sandbox draaien

Sectie getiteld “Controleren of je agentruns in een sandbox draaien”

Twee dingen beslissen dat, beide op de server: of de host een backend biedt en of --sandbox aan staat. Controleer ze in die volgorde.

  1. Ga naar Instellingen → Server → Diagnose en privacy
  2. Lees de kaart Sandboxing. Het gegeven Host is de machine waarop cc_server draait, niet de machine waarnaar je kijkt. Het veld Backend vermeldt Native sandbox (Seatbelt op macOS, bubblewrap op Linux en WSL2) of No isolation. Het gegeven Van kracht is de voorkeur van dit apparaat, niet de omhulling die de server daadwerkelijk gebruikt.
  3. Lees het opstartlog van de server. Het print precies één van drie regels:
    • agent sandbox ON plus de backendmelding — runs worden omhuld
    • no OS-native agent sandbox on this host plus een installatietip waar die er is: alleen runs waarvoor de servereigenaar verantwoordelijk is starten, ongehuld, en die van alle anderen worden geweigerd
    • agent sandbox DISABLED by --sandbox off: de runs van elk lid starten, ongehuld
  4. De blootstellingsregel die bij het opstarten wordt afgedrukt, zegt hetzelfde in één woord: sandbox=native, sandbox=off of sandbox=unavailable.

GET /healthz rapporteert de sandboxstatus niet, dus het opstartlog is de controle.

Alleen de servereigenaar beslist om zonder sandbox te draaien. Om dat voor iedereen te doen, start je de server met --sandbox off, of zet je CC_SERVER_SANDBOX=off. De agents van elk lid draaien dan ongehuld op die machine, dus dit is een beslissing over iedereen die de server gebruikt, eenmaal genomen bij het opstarten. De standaardwaarde is on: die omhult elke run wanneer de host een backend heeft en, wanneer dat niet zo is, start hij alleen de runs van de eigenaar.

Twee situaties krijgen nooit een native sandboxomhulling. Op Windows meldt de native probe altijd dat die niet beschikbaar is en valt er niets te installeren, dus starten alleen de runs van de servereigenaar, tenzij de eigenaar --sandbox off meegeeft. De backend microvm staat apart (interactieve terminals en rigs) en hangt via de probe af van zijn eigen runtime. Op Linux en WSL2 moeten zowel bwrap als socat op het PATH staan; zonder die rapporteert de probe niet beschikbaar en noemt hij de ontbrekende pakketten, en starten alleen de runs van de eigenaar.

Op Linux/WSL2 met bubblewrap geïnstalleerd kunnen de globs voor geheime bestanden uit het standaardbeleid niet worden afgedwongen voor bestanden die een agent later aanmaakt, dus elke native run mislukt in plaats van de regels stil te negeren, ook die van de eigenaar. Een positieve probe bij het opstarten betekent dus niet dat een Linux-dispatch kan starten: vandaag draait een Linux-server agents met --sandbox off, of zonder bubblewrap alleen voor de eigenaar. --sandbox off is een bewuste, onbegrensde uitschakeling, geen vervangende beveiligingsgrens.

De modus wordt per ruimte opgeslagen en voedt de beveiligingsengine als de laag modusvoorinstelling. Drie van de vier modi zijn alleen-lezen, en een alleen-lezen modus weigert twaalf effectklassen zonder meer:

Modus Worktree Geweigerd door de voorinstelling
Agent (chat) Beschrijfbaar Niets — de ingebouwde standaardwaarden gelden
Plan Alleen-lezen Een bestand verwijderen, buiten de worktree schrijven, een commit maken, pushen, een pull request openen, publiceren of mergen, naar een externe tracker schrijven, een pakket installeren, een proces uitvoeren, de werkruimtestructuur wijzigen, een omhulling starten of aansturen, opdrachten op de host uitvoeren
Review Alleen-lezen Dezelfde twaalf. Niet door de gebruiker te selecteren — de composer biedt alleen Agent, Plan en Orkestratie
Orkestratie Alleen-lezen Dezelfde twaalf

Netwerktoegang en toegang tot secrets worden door een alleen-lezen modus bewust niet geweigerd: onderzoek is juist het hele doel ervan.

Goedkeuring is een beslissing van de beveiligingen, niet een sandboxinstelling.

  1. Ga naar Instellingen → Werkruimte → Agentmachtigingen
  2. Zet de actieklasse op Eerst vragen, op het niveau van de werkruimte, de agent of de ruimte

Een beslissing Eerst vragen onderbreekt de run en vraagt het jou. Zonder verbonden goedkeurder valt die gesloten en wordt de actie geweigerd. Zie Beveiligingen configureren voor de volledige bereikresolutie.

Een agent kan niet pushen en ik heb het nooit geweigerd

Sectie getiteld “Een agent kan niet pushen en ik heb het nooit geweigerd”

Lees wat git heeft getoond. Control Center policy: … betekent dat een regel de push heeft geweigerd of dat een Eerst vragen onbeantwoord bleef. … is not linked to this workspace betekent dat de push gericht is op een repo die niet die van de worktree is en ook niet aan de werkruimte is gekoppeld. Control Center has no GitHub credential that can push … betekent dat er geen push-token kon worden aangemaakt: installeer de GitHub App op die repo of log in bij GitHub.

Mijn agentrun is geweigerd met “Deze server heeft geen sandbox”

Sectie getiteld “Mijn agentrun is geweigerd met “Deze server heeft geen sandbox””

De run toont Agents hebben een sandbox nodig op deze server met “Deze server heeft geen sandbox, dus alleen de serverbeheerder kan hier agents uitvoeren. De beheerder kan de sandbox installeren of sandboxing voor iedereen uitzetten.” De machine van de server heeft geen OS-sandbox, en de verantwoordelijke persoon voor de run is niet de servereigenaar, dus er is niets gestart. Bij een schema, webhook of andere automatisering is de verantwoordelijke persoon degene aan wie de automatisering is gebonden, niet wie er toevallig naar kijkt.

Alleen de servereigenaar kan dit veranderen. Op Linux en WSL2 installeert hij bubblewrap en socat en herstart de server (lees eerst de Linux-opmerking hierboven). Op Windows is er geen backend om te installeren. De andere keuze is de server herstarten met --sandbox off, wat de agents van elk lid op die machine zonder inperking laat draaien.

De kaart Sandboxing meldt geen native sandbox

Sectie getiteld “De kaart Sandboxing meldt geen native sandbox”

Dan worden agentruns op die host niet door Seatbelt of bubblewrap omhuld: alleen de runs van de servereigenaar starten, en de overige grenzen zijn wat zij hebben. Installeer op Linux en WSL2 beide ontbrekende tools — sudo apt-get install bubblewrap socat — en herstart de server; het opstartlog zou dan moeten zeggen dat de sandbox aan staat. Op Windows valt er geen native backend te installeren, dus scherp je in plaats daarvan de beveiligingen aan voor de eigen runs van de eigenaar: zie Beveiligingen configureren.

Een agent heeft een bestand buiten zijn worktree bereikt

Sectie getiteld “Een agent heeft een bestand buiten zijn worktree bereikt”

Welke tool het bestand heeft bereikt, bepaalt of dit verwacht gedrag is.

De in-process bestandstools van de harness (read, write, edit, apply patch, search, find, search_files) draaien in het serverproces, dus op hen is geen sandboxprofiel van toepassing — hun grens is hun eigen padbeperking plus de beveiligingen. Een bash-opdracht of de Claude Code CLI wordt wel omhuld waar een backend bestaat, en je geregistreerde checkouts staan binnen die omhulling in elke modus op deny-write, inclusief hun via symlinks herleide spellingen (op macOS herleidt een pad dat via /tmp of /var/folders loopt naar /private, en beide spellingen worden geweigerd). Onder --sandbox off, of voor de eigen runs van de eigenaar op een host zonder backend, geldt niets daarvan. Hoe dan ook kunnen de beveiligingen Buiten de worktree schrijven zonder meer weigeren.