Files
openworker/docs/openshell-inside.md
T
Rohit C Prasad a2b0225580 Inside OpenShell: the allow-a-site command the agent gives is the whole command
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.
2026-10-05 05:45:16 -07:00

145 lines
5.4 KiB
Markdown

# Run OpenWorker inside an OpenShell sandbox
[OpenShell](https://github.com/NVIDIA/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](openshell.md), 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 status` says `Connected`).
- 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:
```bash
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:
```bash
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:
```bash
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`](headless.md) 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`](headless.md) 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:
```bash
# 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`:
```bash
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:
```bash
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](https://docs.nvidia.com/openshell/latest/how-it-works/policies/advisor).
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](https://docs.nvidia.com/openshell/latest/tutorials/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.