On OpenShell 0.1.2 a rule added without --binary lets no program through. The doc says a --no-keep run cannot be changed after it ends.
5.4 KiB
Run OpenWorker inside an OpenShell sandbox
OpenShell is NVIDIA's sandbox runtime for agents. This page runs the OpenWorker CLI inside an OpenShell sandbox: the coworker, its tools and the files it works on are all in the sandbox, and OpenShell decides what it can reach.
This is different from OpenShell as the sandbox for the desktop app, where OpenWorker runs on your computer and only its commands run in a sandbox.
Tested with OpenShell 0.1.2 on a Mac with Docker Desktop.
What you need
- OpenShell 0.1.2, with its gateway running (
openshell statussaysConnected). - Docker. On a Mac, host networking turned on in Docker Desktop (Settings ▸ Resources ▸ Network ▸ Enable host networking).
- A model API key from OpenAI or Anthropic.
1. Get the image
The image holds the OpenWorker CLI and common developer tools: Python, Node, git, curl,
ripgrep, gh, uv, make and a C compiler.
Build it from a checkout of this repository:
docker build -f packaging/openshell/Dockerfile -t openworker-openshell:local .
2. Give OpenShell your model key
OpenShell keeps the key. Inside the sandbox OpenWorker only sees a placeholder, and OpenShell puts the real key on requests to the model provider and nowhere else.
For OpenAI:
openshell profile import -f packaging/openshell/providers/openworker-openai.yaml
export OPENAI_API_KEY=... # your key
openshell provider create --name openworker-openai --type openworker-openai --from-existing
For Anthropic, use openworker-anthropic.yaml, ANTHROPIC_API_KEY and the name
openworker-anthropic in the same three commands.
You do this once. The provider stays on your gateway.
3. Run a task
One command starts a sandbox, runs the task and removes the sandbox:
openshell sandbox create --from openworker-openshell:local \
--provider openworker-openai --no-keep \
-- openworker run --approval-mode bypass-approvals --prompt "Say hello"
The answer is printed in your terminal. Everything after -- is the normal
openworker run command.
--approval-mode bypass-approvals lets the coworker act without asking, which is reasonable
here because the sandbox is what contains it. The other modes are on the
openworker run page.
4. Work on your own files
A sandbox has its own files. Bring a project in, run the task, and take the result out:
# A sandbox that stays up
openshell sandbox create --name work --from openworker-openshell:local \
--provider openworker-openai --detach -- sleep infinity
# Copy the project in. It lands at /sandbox/my-project
openshell sandbox upload work ./my-project /sandbox
# Run a task in it
openshell sandbox exec -n work --workdir /sandbox/my-project \
-- openworker run --approval-mode bypass-approvals --prompt "Fix the failing test"
# Copy a file, or the whole folder, back out
openshell sandbox download work /sandbox/my-project ./my-project-result
# Remove the sandbox when you are done
openshell sandbox delete work
Choose a coworker
It is the same image for every coworker. Name the one you want with --coworker:
openshell sandbox exec -n work --workdir /sandbox/my-project \
-- openworker run --coworker code --prompt "Fix the failing test"
cowork is the default. An unknown id stops the run and lists the ids the image has.
Choose a model
Add --model provider:model, for example --model openai:gpt-5.6-sol. The provider you
attached has to match: a sandbox with only the OpenAI provider cannot reach Anthropic.
Sites
A sandbox reaches only what OpenShell's policy allows. With the provider attached, that is the model API and nothing else. A command or web fetch to any other site fails, and the coworker is told that the sandbox blocked it.
To allow a site, on your computer:
openshell policy update work --add-endpoint pypi.org:443 --binary '/**' --wait
--binary says which programs may use the site. '/**' means any program in the sandbox;
name one, such as /usr/bin/curl, to keep it to that program. Do not leave --binary out:
OpenShell then adds a rule that lets no program through. The change reaches the running
sandbox in a few seconds, with no restart.
The sandbox has to be running to be changed. A run started with --no-keep (step 3) is
gone when it ends, so for work that needs sites use a sandbox that stays up (step 4),
allow the sites, and run the task again.
OpenShell can also draft these rules from the requests it blocked, for you to approve. That is its policy advisor; see OpenShell's guide.
OpenWorker's own --allow-site has no effect inside OpenShell: the sandbox's policy is
OpenShell's to change, not OpenWorker's.
GitHub
Attach OpenShell's GitHub provider and the coworker can use gh and git. OpenShell puts
your token on requests from those two programs only. See OpenShell's guide for
GitHub push access.
What is different inside a sandbox
- Connectors from the desktop app are not there. The sandbox starts with no settings.
- Each run is saved in the sandbox, under
/sandbox/.config/coworker/sessions/. It is gone when the sandbox is deleted, so download what you want to keep. - A program the coworker starts can use the model key in the same way OpenWorker can. It cannot read the key.