mirror of
https://github.com/andrewyng/openworker.git
synced 2026-11-16 23:37:47 +00:00
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.
145 lines
5.4 KiB
Markdown
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.
|