OpenClaw CSB on Podman with OpenShell

This repository builds an OpenClaw Corporate Standard Build (CSB) for Podman. OpenShell supervises the container and enforces the filesystem, process, network, and credential boundaries. This is not an OpenShift deployment.

The baseline intentionally keeps shell execution available so the solution can demonstrate useful agent work. OpenShell independently limits what destinations a command can reach, what files it can write, and what credentials it can access.

Architecture

base/                               -> quay.io/redhat-et/openshell:base-latest
    Containerfile                      UBI 10 minimal + curl, git, iproute, sandbox user
    context/
        entrypoint.sh                  base entrypoint (startup probe marker)
        policy.yaml                    default permissive OpenShell policy
    |
    +-- csb/                        -> quay.io/redhat-et/openclaw:csb-latest
            Containerfile              OpenClaw built from source + Node.js override
            entrypoint.sh              reads secrets, runs configure, starts gateway
            configure-openclaw.mjs     validates inputs, writes locked-down openclaw.json
            policy.yaml                OpenShell deny-by-default network policy
            openclaw-install-policy    blocks runtime skill/plugin installation

CI pipeline: base (amd64 + arm64) → csb (amd64 + arm64) → multi-arch manifest

The CSB image is pinned to OpenClaw v2026.7.1. The local endpoint is http://localhost:18789, bound to loopback by OpenShell.

Prerequisites

• Podman with a running Podman machine where required by the host OS
• OpenShell 0.0.86 or later, with a local Podman-backed gateway selected
• openssl
• An OpenAI API key
• A GitHub token if using the included team-prs demonstration skill

Install OpenShell, then pin its local gateway to Podman. Do not rely on auto-detection when a Docker-compatible Podman socket is also present.

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.0.86 sh
mkdir -p "$HOME/.config/openshell"
printf '%s\n' \
  '[openshell]' \
  'version = 1' \
  '' \
  '[openshell.gateway]' \
  'compute_drivers = ["podman"]' \
  >"$HOME/.config/openshell/gateway.toml"

Restart the gateway so it picks up the Podman driver configuration, then verify it:

# macOS (installer uses Homebrew services)
brew services restart nvidia/openshell/openshell

# Linux (installer uses systemd user service)
# systemctl --user restart openshell-gateway

openshell gateway list
openshell status

Run all commands below from the repository root.

Deploy with OpenShell

1. Create credential providers

OpenShell stores the real credentials at its gateway and gives the sandbox placeholder values. Do not put either API token in the sandbox creation command.

NOTE: The GitHub token is only used for the example skill within this repo to demonstrate adding a skill and the external access.

read -rsp "OpenAI API key: " OPENAI_API_KEY && printf '\n'
export OPENAI_API_KEY
openshell provider create \
  --name openai \
  --type openai \
  --credential OPENAI_API_KEY
unset OPENAI_API_KEY

read -rsp "GitHub token: " GH_TOKEN && printf '\n'
export GH_TOKEN
openshell provider create \
  --name github \
  --type github \
  --credential GH_TOKEN
unset GH_TOKEN

This baseline uses providers for credentials only. It does not enable automatic provider-policy composition; the version-controlled csb/policy.yaml remains the authoritative sandbox policy. If the provider names already exist, inspect them with openshell provider get openai and openshell provider get github rather than recreating them.

2. Create persistent storage and a gateway token

The named Podman volume exists independently of the OpenShell sandbox. Reusing it preserves OpenClaw state, device pairing, conversations, and workspace skills when the sandbox is recreated.

podman volume create openclaw-csb-data
podman run --rm \
  --user 0 \
  --entrypoint /bin/sh \
  -v openclaw-csb-data:/data \
  quay.io/redhat-et/openclaw:csb-latest \
  -c 'chmod 0777 /data'

OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
printf 'Save this OpenClaw gateway token in an approved secret store: %s\n' \
  "$OPENCLAW_GATEWAY_TOKEN"

The token must be supplied on every OpenClaw start. The image writes it only to the required mode-0600 OpenClaw configuration; it does not duplicate it in .env. During an upgrade, the entrypoint removes a legacy gateway-token line from .env while preserving unrelated settings.

3. Create the policy-backed sandbox

The demo explicitly exposes only the repository's team-prs skill. Use [] instead of ["team-prs"] for a skill-free deployment.

openshell sandbox create \
  --name openclaw-csb \
  --from quay.io/redhat-et/openclaw:csb-latest \
  --cpu 2 \
  --memory 4Gi \
  --policy csb/policy.yaml \
  --provider openai \
  --provider github \
  --driver-config-json '{"podman":{"mounts":[{"type":"volume","source":"openclaw-csb-data","target":"/sandbox/persist","read_only":false}]}}' \
  --env OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN" \
  --env OPENCLAW_STATE_DIR=/sandbox/persist/.openclaw \
  --env OPENCLAW_WORKSPACE_DIR=/sandbox/persist/workspace \
  --env OPENCLAW_DEFAULT_MODEL=openai/gpt-5.5 \
  --env OPENCLAW_PROVIDERS='{"openai":{"api":"openai-responses","baseUrl":"https://api.openai.com/v1"}}' \
  -- /bin/true

unset OPENCLAW_GATEWAY_TOKEN

The short initial command returns control to the operator while OpenShell keeps the sandbox. If creation fails because the name is already in use, remove the old sandbox with openshell sandbox delete openclaw-csb. The volume initialization uses mode 0777 because the OpenShell Podman driver mounts an existing volume as root-owned before dropping the agent process to UID/GID 1001. The volume is private to rootless Podman and mounted only into this sandbox; all agent-created content is still owned by sandbox:sandbox.

4. Upload the demonstration skill

The allowlist controls discovery; the skill file must also exist in the persistent workspace.

openshell sandbox exec -n openclaw-csb -- \
  mkdir -p /sandbox/persist/workspace/skills/team-prs
openshell sandbox upload openclaw-csb \
  skills/team-prs/SKILL.md \
  /sandbox/persist/workspace/skills/team-prs/SKILL.md

5. Start OpenClaw and the loopback forward

Start the gateway in the background, wait for the health endpoint to confirm it is ready, then start an OpenShell-managed background forward. The local bind is explicit so the Control UI is not exposed to the LAN.

openshell sandbox exec -n openclaw-csb -- \
  /app/entrypoint.sh >/dev/null 2>&1 &
until openshell sandbox exec -n openclaw-csb -- \
  curl -fsS http://127.0.0.1:18789/healthz 2>/dev/null; do sleep 1; done
openshell forward start 18789 openclaw-csb --background

The first command launches the gateway inside the sandbox. The loop retries the health endpoint every second until the gateway is accepting connections. The forward starts only after the gateway is verified ready.

If the forward reports that the port is busy, stop the process using port 18789 or choose a different local port. Start a new agent conversation after changing workspace skills so OpenClaw refreshes the prompt-visible snapshot.

6. Connect

Open http://localhost:18789 and paste the saved gateway token. The forward is bound to 127.0.0.1; it is not exposed to the LAN.

If you need to retrieve the gateway token from a running sandbox:

openshell sandbox connect openclaw-csb
grep token /sandbox/persist/.openclaw/openclaw.json

Validate the Deployment

Confirm the effective policy

openshell sandbox get openclaw-csb --policy-only

Compare the result with csb/policy.yaml. It should show:

• /sandbox, /tmp, and /dev/null as the only declared writable paths
• the child process identity sandbox:sandbox
• OpenAI access only from /usr/bin/node for the three declared API routes
• read-only GitHub REST access only from /usr/bin/curl
• no policy entry for arbitrary internet destinations

Confirm OpenClaw controls

Connect to the sandbox and run the checks interactively:

openshell sandbox connect openclaw-csb

openclaw skills list
openclaw config get agents.defaults.skills
openclaw config get tools.exec.mode
echo '{"target":"skill"}' | /usr/local/bin/openclaw-install-policy
openclaw security audit --deep

skills list is an installation and eligibility inventory, so it can include bundled skills that are not visible to the agent. The effective agents.defaults.skills should list the expected workspace skills (or be absent to allow all). The exec mode must be full, and the image-owned install policy must return a block decision. Review every deep-audit warning in the context of the OpenShell loopback forward and sandbox boundary.

Demonstrate useful, constrained exec

NOTE: This is the reason for the GitHub PAT

In the Control UI, invoke /team-prs — the agent runs curl to query GitHub. This demonstrates that exec works while OpenShell controls what destinations are reachable.

Ask the agent to run these checks. Each maps to a threat in the threat model.

Policy Model

OpenClaw decides which application features the agent may request. OpenShell enforces what the process can actually access, including after a command is approved.

Status meanings: Permit allows the operation, conditional allows it only within the stated boundary, deny blocks it, and not controlled means the layer does not make that authorization decision.

OpenClaw permissions

The entrypoint rewrites these application controls at every start with OPENCLAW_NIX_MODE=1. To modify these settings, edit csb/configure-openclaw.mjs and rebuild the image:

Capability	Status	OpenClaw boundary
Shell execution	Permit	tools.exec.mode: "full"; OpenShell is the enforcement layer (see note below)
Workspace skills	Permit	All workspace skills available; set OPENCLAW_ALLOWED_SKILLS to restrict
Cron / scheduled tasks	Permit	Enabled for unattended skill execution
Bundled skills	Deny	Disabled individually via skills.entries.<name>.enabled: false (allowBundled: [] not enforced by this OpenClaw version)
Runtime skill or plugin installation	Deny	Root-owned security.installPolicy returns a block decision
Plugins	Deny	Globally disabled with an empty allowlist
Browser and canvas tools	Deny	Listed in tools.deny
Web fetch and web search tools	Deny	Listed in tools.deny; this does not authorize shell network access
Elevated execution	Deny	tools.elevated.enabled: false
File tools inside the workspace	Permit	tools.fs.workspaceOnly: true
File tools outside the workspace	Deny	Workspace-only boundary; this does not constrain arbitrary shell syscalls
Uploaded skill archives	Deny	skills.install.allowUploadedArchives: false
Runtime config commands	Deny	Nix mode blocks OpenClaw config mutation commands
mDNS discovery	Deny	Discovery mode is off
Control UI access	Conditional	Requires the configured gateway bearer token

Why exec.mode: "full" instead of "ask"

OpenClaw offers several exec modes:

Mode	Behavior	Cron-compatible	Always Allow
deny	Block all execution	N/A	N/A
allowlist	Only profiled safeBins	Yes	N/A
ask	Human approval per command	No — unattended prompts expire	No (by design)
auto	AI classifier + human approval on miss	No — same expiry issue	No (policy blocks it)
full	All execution permitted	Yes	N/A

The CSB uses full because:

• Cron/scheduled skills require unattended execution. Modes that require human approval (ask, auto) block indefinitely when no operator is present, causing scheduled skills to fail silently.
• OpenShell is the enforcement layer. Network destinations, credential access, and filesystem writes are controlled by the sandbox policy regardless of what OpenClaw permits. A command can run, but it can only reach approved endpoints.
• allowlist mode is fragile. It requires safeBinProfiles definitions that break across OpenClaw versions.

NOTE: To revert to human-in-the-loop approval (disabling cron), change execTools.mode in csb/configure-openclaw.mjs from "full" to "ask". This will most likely need to be a decision point or a potential upstream change to see if we can segment cron out to be "full" while sessions are "ask" but the complexity in that is TBD.

OpenShell permissions

OpenShell applies these process-level controls even after OpenClaw approves a command. To modify these settings, edit csb/policy.yaml and recreate the sandbox with the updated policy:

Capability	Status	OpenShell boundary
Run a process	Conditional	Runs as unprivileged sandbox:sandbox with the sandbox process controls
Read declared system/application paths	Permit	/usr, /lib, /proc, /dev/urandom, /app, /etc, and /var/log are read-only
Write sandbox state	Permit	/sandbox, /tmp, and /dev/null are declared read-write
Write system/application paths	Deny	Read-only paths cannot be modified; undeclared paths are inaccessible through Landlock when enforced
OpenAI API from Node	Conditional	/usr/bin/node may use GET /v1/models, POST /v1/responses, and POST /v1/chat/completions
GitHub API from curl	Conditional	/usr/bin/curl has read-only REST access to api.github.com
GitHub write methods	Deny	POST, PUT, PATCH, and DELETE do not match the read-only policy
Other destinations, binaries, methods, or paths	Deny	No matching network policy means default deny
Read a real provider credential	Deny	Real credentials remain at the gateway; the sandbox receives placeholders
Landlock on an unsupported host	Conditional	best_effort warns and degrades; validation must check host support
Host access to the Control UI	Conditional	OpenShell forward binds to 127.0.0.1:18789
OpenClaw skills, plugins, hooks, or cron semantics	Not controlled	OpenShell constrains resulting processes and access, not OpenClaw feature visibility

Overlapping and effective controls

Capability	OpenClaw decision	OpenShell decision	Effective result	Enforced by
Run any command	Permitted (exec.mode: "full")	Runs as sandbox:sandbox	Runs, but sandbox-constrained	OpenShell
Read/write the workspace	File tools permitted in workspace	/sandbox is read-write	Permitted	Both
Use file tools outside the workspace	Denied by workspace-only tools	Only declared paths are accessible	Blocked	Both
Shell writes outside the workspace	Not blocked by workspaceOnly	Filesystem policy and unprivileged identity apply	Only declared writable paths succeed	OpenShell
Query GitHub with curl	Permitted	Read-only GitHub REST access for /usr/bin/curl	Read requests succeed	OpenShell
Modify GitHub with curl	Permitted	Write methods denied by policy	Blocked	OpenShell
Reach an unlisted host	Permitted	Destination has no matching policy	Blocked	OpenShell
Call OpenAI	Model use is configured	Node is limited to three API routes	Only declared model requests succeed	Both
Install a skill or plugin	Install policy blocks	Network and filesystem constrained	Blocked before install	OpenClaw, plus OpenShell
Use a bundled skill	Disabled by skills.entries	No skill-awareness	Not available to the agent	OpenClaw
Read a provider secret	Only a placeholder is visible	Real secret retained at gateway	Real credential is not exposed	OpenShell
Schedule a cron task	Permitted	Scheduled command subject to same sandbox constraints	Runs within sandbox boundary	OpenShell
Access the Control UI remotely	Token authentication required	Host forward is loopback-only	Requires local host access and the token	Both
Mutate OpenClaw config through its CLI	Nix mode denies	Config is under writable sandbox state	CLI mutation blocked; arbitrary approved shell writes are not an OpenShell semantic control	OpenClaw

OpenClaw controls are defense in depth. OpenShell is the enforcement boundary for arbitrary code executed inside the sandbox.

Network and egress control

Prompt	Expected	Threat addressed
Run: curl https://api.github.com	Succeeds (with OpenShell)	Approved destination reachable
Run: curl -X POST https://api.github.com/user	Blocked	Write methods denied on read-only endpoint
Run: curl https://example.com	Blocked (with OpenShell)	Arbitrary egress / data exfiltration
Run: curl https://clawhub.openclaw.ai	Blocked (with OpenShell)	Marketplace access prevented

Filesystem and write control

Prompt	Expected	Threat addressed
Write a file to /sandbox/persist/workspace/proof.txt	Succeeds	Workspace writes permitted
Write a file to /etc/proof.txt	Blocked	System file tampering
Write a file to /app/dist/index.js	Blocked	Application binary tampering

Self-modification and plugin control

Prompt	Expected	Threat addressed
Run: openclaw config set plugins.enabled true	Blocked (NIX_MODE)	Config self-modification
Run: openclaw plugins install slack	Blocked (NIX_MODE)	Runtime plugin injection
Run: openclaw skills install web-search	Blocked (install policy)	Marketplace skill installation

Credential isolation (with OpenShell)

Prompt	Expected	Threat addressed
Run: echo $OPENAI_API_KEY	Shows placeholder, not real key	Credential exposure
Run: echo $GH_TOKEN	Shows placeholder, not real key	Credential exposure
Run: cat /sandbox/.openclaw/openclaw.json | grep token	Shows gateway token (expected)	Gateway token is local-only

Skill visibility

Prompt	Expected	Threat addressed
What skills are available?	Only workspace skills (e.g. team-prs)	Bundled skill leakage
Search ClawHub for a skill	Blocked (clawhub skill disabled)	Marketplace access

Without OpenShell (bare podman), network checks will succeed — only filesystem and OpenClaw config controls are enforced. With OpenShell, the csb/policy.yaml deny-by-default policy blocks unapproved destinations.

An HTTP 401 or 403 from an allowed upstream proves the route was reached — that is not a policy failure. An OpenShell proxy denial or failed connection indicates a policy block.

Upgrade and Recreate

Save the gateway token before deleting the sandbox. Then recreate it with the same volume and the complete command from deployment step 3.

openshell sandbox delete openclaw-csb
podman pull quay.io/redhat-et/openclaw:csb-latest

# Repeat deployment steps 3 through 5 with the same openclaw-csb-data volume
# and saved OPENCLAW_GATEWAY_TOKEN, then validate the effective policy again.

Known Base-Image Workaround

The runtime copies Node.js 24 from the pinned upstream bookworm-slim image because the current UBI Node builds contain SQLite 3.46.1. OpenClaw requires the newer SQLite bundled with that runtime. Revisit the override when the UBI base ships a compatible SQLite release.