Python
An image of the CLI for OpenShell, provider profiles, and how to use them
Rohit C Prasad020263b5bd98
diff --git a/.dockerignore b/.dockerignorenew file mode 100644index 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.mdnew file mode 100644index 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/Dockerfilenew file mode 100644index 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 sandboxdiff --git a/packaging/openshell/providers/openworker-anthropic.yaml b/packaging/openshell/providers/openworker-anthropic.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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]