Run Pi with OpenRouter
Build a Pi coding-agent image, configure OpenRouter access, and run Pi inside an OpenShell sandbox.
In this tutorial, we’ll run Pi, a terminal coding agent, inside an OpenShell sandbox. Pi works with many model providers out of the box, including OpenRouter, which we use here.
We’ll build a Pi image, give the sandbox access to OpenRouter, and start Pi. The sandbox lets Pi reach OpenRouter but nothing else on the network. OpenShell supplies Pi with an opaque placeholder for your API key.
Prerequisites
Section titled “Prerequisites”You’ll need:
- A working OpenShell installation with an active gateway. Refer to Installation.
- Docker or Podman to build the image.
- An OpenRouter API key.
Build the Pi Image
Section titled “Build the Pi Image”Pi doesn’t publish a container image, so we’ll build one from its npm package,
based on Pi’s container guide.
Save this Dockerfile as Dockerfile.pi:
FROM node:24-bookworm-slim
ARG PI_VERSION=latest
RUN apt-get update \ && apt-get install -y --no-install-recommends bash ca-certificates fd-find git ripgrep \ && ln -s /usr/bin/fdfind /usr/local/bin/fd \ && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts "@earendil-works/pi-coding-agent@${PI_VERSION}"
RUN mkdir -p /workspace && chown node:node /workspaceUSER nodeWORKDIR /workspace
ENV PI_CODING_AGENT_DIR=/tmp/pi-agentWe add two things to Pi’s guide because the sandbox limits what Pi can reach:
- We install
fd. Pi usesfdandripgrepto search files, and if they’re missing, it downloads them from GitHub on first use. The sandbox blocks that download, so the image includes both. - We set
PI_CODING_AGENT_DIRso Pi keeps its settings and sessions in/tmp, one of the few places the sandbox lets Pi write.
Now build the image:
docker build -t pi-agent:local -f Dockerfile.pi .Give Pi Access to OpenRouter
Section titled “Give Pi Access to OpenRouter”A sandbox has no network access until you grant it. To let Pi reach
OpenRouter, we’ll create a provider, which stores your API key and opens access
to the service. Pi receives an opaque placeholder in OPENROUTER_API_KEY.
OpenShell substitutes the real key in requests authorized for OpenRouter. See
How Credential Injection Works
for credential delivery and response-handling limits.
A provider is built from a provider profile, which describes the service. Save
this one as provider-openrouter.yaml:
id: openrouterdisplay_name: OpenRouterdescription: Direct OpenRouter inference accesscategory: inferenceinference_capable: true
credentials: - name: api_key description: OpenRouter API key env_vars: - OPENROUTER_API_KEY required: true auth_style: bearer header_name: authorization
discovery: credentials: - api_key
endpoints: - host: openrouter.ai port: 443 protocol: rest access: read-write enforcement: enforce
binaries: - /usr/local/bin/nodeHere’s what the main sections do:
credentialsdeclares the API key. Pi finds the placeholder inOPENROUTER_API_KEY.endpointsauthorizes requests and credential injection foropenrouter.ai.binariesallows onlynodeto use this access. Pi runs on Node.js, so that includes Pi.
Check the profile, import it, and create a provider named openrouter:
openshell profile lint -f provider-openrouter.yamlopenshell profile import -f provider-openrouter.yaml
OPENROUTER_API_KEY=your-key \ openshell provider create \ --name openrouter \ --type openrouter \ --from-existingReplace your-key with your OpenRouter API key, or drop that prefix if
OPENROUTER_API_KEY is already set in your shell. --from-existing tells
OpenShell to read the key from that variable.
Start Pi in a Sandbox
Section titled “Start Pi in a Sandbox”Next, create a sandbox from the image, attach the provider, and start Pi:
openshell sandbox create \ --name pi \ --from pi-agent:local \ --provider openrouter \ -- piEverything after -- runs inside the sandbox, so Pi and any commands it runs
stay contained.
Pi starts with its default OpenRouter model. To pick a different one, type
/model and choose any OpenRouter model from the list. OpenRouter usually has
some free models, marked with a :free suffix, which are handy for trying this
out without spending credits.
Then give Pi a try:
Explain what files are available in this workspace.The workspace starts empty, but we’ll give Pi your own code in a later step.
Inspect the Sandbox
Section titled “Inspect the Sandbox”While Pi is running, open another terminal and take a look at the sandbox’s status, access, providers, and logs:
openshell sandbox listopenshell policy get pi --fullopenshell sandbox provider list piopenshell logs pi --tailopenshell logs streams the sandbox’s activity, including any connections it
blocks. When you’re done, type /quit in Pi to exit.
Work on a Local Project
Section titled “Work on a Local Project”To point Pi at your own code, run this from your project directory. --upload
copies the directory into the sandbox, skipping anything .gitignore excludes.
You cannot combine --upload with a trailing command, so start Pi from the
shell that opens.
openshell sandbox create \ --name pi-project \ --from pi-agent:local \ --provider openrouter \ --upload .:/workspaceIn the sandbox shell, run pi.
Pi’s changes stay inside the sandbox. To copy them back, run
openshell sandbox download from another terminal while Pi is still running.
Refer to Transfer Files.
Clean Up
Section titled “Clean Up”When you’re finished, delete both sandboxes:
openshell sandbox delete pi pi-projectTroubleshooting
Section titled “Troubleshooting”- If the gateway can’t find
pi-agent:local, make sure you built the image with the same container engine your gateway uses, or pushed it to a registry the gateway can reach. - If Pi’s requests to OpenRouter are denied, make sure the
binariespath in the profile matches wherenodeis installed in your image. In the image above, that’s/usr/local/bin/node.
Next Steps
Section titled “Next Steps”- To give Pi more tools, add them to the image. To let Pi reach package registries, source hosts, or other services, grant access with a sandbox policy.
- To use a different model service, write a provider profile for it. The
providers/directory has examples, and Profiles describes each field. - To learn about images, resources, file transfer, and the sandbox lifecycle, refer to Sandboxes.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.