openshell-playground-plugin

Imported from eformat/openshell-playground-plugin (AGENTS.md). Install upstream with npx skills add eformat/openshell-playground-plugin. Copyright stays with the author.

Supported Agents

This document covers all agent types supported by the OpenShell Playground plugin, their configuration, sandbox images, and terminal setup.

Architecture

Each agent type runs on its own per-agent-type gateway. OpenShell has one inference route per gateway, so each agent gets its own provider and model configuration via inference.local.

When a user opens a sandbox terminal, the plugin:

1. Connects to the sandbox pod via K8s exec WebSocket
2. Enters the sandbox network namespace via nsenter --net
3. Sources a shell rcfile that configures TLS, proxy, and inference environment variables
4. Runs agent-specific setup (config files, model discovery)

Common Environment

All agents share these base environment variables set by the rcfile:

Process cleanup: set +m disables job control so child processes stay in bash's process group. trap 'kill 0' EXIT ensures agents are killed when the terminal disconnects.

Claude Code

Provider Notes

• Vertex AI: Register with GCP Project ID, Region, and Service Account JSON. The gateway mints OAuth tokens internally using --from-gcloud-adc.
• Anthropic: Direct API key.

Known Issues

• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 is required for Vertex AI to avoid 400 errors from the context_management field.
• The theme detection query (OSC 11) hangs in xterm.js — OPENSHELL_THEME=dark is set in the gateway's ttyd sidecar.

Codex

Auto-Configuration

The rcfile creates a Codex config with a custom openshell provider:

model_provider = "openshell"

[model_providers.openshell]
name = "OpenShell Inference"
base_url = "https://inference.local/v1"
env_key = "OPENAI_API_KEY"
supports_websockets = false

WebSocket transport is disabled because OPA policy blocks wss://inference.local/v1/responses. SSE streaming is used instead.

Known Issues

• Codex is a Rust binary — NODE_TLS_REJECT_UNAUTHORIZED does not work. Use SSL_CERT_FILE and CODEX_CA_CERTIFICATE for TLS trust.
• The gpt-5.4-codex model ID does not exist. Use gpt-5.4.

OpenCode

Auto-Configuration

The rcfile queries inference.local/v1/models and generates:

{
  "provider": {
    "openai-compatible": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://inference.local/v1",
        "apiKey": "unused"
      },
      "models": { "<model-id>": { "name": "<model-id>" } }
    }
  }
}

Known Issues

• OpenCode's SQLite database can corrupt if the process is force-killed (kill -9). The rcfile includes an auto-recovery check that deletes the database if it fails a SELECT 1 probe.
• Session resume (opencode -c) works if the workspace PVC persists session data at /sandbox/.local/share/opencode/.

GitHub Copilot CLI

Auto-Configuration

COPILOT_PROVIDER_BASE_URL=https://inference.local/v1
COPILOT_PROVIDER_API_KEY=unused
COPILOT_MODEL=<auto-detected from inference.local/v1/models>

BYOK mode skips GitHub authentication entirely. The agent runs fully offline against inference.local.

Pi

Auto-Configuration

The rcfile queries inference.local/v1/models and generates a Pi models config:

{
  "providers": {
    "openshell": {
      "baseUrl": "https://inference.local/v1",
      "api": "openai-completions",
      "apiKey": "unused",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [{ "id": "<model-id>" }]
    }
  }
}

Select the model inside Pi with the /model command.

Hermes Agent

Custom Image

The official nousresearch/hermes-agent image requires CAP_NET_ADMIN / CAP_SYS_ADMIN for its own network isolation, which conflicts with OpenShell's supervisor. The custom image (images/Containerfile.hermes) adds iproute2 and sets up the sandbox user:

FROM docker.io/nousresearch/hermes-agent:v2026.7.7.2
RUN apt-get update -qq && apt-get install -y -qq iproute2
RUN groupadd -g 1001 sandbox && useradd -m -u 1001 -g sandbox -s /bin/bash -d /sandbox sandbox
RUN install -d -o sandbox -g sandbox /workspace /sandbox /sandbox/.hermes
RUN chmod -R a+rX /opt/hermes && ln -sf /opt/hermes/.venv/bin/hermes /usr/local/bin/hermes
ENV HERMES_HOME=/sandbox/.hermes TERM=xterm-256color

Auto-Configuration

The rcfile creates all Hermes directories (cron, sessions, logs/curator, memories, profiles, hooks, skills, etc.) with chmod 777 to handle PVC ownership mismatches. HERMES_HOME is exported.

The gateway's inference config sets model.provider: openai-api and model.default: <model>, which Hermes reads on startup.

Ollama

Bundled Agents

The Ollama sandbox includes Claude Code, Codex, and OpenCode pre-installed. The rcfile configures all three:

• Codex: /sandbox/.codex/config.toml with supports_websockets = false
• OpenCode: /sandbox/opencode.json with models from inference.local
• Claude Code: Via base env vars

Local vs Remote Models

The Ollama server auto-starts inside the sandbox. Users can:

• Pull local models: ollama pull qwen3:8b (requires GPU via --gpu flag)
• Use remote inference: Agents route through inference.local to the gateway's provider

The Ollama TUI's "Chat with a model" option uses locally pulled models only. The agent launchers (Claude Code, Codex, OpenCode) use inference.local.

Notes

For container environments without GPU, Ollama provides limited value — the same agents are available on base sandbox gateways with remote inference. Ollama is most useful with openshell sandbox create --from ollama --gpu.

Agent Type Configuration

Agent types are defined in src/utils/types.ts (AGENT_TYPES array). Each entry specifies:

Terminal setup is in src/components/SandboxTerminals.tsx — the agentSetup() function returns agent-specific rcfile content based on the agentType string.

OpenShell Supervisor Version Pinning

The OpenShell supervisor binary is injected into sandbox pods via a Kubernetes image volume. The gateway TOML supervisor_image field controls which image is used.

Current Pinned Version

The plugin pins to openshell-sandbox 0.0.86 via a self-hosted image:

supervisor_image = "quay.io/eformat/openshell-supervisor:0.0.86"

Source: backend/gateway_deploy.go — the supervisor_image constant in the gateway TOML template.

Reason: OpenShell supervisor 0.0.91 (the latest tag as of 2026-07-27) has a regression where SubmitPolicyAnalysis is never called. This breaks OPA policy proposal generation — network rules never appear in the gateway TUI.

Symptom of regression: Gateway TUI shows "No network rules yet" even after sandbox makes outbound connections. The gateway logs show only GetDraftPolicy calls, never SubmitPolicyAnalysis.

How we detected it: user-developer namespace sandbox (running 0.0.86, started 6 days earlier) generated rules correctly. user-mhepburn sandbox (freshly pulled, got 0.0.91) did not.

Our pinned image: The 0.0.86 binary was copied from the working sandbox and baked into quay.io/eformat/openshell-supervisor:0.0.86 (see images/Containerfile.supervisor).

Upgrading the Supervisor

When upgrading, test policy proposal generation before shipping:

1. Deploy a new gateway
2. Deploy a sandbox
3. From the sandbox terminal, make a blocked outbound connection: curl -k https://eformat.me
4. Check the gateway TUI — network rules should appear within seconds
5. If no rules appear, check gateway logs for SubmitPolicyAnalysis calls:

   oc logs openshell-<type>-0 -n <namespace> -c openshell | grep SubmitPolicy

6. If absent, the supervisor version has a regression — revert to the last working version

To update the pinned version:

1. Verify the new version works using the test above
2. Copy the binary: oc cp sandbox-<id>:/opt/openshell/bin/openshell-sandbox /tmp/openshell-sandbox-X.Y.Z -c agent
3. Build and push: podman build -t quay.io/eformat/openshell-supervisor:X.Y.Z -f images/Containerfile.supervisor images/
4. Update supervisor_image in backend/gateway_deploy.go
5. Run make deploy

Adding a New Agent

1. Add an entry to AGENT_TYPES in src/utils/types.ts with the sandbox image and model suggestions
2. Add a setup constant and switch case in src/components/SandboxTerminals.tsx
3. If the agent needs a custom sandbox image, create a Containerfile in images/ and push to your registry
4. If the sandbox image is not a community name, use the full image reference in the sandbox field
5. Build and deploy the plugin