Add container Runtime Access inspector and Docker image setup guidance

[ashwin-pc]

Context

pi-web is moving toward a container-friendly, bash-first experience where the agent can inspect and operate on whatever the runtime can actually see. Instead of adding a host-side supervisor for dynamic mounts, we want a static-container experience that is transparent and easy to fix from the UI.

The goal is for users to run the official pi-web container image, click an info/access button, and immediately understand:

• whether pi-web is running inside a container
• what paths Pi can read and write
• what mounted roots are available
• which credentials/configs appear present, without exposing secret values
• what network capabilities appear available
• what common CLI tools are installed
• how to update Docker/Compose config when something is not accessible

The Pi agent should also receive this runtime access information in its context, similar to how contexts/web-ui.md currently teaches the agent about pi-web artifact behavior.

Design notes

pi-web state vs scratch

Use two separate persistent/writeable areas in container installs:

• pi-web state: durable app data, such as sessions, settings, audit logs, cached metadata, and generated runtime-access reports. This should usually be a named volume, for example /pi-web.
• scratch: disposable agent workspace for temporary downloads, command output, experiments, extracted archives, intermediate files, etc. This can be a named volume or tmpfs, for example /scratch.

These should be distinct so users can safely clear scratch without deleting pi-web history/settings/audit data.

Container image strategy

Evaluate image base options rather than assuming a custom heavy image:

• Ubuntu/Debian-slim style image: better compatibility with common CLIs and user expectations; easier to install awscli/kubectl/psql/git/node/python/jq/rg/curl/ssh. Larger, but likely better for the product's bash-first philosophy.
• Alpine: much smaller, but musl/busybox differences can cause friction with common tools, shell scripts, native packages, Playwright/browser automation, Python wheels, and vendor CLIs.
• Custom pi-web image: still useful as a maintained product artifact, but should be based on a standard distro and documented clearly. We do not need to invent a distro; we need to publish a reliable, batteries-included runtime.

Initial recommendation: use Debian/Ubuntu slim as the default official image, and optionally add a minimal image later only if there is real demand.

Proposed feature: Runtime Access inspector

Add a header/info panel, e.g. Runtime Access, with tabs:

1. Overview

   • containerized: yes/no/unknown
   • current cwd
   • UID/GID
   • hostname
   • shell path
   • profile/safety mode if configured

2. Filesystem access

   • parse /proc/self/mountinfo
   • show mounted roots
   • show likely source/type where safely detectable
   • show read/write status by testing safe temp writes where appropriate
   • classify paths as workspace, state, scratch, data, secret, system, unknown

3. Credentials/config presence

   • detect presence only, never values
   • examples: AWS config/credentials, kubeconfig, GitHub token presence, SSH agent/socket, npmrc, Docker socket
   • redact all sensitive values

4. Network/tooling

   • show whether internet/LAN/host gateway appear reachable if checks are enabled
   • show presence/version of common CLIs: git, node, npm, python, jq, rg, curl, ssh, aws, kubectl, docker, psql, mysql, terraform

5. Fix access

   • let user describe a missing path/capability
   • generate Docker run and Compose snippets to add a static mount or env/config
   • explicitly say restart/recreate is required for new mounts

API shape

Add something like:

GET /api/runtime/access

Example response:

{
  "ok": true,
  "runtime": {
    "container": true,
    "cwd": "/workspace",
    "uid": 1000,
    "gid": 1000,
    "hostname": "pi-web"
  },
  "mounts": [
    {
      "path": "/workspace",
      "kind": "bind-or-volume",
      "mode": "rw",
      "writable": true,
      "classification": "workspace"
    },
    {
      "path": "/pi-web",
      "kind": "volume",
      "mode": "rw",
      "writable": true,
      "classification": "state"
    },
    {
      "path": "/scratch",
      "kind": "volume-or-tmpfs",
      "mode": "rw",
      "writable": true,
      "classification": "scratch"
    },
    {
      "path": "/secrets/aws",
      "kind": "bind",
      "mode": "ro",
      "writable": false,
      "classification": "secret"
    }
  ],
  "credentials": [
    { "kind": "aws", "present": true, "path": "/secrets/aws", "redacted": true }
  ],
  "tools": [
    { "name": "git", "present": true, "version": "..." },
    { "name": "aws", "present": true, "version": "..." }
  ]
}

Agent context

Generate and inject a runtime context file into Pi sessions, e.g.:

# pi-web runtime access

You are running inside a container.

Writable paths:
- /workspace
- /scratch
- /pi-web

Read-only paths:
- /host/logs
- /secrets/aws

If the user asks you to access a missing host path, explain that Docker mounts must be configured at container start/recreate time. Propose a Docker run or Compose change. Do not claim you can mount arbitrary host paths dynamically from inside the container.

Also add static docs, e.g. contexts/container-setup.md, that teach the agent the intended mount conventions:

• /workspace for writable project/work area
• /pi-web for durable pi-web state
• /scratch for disposable agent temp work
• /host/<name> for read-only host data
• /secrets/<name> for read-only credentials/config

Docker/Compose docs

Add an official container install example along these lines:

services:
  pi-web:
    image: ghcr.io/ashwin-pc/pi-web:latest
    ports:
      - "127.0.0.1:8787:8787"
    environment:
      HOST: "0.0.0.0"
      PORT: "8787"
      PI_WEB_CWD: "/workspace"
      PI_WEB_STATE_DIR: "/pi-web"
      PI_WEB_SCRATCH_DIR: "/scratch"
      PI_WEB_TOKEN: "${PI_WEB_TOKEN}"
    volumes:
      - ./workspace:/workspace:rw
      - pi-web-state:/pi-web
      - pi-web-scratch:/scratch
      # Optional data mounts:
      # - /var/log:/host/logs:ro
      # - ~/.aws:/secrets/aws:ro

volumes:
  pi-web-state:
  pi-web-scratch:

Acceptance criteria

• Official Docker image is documented, with a clear base-image decision.
• Runtime Access panel shows visible mounted paths and read/write status.
• Sensitive credential/config detection reports presence only, with redaction.
• Pi session context includes generated runtime access information.
• The agent can answer access-failure questions with concrete Docker run / Compose fixes.
• Docs explain /pi-web state vs /scratch and how to clear each safely.
• No host-side supervisor or Docker socket mount is required for the core experience.

Non-goals for this issue

• Live dynamic host mounting from inside the container.
• Granting pi-web direct access to /var/run/docker.sock.
• Building a full connector framework before the bash-first runtime access model is in place.