@shadowob/cloud 1.1.6-dev.311

package/images/claude-runner/RUNNER.md

@@ -0,0 +1,222 @@
+# Claude Code Runner Research
+
+Research date: 2026-05-14.
+
+## Target role
+
+`claude-code` should run through the ShadowOB `cc-connect` fork, not through
+OpenClaw gateway or ACPX. The runner process should be:
+
+```text
+cc-connect fork -> agent type "claudecode" -> claude CLI
+```
+
+Shadow messaging, DMs, slash commands, attachments, and typing/progress should
+come from the cc-connect ShadowOB platform.
+
+## Current repository state
+
+The previous `apps/cloud` adapter declared:
+
+```text
+openclaw gateway -> ACPX plugin -> claude CLI process
+```
+
+The current adapter and Dockerfile now use the cc-connect fork path. The runner
+package emits `cc-connect-config.toml`, Claude settings, MCP config, and
+ShadowOB skill files through `runtime-files.json`.
+
+## Native Claude Code configuration
+
+Claude Code has its own hierarchy and should not be flattened into OpenClaw
+agent defaults:
+
+| Concern | Native Claude Code surface |
+| --- | --- |
+| Settings | `~/.claude/settings.json`, project `.claude/settings.json`, local `.claude/settings.local.json`, managed settings. |
+| Models | `model`, `availableModels`, `modelOverrides`, `effortLevel`, `ANTHROPIC_MODEL`, provider envs. |
+| Permissions | `permissions.allow`, `permissions.ask`, `permissions.deny`, permission modes, managed restrictions. |
+| Memory/context | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, managed `claudeMd`. |
+| MCP | User/local state in `~/.claude.json`; project MCP servers in `.mcp.json`; managed MCP policy. |
+| Skills and slash commands | `.claude/skills/<name>/SKILL.md`; legacy `.claude/commands/*.md` still works and is treated like skills. |
+| Hooks | `hooks` in settings, plus hooks from skills, subagents, and plugins. |
+| Subagents | `~/.claude/agents/` and `.claude/agents/`; settings can run the main thread as a named subagent. |
+| Logs and telemetry | Claude Code monitoring/usage and OpenTelemetry settings; session retention via `cleanupPeriodDays`, `CLAUDE_CODE_SKIP_PROMPT_HISTORY`, and non-interactive session persistence flags. |
+
+## Shadow slash command bridge
+
+The runner package always materializes `/etc/shadowob/slash-commands.json` so
+Shadow can load a stable command index. The Claude Code runner owns its catalog
+in `apps/cloud/src/runtimes/slash-commands/claude-code.ts`; this is
+intentionally not a common runtime artifact.
+
+Official Claude Code commands researched from the Claude Code command reference
+include `/add-dir`, `/agents`, `/clear`, `/compact`, `/config`, `/cost`,
+`/doctor`, `/hooks`, `/init`, `/login`, `/logout`, `/mcp`, `/memory`,
+`/model`, `/permissions`, `/pr_comments`, `/review`, `/security-review`,
+`/setup-bedrock`, `/setup-vertex`, `/simplify`, `/skills`, `/status`,
+`/statusline`, `/tasks`, `/terminal-setup`, `/theme`, `/tui`, `/ultraplan`,
+`/ultrareview`, `/usage`, `/voice`, and `/web-setup`.
+
+Current Cloud injection registers only names that do not collide with
+cc-connect's universal bot commands. For example, `/review`, `/permissions`,
+`/hooks`, `/mcp`, `/login`, `/logout`, `/security-review`, `/setup-bedrock`,
+`/setup-vertex`, and `/terminal-setup` are injected; `/model`, `/status`,
+`/usage`, `/skills`, `/config`, `/doctor`, `/stop`, `/help`, and `/compact`
+remain cc-connect management commands.
+
+cc-connect local commands are prompt-backed. True Claude Code TUI passthrough
+requires a cc-connect agent enhancement so colliding command names do not break
+session, provider, and permission management.
+
+## Schema and type anchors
+
+- Settings schema URL:
+  `https://json.schemastore.org/claude-code-settings.json`.
+- Claude Code docs call this the official JSON schema, but warn that it can lag
+  the newest CLI settings. Treat docs and CLI behavior as authoritative when the
+  schema is behind.
+- Global config `~/.claude.json` is not the same schema as
+  `settings.json`; docs say adding those keys to `settings.json` is invalid.
+- MCP project config uses `.mcp.json`; subagents use Markdown files under
+  `.claude/agents/` with YAML frontmatter.
+- cc-connect type anchor: `../cc-connect/agent/claudecode/claudecode.go`.
+
+## Provider and authentication notes
+
+- Headless Cloud runners should prefer API/provider secrets over subscription
+  login. `ANTHROPIC_API_KEY` forces API-key usage in non-interactive mode and
+  overrides Claude subscription auth when present.
+- Claude subscription login can be useful locally, but a clean Kubernetes
+  container should not depend on a browser-backed Claude Pro/Max/Team session.
+- Custom gateway routing is not the same as model selection:
+  `ANTHROPIC_BASE_URL` changes the request destination, while `model`,
+  `ANTHROPIC_DEFAULT_*_MODEL`, `CLAUDE_CODE_SUBAGENT_MODEL`, or
+  `ANTHROPIC_CUSTOM_MODEL_OPTION` determine model IDs.
+- For LLM gateways, enable model discovery with
+  `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` when the gateway exposes
+  `/v1/models`; otherwise emit `ANTHROPIC_CUSTOM_MODEL_OPTION` and companion
+  display metadata for the selected Cloud model.
+- Bedrock, Vertex AI, Foundry, and Claude Platform on AWS have provider-specific
+  envs and model identifiers. The adapter must keep those as Claude-native env
+  or settings values, never as OpenClaw `models.providers`.
+
+## Security, audit, cost, network, and tools
+
+- Permissions: `permissions.allow`, `permissions.ask`, `permissions.deny`,
+  `permissions.defaultMode`, and managed `allowManagedPermissionRulesOnly`.
+  Deny rules are evaluated before ask/allow.
+- Bypass control: `disableBypassPermissionsMode = "disable"` should be the
+  default for managed Cloud runners unless the deployment explicitly enables
+  bypass.
+- Sandbox: `sandbox.enabled`, `failIfUnavailable`, filesystem allow/deny read
+  and write lists, and network allow/deny domains.
+- Hooks: `allowManagedHooksOnly`, `allowedHttpHookUrls`, and
+  `httpHookAllowedEnvVars` are required when HTTP hooks are generated.
+- MCP: managed allow/deny MCP settings must be represented separately from
+  `.mcp.json`.
+- Tool surface: Claude permission rules cover tool names such as `Bash`,
+  `Read`, `Edit`, `WebFetch`, MCP tools, and Agent rules.
+- Cost/audit: model, `maxContextTokens`, skill listing budgets, cleanup period,
+  and OpenTelemetry env/settings should be generated when Cloud audit is
+  enabled.
+- Logs: collect cc-connect daemon logs plus Claude Code monitoring/usage output
+  and transcript retention state.
+
+## cc-connect mapping
+
+The local fork exposes `core.RegisterAgent("claudecode", New)`. Important
+options from `../cc-connect/agent/claudecode/claudecode.go`:
+
+- `work_dir`
+- `cli_path`
+- `model`
+- `reasoning_effort`
+- `mode`: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`
+- `allowed_tools` and `disallowed_tools`
+- `max_context_tokens`
+- `router_url` and `router_api_key`
+- `system_prompt`
+- `env`
+- `run_as_user` and `run_as_env`
+
+The Cloud runner package should generate a `cc-connect` project like:
+
+```toml
+[[projects]]
+name = "agent-id"
+
+[projects.agent]
+type = "claudecode"
+
+[projects.agent.options]
+work_dir = "/workspace"
+
+[[projects.platforms]]
+type = "shadowob"
+```
+
+Provider secrets should be passed through provider refs or environment files,
+not through OpenClaw `models.providers`.
+
+## Capability notes
+
+- Models: map Cloud model preferences to Claude `model` and optional
+  `availableModels`/provider envs.
+- Skills/slash commands: materialize `.claude/skills` and optionally legacy
+  `.claude/commands` only for compatibility.
+- MCP: write `.mcp.json` for project-scoped MCP and avoid relying on
+  `~/.claude.json` in immutable images.
+- Cron/routine: Claude Code has scheduled prompt support in its automation
+  docs, but Cloud phase 1 should treat scheduling as a Cloud/Shadow concern
+  unless explicitly mounting a Claude-native schedule store.
+- Hooks: write Claude settings `hooks`, not OpenClaw `hooks`.
+- Subagents: materialize `.claude/agents` and any preloaded skill references.
+- Logs: collect both cc-connect daemon logs and Claude Code native telemetry or
+  transcript artifacts when enabled.
+
+## Migration implications
+
+- OpenClaw and ACPX have been removed from the Claude runner image path.
+- The image builds the cc-connect fork binary and installs the Claude CLI.
+- Generate Claude config files in the workspace/home directory before starting
+  cc-connect.
+- Keep `run_as_user` available for OS-user isolation; the fork currently
+  supports it for Claude Code.
+
+## Adapter and smoke tests
+
+Unit tests:
+
+- `settings.json` validates against the schema URL when only schema-known fields
+  are emitted.
+- Managed-only settings are not written into project settings.
+- Permission deny/ask/allow, sandbox filesystem, sandbox network, HTTP hook URL
+  allowlists, MCP restrictions, and `disableBypassPermissionsMode` are mapped.
+- cc-connect TOML contains `type = "claudecode"` and no OpenClaw artifacts.
+- Secret env vars are kept in secret data or per-runtime secret files.
+
+Container smoke:
+
+- `cc-connect --version` and `claude --version` work.
+- Generated `.claude/settings.json` and `.mcp.json` exist in the expected
+  workspace/home paths.
+- Container starts cc-connect with the ShadowOB platform block.
+- A denied read target such as `.env` remains denied in generated config.
+- Logs include cc-connect startup but no raw Shadow token or provider key.
+
+## Sources
+
+- Settings: https://code.claude.com/docs/en/settings
+- Model configuration: https://code.claude.com/docs/en/model-config
+- Environment variables: https://code.claude.com/docs/en/env-vars
+- Permissions: https://code.claude.com/docs/en/permissions
+- Sandboxing: https://code.claude.com/docs/en/sandboxing
+- Skills and custom commands:
+  https://code.claude.com/docs/en/skills
+- Slash commands: https://code.claude.com/docs/en/commands
+- MCP: https://code.claude.com/docs/en/mcp
+- Hooks: https://code.claude.com/docs/en/hooks
+- Subagents: https://code.claude.com/docs/en/sub-agents
+- Monitoring: https://code.claude.com/docs/en/monitoring-usage
+- cc-connect fork source: https://github.com/buggyblues/cc-connect

package/images/claude-runner/entrypoint.mjs

@@ -0,0 +1,2 @@
+process.env.SHADOW_RUNNER_NAME ??= 'claude-runner'
+await import('../cc-connect-runner/entrypoint.mjs')

package/images/codex-runner/Dockerfile

@@ -0,0 +1,87 @@
+# syntax=docker/dockerfile:1.7
+
+# ─── Codex Runner ─────────────────────────────────────────────────────────
+# Native cc-connect runner for OpenAI Codex.
+#
+# Build from the repository root:
+#   docker build -t ghcr.io/buggyblues/codex-runner:latest \
+#     -f apps/cloud/images/codex-runner/Dockerfile .
+# ──────────────────────────────────────────────────────────────────────────
+
+FROM golang:1.25-bookworm AS cc-builder
+
+ARG CC_CONNECT_REF=63b5d59127b3004bc7002f2d51892b1f2a91ea83
+ARG CC_CONNECT_REPO=https://github.com/buggyblues/cc-connect.git
+
+WORKDIR /build
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates git && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN git clone --depth 1 "${CC_CONNECT_REPO}" /tmp/cc-connect && \
+    cd /tmp/cc-connect && \
+    git fetch --depth 1 origin "${CC_CONNECT_REF}" && \
+    git checkout "${CC_CONNECT_REF}" && \
+    CGO_ENABLED=0 go build \
+      -tags "no_web no_acp no_cursor no_devin no_iflow no_kimi no_qoder no_feishu no_telegram no_discord no_slack no_dingtalk no_wecom no_weixin no_qq no_qqbot no_line no_weibo" \
+      -ldflags "-s -w" \
+      -o /build/cc-connect ./cmd/cc-connect
+
+FROM node:22-bookworm-slim AS node-deps
+
+WORKDIR /build
+
+RUN npm init -y && \
+    npm install --no-audit --fund=false \
+      @openai/codex@latest \
+      @shadowob/cli@latest \
+      @shadowob/connector@latest
+
+FROM node:22-bookworm-slim AS runner
+
+LABEL org.opencontainers.image.source="https://github.com/nicepkg/shadow"
+LABEL org.opencontainers.image.description="Shadow Cloud Codex Runner (cc-connect + Codex)"
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl git tini && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN userdel -r node 2>/dev/null || true; \
+    groupdel node 2>/dev/null || true; \
+    groupadd -g 1000 shadow; \
+    useradd -u 1000 -g shadow -m -d /home/shadow -s /usr/sbin/nologin shadow
+
+WORKDIR /app
+RUN mkdir -p /home/shadow/.cc-connect /home/shadow/.codex /etc/openclaw /etc/shadowob \
+             /var/log/shadowob /workspace /tmp/npm-cache && \
+    ln -s /home/shadow /home/openclaw && \
+    chown -R shadow:shadow /home/shadow /etc/shadowob /var/log/shadowob \
+      /workspace /tmp/npm-cache /app
+
+COPY --from=node-deps --chown=shadow:shadow /build/node_modules ./node_modules
+COPY --from=node-deps --chown=shadow:shadow /build/package.json ./package.json
+COPY --from=cc-builder /build/cc-connect /usr/local/bin/cc-connect
+
+RUN ln -s /app/node_modules/.bin/codex /usr/local/bin/codex && \
+    ln -s /app/node_modules/.bin/shadowob /usr/local/bin/shadowob && \
+    ln -s /app/node_modules/.bin/shadowob-connector /usr/local/bin/shadowob-connector
+
+COPY --chown=shadow:shadow apps/cloud/images/cc-connect-runner/entrypoint.mjs /app/entrypoint.mjs
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:3100/health || exit 1
+
+EXPOSE 3100
+
+ENV NODE_ENV=production
+ENV HOME=/home/shadow
+ENV SHADOW_RUNNER_HEALTH_PORT=3100
+ENV OPENCLAW_NO_RESPAWN=1
+ENV SHADOW_RUNNER_NAME=codex-runner
+ENV npm_config_cache=/tmp/npm-cache
+
+USER shadow
+
+ENTRYPOINT ["tini", "--"]
+CMD ["node", "/app/entrypoint.mjs"]

package/images/codex-runner/RUNNER.md

@@ -0,0 +1,226 @@
+# Codex Runner Research
+
+Research date: 2026-05-14.
+
+## Target role
+
+`codex` should run through the ShadowOB `cc-connect` fork, not through OpenClaw
+gateway or ACPX. The runner process should be:
+
+```text
+cc-connect fork -> agent type "codex" -> codex CLI
+```
+
+Shadow messaging should come from the cc-connect ShadowOB platform. Codex should
+use its own config, skills, MCP, hooks, subagents, sessions, and logs.
+
+## Current repository state
+
+The Codex adapter and image now use the cc-connect fork path. The runtime
+package emits `cc-connect-config.toml`, `$CODEX_HOME/config.toml`, project
+`.codex/config.toml`, workspace bootstrap files, and ShadowOB skill files
+through `runtime-files.json`.
+
+## Native Codex configuration
+
+Codex reads layered TOML configuration:
+
+| Concern | Native Codex surface |
+| --- | --- |
+| User config | `$CODEX_HOME/config.toml`, defaulting to `~/.codex/config.toml`. |
+| Project config | `.codex/config.toml` in trusted projects. |
+| System config | `/etc/codex/config.toml` on Unix. |
+| Model | `model`, profiles, `model_provider`, model catalogs. |
+| Reasoning | `model_reasoning_effort`, model-specific settings. |
+| Approvals and sandbox | `approval_policy`, `sandbox_mode`, permission profiles. |
+| MCP | `[mcp_servers.<name>]` with stdio or HTTP settings, enabled/disabled tools, timeouts. |
+| Skills | `.agents/skills` in repo/user/admin/system locations. |
+| Instructions | `AGENTS.md` hierarchy and optional config instructions. |
+| Hooks | Codex hooks config, loaded from trusted config layers. |
+| Subagents | Codex subagent roles in config with agent instruction files. |
+| Slash commands | Built-in CLI slash commands such as `/model`, `/mcp`, `/permissions`, `/agent`, `/review`, and `/status`. |
+| Automation | Codex app automations exist, but they are app-level background jobs rather than a simple CLI runner cron store. |
+| Logs and sessions | `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl`, `history.jsonl`, `auth.json`, local state/cache files. |
+
+## Shadow slash command bridge
+
+The runner package always materializes `/etc/shadowob/slash-commands.json` so
+Shadow can load a stable command index. The Codex runner owns its catalog in
+`apps/cloud/src/runtimes/slash-commands/codex.ts`; this is intentionally not a
+common runtime artifact.
+
+Official Codex CLI commands researched from the Codex docs include
+`/permissions`, `/sandbox-add-read-dir`, `/agent`, `/apps`, `/plugins`,
+`/clear`, `/compact`, `/copy`, `/diff`, `/exit`, `/experimental`, `/feedback`,
+`/init`, `/logout`, `/mcp`, `/mention`, `/model`, `/fast`, `/plan`, `/goal`,
+`/personality`, `/ps`, `/stop`, `/fork`, `/side`, `/resume`, `/new`, `/quit`,
+`/review`, `/status`, `/debug-config`, `/statusline`, `/title`, and `/keymap`.
+
+Current Cloud injection registers only names that do not collide with
+cc-connect's own universal control commands:
+
+- Injected local Codex catalog: `/permissions`, `/sandbox-add-read-dir`,
+  `/agent`, `/apps`, `/plugins`, `/clear`, `/copy`, `/exit`, `/experimental`,
+  `/feedback`, `/init`, `/logout`, `/mcp`, `/mention`, `/fast`, `/plan`,
+  `/goal`, `/personality`, `/fork`, `/side`, `/resume`, `/review`,
+  `/debug-config`, `/statusline`, `/title`, and `/keymap`.
+- Left to cc-connect control flow: `/new`, `/compact`, `/status`, `/diff`,
+  `/model`, `/ps`, `/stop`, and overlapping management/help commands.
+
+cc-connect local commands are prompt-backed, not full Codex TUI passthrough.
+Adding true native passthrough/discovery belongs in the cc-connect Codex agent,
+where it can distinguish cc-connect management commands from Codex CLI commands.
+
+## Schema and type anchors
+
+- Generated JSON Schema source:
+  `https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/config.schema.json`.
+  Codex config is TOML on disk, but this schema is the official repo-generated
+  shape for config keys.
+- Official type source: Codex Config Reference key/type table at
+  `https://developers.openai.com/codex/config-reference`.
+- Config layers: `$CODEX_HOME/config.toml`, trusted project `.codex/config.toml`,
+  and `/etc/codex/config.toml`.
+- Test rule: generated TOML must parse as TOML and must be accepted by the Codex
+  CLI in a container smoke test; do not use a handwritten JSON schema as source
+  of truth.
+- cc-connect type anchor: `../cc-connect/agent/codex/codex.go`.
+
+## Provider and authentication notes
+
+- Codex CLI supports first-run authentication with either a ChatGPT account or
+  an API key. In Cloud, the reliable headless path is API-key or custom-provider
+  auth, not an interactive ChatGPT subscription login.
+- For OpenAI API-key mode, set `OPENAI_API_KEY` through Secret data and use
+  `preferred_auth_method = "apikey"` when the runner profile could otherwise
+  prefer stored ChatGPT auth.
+- Custom providers belong in `[model_providers.<id>]`. The official config
+  reference defines `base_url`, `env_key`, `query_params`, static/env headers,
+  command-backed bearer-token auth, `requires_openai_auth`, retry/timeouts, and
+  `wire_api`.
+- Current Codex config reference lists `responses` as the supported
+  `wire_api`, so custom OpenAI-compatible gateways must support the Responses
+  API or be fronted by a gateway that translates correctly.
+- Built-in local providers such as `ollama`/`lmstudio` are provider IDs, but
+  remote Cloud runners must not silently point them at localhost unless the
+  container actually runs that model service.
+
+## Security, audit, cost, network, and tools
+
+- Permissions: `approval_policy`, granular approval policy, `sandbox_mode`,
+  `default_permissions`, and named `[permissions.<name>]` tables.
+- Filesystem: named permission profiles can grant `read`, `write`, or `none` to
+  special roots such as `:project_roots` and explicit paths/globs.
+- Network: `sandbox_workspace_write.network_access`, permission profile network
+  tables, web search mode (`cached`, `live`, `disabled`), and MCP remote servers.
+- Secrets: `shell_environment_policy` must default to a restrictive inheritance
+  mode and keep KEY/SECRET/TOKEN filtering unless intentionally overridden.
+- Tools: `features.shell_tool`, MCP server tool include/deny config, skills
+  config, subagent config, and rules should be emitted as native Codex config.
+- Cost/audit: `model`, `model_reasoning_effort`, `service_tier`, web search
+  mode, and tool-output/token-related telemetry must be tracked.
+- Observability: `[otel]` supports logs, metrics, traces, redacted prompts by
+  default, and event metadata for API requests, SSE events, tool decisions, and
+  tool results.
+
+## cc-connect mapping
+
+The local fork exposes `core.RegisterAgent("codex", New)`. Important options
+from `../cc-connect/agent/codex/codex.go`:
+
+- `work_dir`
+- `model`
+- `reasoning_effort`: `low`, `medium`, `high`, `xhigh`
+- `mode`: `suggest`, `auto-edit`, `full-auto`, `yolo`
+- `backend`: `exec` or `app_server`
+- `app_server_url`
+- `codex_home`
+- `cli_path`
+
+The default path drives `codex exec --json`. The app-server backend can be kept
+as an advanced option, but the phase-1 runner should start with the simpler
+`exec` path unless a deployment explicitly requests app-server mode.
+
+Example generated project shape:
+
+```toml
+[[projects]]
+name = "agent-id"
+
+[projects.agent]
+type = "codex"
+
+[projects.agent.options]
+work_dir = "/workspace"
+codex_home = "/home/shadow/.codex"
+
+[[projects.platforms]]
+type = "shadowob"
+```
+
+## Capability notes
+
+- Models: map Cloud model preferences to Codex `model`, profile, and optional
+  provider config. Avoid writing OpenClaw `agents.defaults.model`.
+- Skills: materialize `.agents/skills` for repo-scoped workflows and
+  `$CODEX_HOME/skills` only if the runner owns the whole home directory.
+- MCP: generate `[mcp_servers.*]` TOML tables.
+- Cron/routine: Codex app automations are not the same as CLI-local cron; Cloud
+  should own phase-1 schedules unless later integrating the Codex app
+  automation APIs.
+- Hooks: write Codex hook config in trusted project or user config.
+- Subagents: generate Codex agent roles and instruction files under `.codex`
+  only when `features.multi_agent` or equivalent config is enabled.
+- Logs: preserve Codex rollout JSONL paths and collect cc-connect daemon logs
+  separately.
+
+## Migration implications
+
+- OpenClaw, ACPX, and `@shadowob/openclaw-shadowob` have been removed from the
+  Codex runner image path.
+- The image builds the cc-connect fork binary and installs the Codex CLI.
+- Generate `$CODEX_HOME/config.toml`, project `.codex/config.toml`,
+  `AGENTS.md`, `.agents/skills`, and MCP config as native artifacts.
+- Keep current redaction patterns for container logs, but do not assume
+  `/var/log/openclaw` for the Codex runner.
+
+## Adapter and smoke tests
+
+Unit tests:
+
+- Generated TOML parses and contains expected scalar/table types for
+  `approval_policy`, `sandbox_mode`, `default_permissions`, `[permissions.*]`,
+  `[mcp_servers.*]`, `[features]`, and `[otel]`.
+- cc-connect TOML contains `type = "codex"` and no OpenClaw artifacts.
+- Permission mapping keeps network disabled by default in workspace-write mode.
+- `shell_environment_policy` excludes secrets unless Cloud explicitly opts in.
+- OTel config never exports raw prompts unless audit policy asks for it.
+
+Container smoke:
+
+- `cc-connect --version` and `codex --version` work.
+- `$CODEX_HOME/config.toml`, project `.codex/config.toml`, `AGENTS.md`, and
+  `.agents/skills` are materialized.
+- Start cc-connect with `type = "codex"` and inspect logs/session paths.
+- Assert no `/etc/openclaw/config.json` exists for this runner.
+- Run a no-network or read-only parse/start mode to confirm config loads before
+  any provider call.
+
+## Sources
+
+- CLI auth/setup: https://developers.openai.com/codex/cli
+- Config basics: https://developers.openai.com/codex/config-basic
+- Advanced config: https://developers.openai.com/codex/config-advanced
+- Config reference: https://developers.openai.com/codex/config-reference
+- Generated config schema:
+  https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/config.schema.json
+- Agent approvals and security:
+  https://developers.openai.com/codex/agent-approvals-security
+- MCP: https://developers.openai.com/codex/mcp
+- Skills: https://developers.openai.com/codex/skills
+- Hooks: https://developers.openai.com/codex/hooks
+- Subagents: https://developers.openai.com/codex/subagents
+- CLI slash commands: https://developers.openai.com/codex/cli/slash-commands
+- App automations: https://developers.openai.com/codex/app/automations
+- Codex CLI repository: https://github.com/openai/codex
+- cc-connect fork source: https://github.com/buggyblues/cc-connect

package/images/codex-runner/entrypoint.mjs

@@ -0,0 +1,2 @@
+process.env.SHADOW_RUNNER_NAME ??= 'codex-runner'
+await import('../cc-connect-runner/entrypoint.mjs')

package/images/gemini-runner/Dockerfile

@@ -0,0 +1,87 @@
+# syntax=docker/dockerfile:1.7
+
+# ─── Gemini Runner ────────────────────────────────────────────────────────
+# Native cc-connect runner for Gemini CLI.
+#
+# Build from the repository root:
+#   docker build -t ghcr.io/buggyblues/gemini-runner:latest \
+#     -f apps/cloud/images/gemini-runner/Dockerfile .
+# ──────────────────────────────────────────────────────────────────────────
+
+FROM golang:1.25-bookworm AS cc-builder
+
+ARG CC_CONNECT_REF=63b5d59127b3004bc7002f2d51892b1f2a91ea83
+ARG CC_CONNECT_REPO=https://github.com/buggyblues/cc-connect.git
+
+WORKDIR /build
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates git && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN git clone --depth 1 "${CC_CONNECT_REPO}" /tmp/cc-connect && \
+    cd /tmp/cc-connect && \
+    git fetch --depth 1 origin "${CC_CONNECT_REF}" && \
+    git checkout "${CC_CONNECT_REF}" && \
+    CGO_ENABLED=0 go build \
+      -tags "no_web no_acp no_cursor no_devin no_iflow no_kimi no_qoder no_feishu no_telegram no_discord no_slack no_dingtalk no_wecom no_weixin no_qq no_qqbot no_line no_weibo" \
+      -ldflags "-s -w" \
+      -o /build/cc-connect ./cmd/cc-connect
+
+FROM node:22-bookworm-slim AS node-deps
+
+WORKDIR /build
+
+RUN npm init -y && \
+    npm install --no-audit --fund=false \
+      @google/gemini-cli@latest \
+      @shadowob/cli@latest \
+      @shadowob/connector@latest
+
+FROM node:22-bookworm-slim AS runner
+
+LABEL org.opencontainers.image.source="https://github.com/nicepkg/shadow"
+LABEL org.opencontainers.image.description="Shadow Cloud Gemini Runner (cc-connect + Gemini CLI)"
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl git tini && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN userdel -r node 2>/dev/null || true; \
+    groupdel node 2>/dev/null || true; \
+    groupadd -g 1000 shadow; \
+    useradd -u 1000 -g shadow -m -d /home/shadow -s /usr/sbin/nologin shadow
+
+WORKDIR /app
+RUN mkdir -p /home/shadow/.cc-connect /home/shadow/.gemini /etc/openclaw /etc/shadowob \
+             /var/log/shadowob /workspace /tmp/npm-cache && \
+    ln -s /home/shadow /home/openclaw && \
+    chown -R shadow:shadow /home/shadow /etc/shadowob /var/log/shadowob \
+      /workspace /tmp/npm-cache /app
+
+COPY --from=node-deps --chown=shadow:shadow /build/node_modules ./node_modules
+COPY --from=node-deps --chown=shadow:shadow /build/package.json ./package.json
+COPY --from=cc-builder /build/cc-connect /usr/local/bin/cc-connect
+
+RUN ln -s /app/node_modules/.bin/gemini /usr/local/bin/gemini && \
+    ln -s /app/node_modules/.bin/shadowob /usr/local/bin/shadowob && \
+    ln -s /app/node_modules/.bin/shadowob-connector /usr/local/bin/shadowob-connector
+
+COPY --chown=shadow:shadow apps/cloud/images/cc-connect-runner/entrypoint.mjs /app/entrypoint.mjs
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:3100/health || exit 1
+
+EXPOSE 3100
+
+ENV NODE_ENV=production
+ENV HOME=/home/shadow
+ENV SHADOW_RUNNER_HEALTH_PORT=3100
+ENV OPENCLAW_NO_RESPAWN=1
+ENV SHADOW_RUNNER_NAME=gemini-runner
+ENV npm_config_cache=/tmp/npm-cache
+
+USER shadow
+
+ENTRYPOINT ["tini", "--"]
+CMD ["node", "/app/entrypoint.mjs"]