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, plus a parallel csb-openclaw-only (amd64 + arm64) → multi-arch manifest pipeline for the OpenClaw-only variant below.

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

OpenClaw-only variant

csb/Containerfile.openclaw builds OpenClaw without OpenShell: no OpenShell CLI, no sandbox policy, and the openshell OpenClaw extension is not opted in. Both build and runtime stages share one Hardened Images base (registry.access.redhat.com/hi/nodejs), so no separate Node-runtime stage or binary swap is needed. Images are tagged quay.io/redhat-et/openclaw:csb-openclaw-only-*.

This variant has no OpenShell enforcement layer — only the OpenClaw-level controls in Policy Model apply; the OpenShell rows in that section (network egress, filesystem Landlock, credential placeholders) do not apply here. Use it only where the OpenShell sandbox boundary is provided some other way, or for workloads that don't need it.

The app's own gateway.bind setting is "lan" (it binds inside the container regardless of variant); with OpenShell that's made loopback-only by the forward command's explicit 127.0.0.1 binding. This variant has no forward step, so publish the port to loopback yourself:

podman build -f csb/Containerfile.openclaw -t localhost/openclaw-openclaw-only .
podman run --rm -p 127.0.0.1:18789:18789 \
  -e OPENAI_API_KEY \
  -e OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)" \
  localhost/openclaw-openclaw-only

Prerequisites

• Podman with a running Podman machine where required by the host OS and the openshell Podman network created (podman network create openshell)
• 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

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.

The commands work in an interactive macOS or Linux zsh or bash shell. Copy a complete code block at a time.

Quickstart

1. Create credential providers

OpenShell stores real credentials at its gateway. Do not put either secret in a sandbox creation command. The GitHub provider is used by the included team-prs demonstration skill.

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

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

If those providers already exist, inspect them with openshell provider get openai and openshell provider get github rather than recreating them.

2. Create, start, and forward OpenClaw

The Quickstart creates the sandbox, uploads skills, starts OpenClaw, and opens the loopback forward. See manual setup for the full copy/paste deployment sequence. It reuses an existing openclaw-csb sandbox, which makes a failed or interrupted Quickstart safe to rerun.

./scripts/openclaw-csb quickstart

By default, it uploads this repository's skills/ directory. To upload another skills root, pass --skills-dir; each immediate child must contain SKILL.md. Quickstart replaces matching skill directories in the persistent workspace.

./scripts/openclaw-csb quickstart --skills-dir /path/to/skills

All uploaded workspace skills are visible by default. Restrict that set with repeatable --allow-skill flags, using each skill's name from SKILL.md.

./scripts/openclaw-csb quickstart \
  --allow-skill team-prs \
  --allow-skill my-skill

Plugins are disabled by default. Enable specific plugin IDs with repeatable --allow-plugin flags:

./scripts/openclaw-csb quickstart --allow-plugin my-plugin

--allow-skill and --allow-plugin only take effect when the sandbox is created. Quickstart reuses an existing openclaw-csb sandbox as-is and does not update its environment, so changing either flag on a later run has no effect until you delete and recreate the sandbox — see Upgrade and Recreate.

To use a locally built image:

OPENCLAW_CSB_IMAGE=localhost/openclaw-csb:ux ./scripts/openclaw-csb quickstart

3. Access the OpenClaw Control UI

Copy the stored token immediately before opening the UI, because the Quickstart commands may have replaced your clipboard:

./scripts/openclaw-csb token-copy

Then open http://localhost:18789 and paste the token. The forward is bound to 127.0.0.1; it is not exposed to the LAN. The default agent ID is main. OpenClaw creates its workspace files on the first successful agent turn.

Manual setup

For the provider, token, sandbox, skill-upload, and forward commands, see docs/manual-setup.md.

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	Conditional	Disabled unless OPENCLAW_ALLOWED_PLUGINS is set; then only the listed plugin IDs are enabled
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.