Skip to content
Python

An image of the CLI for OpenShell, provider profiles, and how to use them

Rohit C Prasad020263b5bd98
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..6a41aa55
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,8 @@
+# The only image built from this repository is packaging/openshell/Dockerfile, and it
+# needs the CLI's source and nothing else.
+*
+!pyproject.toml
+!README.md
+!LICENSE
+!coworker
+**/__pycache__
diff --git a/docs/openshell-inside.md b/docs/openshell-inside.md
new file mode 100644
index 00000000..a87bf9cb
--- /dev/null
+++ b/docs/openshell-inside.md
@@ -0,0 +1,139 @@
+# 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. The change reaches the
+running sandbox in a few seconds, with no restart.
+
+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.
diff --git a/packaging/openshell/Dockerfile b/packaging/openshell/Dockerfile
new file mode 100644
index 00000000..d9c25091
--- /dev/null
+++ b/packaging/openshell/Dockerfile
@@ -0,0 +1,59 @@
+# OpenWorker's CLI in an image for OpenShell (https://github.com/NVIDIA/OpenShell):
+#
+# openshell sandbox create --from ghcr.io/andrewyng/openworker-openshell:latest \
+# --provider <your model provider> -- openworker run --prompt "..."
+#
+# What OpenShell asks of an image: a standard Linux base, a non-root USER, and iproute2
+# (nftables lets it also log direct connections). The rest is the CLI and the tools an
+# agent's commands usually reach for. See docs/openshell-inside.md.
+#
+# Build from the repository root, so the CLI in the image is this checkout:
+# docker build -f packaging/openshell/Dockerfile -t openworker-openshell:local .
+
+FROM node:22-bookworm-slim AS node
+
+FROM python:3.13-slim-bookworm
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates curl wget git openssh-client \
+ iproute2 nftables \
+ ripgrep fd-find jq less nano tree procps \
+ unzip zip xz-utils make build-essential \
+ && ln -s /usr/bin/fdfind /usr/local/bin/fd \
+ && rm -rf /var/lib/apt/lists/*
+
+# GitHub's own CLI: with OpenShell's GitHub provider attached, `gh` is how an agent
+# reaches GitHub (the credential is swapped in for `gh` and `git` only).
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# Node and npm, from Node's own image.
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+ && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
+RUN pip install --no-cache-dir uv
+
+# The CLI lives in a virtual environment of its own, apart from the Python an agent's
+# project uses. Two things about where:
+# - under /usr, because OpenShell's default policy lets a sandbox read /usr and not /opt
+# (with the CLI in /opt the sandbox could not even start it: "Permission denied");
+# - `--copies`, so the environment has its own interpreter file and an OpenShell provider
+# profile can name OpenWorker (/usr/local/lib/openworker/venv/bin/python) and not every
+# Python program in the sandbox.
+COPY pyproject.toml README.md LICENSE /tmp/openworker-src/
+COPY coworker /tmp/openworker-src/coworker
+RUN python -m venv --copies /usr/local/lib/openworker/venv \
+ && /usr/local/lib/openworker/venv/bin/pip install --no-cache-dir /tmp/openworker-src \
+ && ln -s /usr/local/lib/openworker/venv/bin/openworker /usr/local/bin/openworker \
+ && rm -rf /tmp/openworker-src
+
+# The account agents run as, with /sandbox as its home and the place work happens.
+RUN groupadd --gid 1000 sandbox \
+ && useradd --uid 1000 --gid sandbox --home-dir /sandbox --create-home --shell /bin/bash sandbox
+WORKDIR /sandbox
+USER sandbox
diff --git a/packaging/openshell/providers/openworker-anthropic.yaml b/packaging/openshell/providers/openworker-anthropic.yaml
new file mode 100644
index 00000000..19ddf0cc
--- /dev/null
+++ b/packaging/openshell/providers/openworker-anthropic.yaml
@@ -0,0 +1,35 @@
+# OpenShell provider profile: OpenWorker calling Anthropic models.
+#
+# openshell profile import -f packaging/openshell/providers/openworker-anthropic.yaml
+# ANTHROPIC_API_KEY=... openshell provider create --name openworker-anthropic \
+# --type openworker-anthropic --from-existing
+#
+# Client binary: OpenWorker's own Python, as installed in
+# ghcr.io/andrewyng/openworker-openshell (packaging/openshell/Dockerfile).
+# Commands OpenWorker starts count as OpenWorker too.
+# Credential scope: ANTHROPIC_API_KEY, sent in the x-api-key header to
+# api.anthropic.com and nowhere else. Inside the sandbox the variable
+# holds a placeholder.
+# Endpoint access: api.anthropic.com, read-write, L7 enforced.
+
+id: openworker-anthropic
+display_name: OpenWorker (Anthropic)
+description: OpenWorker CLI with Anthropic models
+category: agent
+inference_capable: true
+credentials:
+ - name: api_key
+ description: Anthropic API key
+ env_vars: [ANTHROPIC_API_KEY]
+ required: true
+ auth_style: header
+ header_name: x-api-key
+discovery:
+ credentials: [api_key]
+endpoints:
+ - host: api.anthropic.com
+ port: 443
+ protocol: rest
+ access: read-write
+ enforcement: enforce
+binaries: [/usr/local/lib/openworker/venv/bin/python]
diff --git a/packaging/openshell/providers/openworker-openai.yaml b/packaging/openshell/providers/openworker-openai.yaml
new file mode 100644
index 00000000..379c7f4a
--- /dev/null
+++ b/packaging/openshell/providers/openworker-openai.yaml
@@ -0,0 +1,34 @@
+# OpenShell provider profile: OpenWorker calling OpenAI models.
+#
+# openshell profile import -f packaging/openshell/providers/openworker-openai.yaml
+# OPENAI_API_KEY=... openshell provider create --name openworker-openai \
+# --type openworker-openai --from-existing
+#
+# Client binary: OpenWorker's own Python, as installed in
+# ghcr.io/andrewyng/openworker-openshell (packaging/openshell/Dockerfile).
+# Commands OpenWorker starts count as OpenWorker too.
+# Credential scope: OPENAI_API_KEY, sent as a bearer token to api.openai.com and
+# nowhere else. Inside the sandbox the variable holds a placeholder.
+# Endpoint access: api.openai.com, read-write, L7 enforced.
+
+id: openworker-openai
+display_name: OpenWorker (OpenAI)
+description: OpenWorker CLI with OpenAI models
+category: agent
+inference_capable: true
+credentials:
+ - name: api_key
+ description: OpenAI API key
+ env_vars: [OPENAI_API_KEY]
+ required: true
+ auth_style: bearer
+ header_name: authorization
+discovery:
+ credentials: [api_key]
+endpoints:
+ - host: api.openai.com
+ port: 443
+ protocol: rest
+ access: read-write
+ enforcement: enforce
+binaries: [/usr/local/lib/openworker/venv/bin/python]