feat(openshell): upgrade to 0.0.54, fix sandbox integration

  - Install via deb package (CI runner default)
  - Fix sandbox download cmd broken by 0.0.54 API change
  - Set working/config dir to /sandbox/ for direct artifact download
  - Add UploadFile: works around upload-in-git-repo bug that placed
    schema at wrong sandbox path; self-corrects on path mismatch
  - Move credentials to /tmp/ (outside workspace, reduces confusion)
  - Fix review agent hardcoded /tmp/workspace path
  - Rename variables that caused implementation confusion
  - Update documentation

Signed-off-by: Hector Martinez <hemartin@redhat.com>

Author: rh-hemartin

action.yml

@@ -149,45 +149,6 @@ runs:
       shell: bash
       run: fullsend --version
 
-    - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
-
-    - name: Set OpenShell version
-      shell: bash
-      run: echo "OPENSHELL_VERSION=0.0.38" >> "${GITHUB_ENV}"
-
-    - name: Install OpenShell CLI
-      shell: bash
-      run: |
-        uv tool install openshell==${OPENSHELL_VERSION}
-        openshell --version
-
-    - name: Download openshell-gateway
-      shell: bash
-      run: |
-        set -euo pipefail
-
-        arch="$(uname -m)"
-        case "${arch}" in
-          x86_64) ;;
-          aarch64|arm64) arch=aarch64 ;;
-          *) echo "::error::Unsupported architecture for openshell-gateway: ${arch}"; exit 1 ;;
-        esac
-
-        GATEWAY_ASSET="openshell-gateway-${arch}-unknown-linux-gnu.tar.gz"
-        GATEWAY_URL="https://github.com/NVIDIA/OpenShell/releases/download/v${OPENSHELL_VERSION}/${GATEWAY_ASSET}"
-        max_attempts=3; attempt=1; delay=5
-        while true; do
-          if curl -fsSL "${GATEWAY_URL}" -o "/tmp/${GATEWAY_ASSET}"; then break; fi
-          if (( attempt >= max_attempts )); then
-            echo "::error::Gateway download failed after ${max_attempts} attempts"
-            exit 1
-          fi
-          echo "::warning::Gateway download attempt ${attempt}/${max_attempts} failed, retrying in ${delay}s..."
-          sleep "${delay}"; (( attempt++ )); (( delay *= 3 ))
-        done
-        tar xzf "/tmp/${GATEWAY_ASSET}" -C "${RUNNER_TEMP}/fullsend"
-        rm -f "/tmp/${GATEWAY_ASSET}"
-
     - name: Install Podman
       shell: bash
       run: |
@@ -203,58 +164,25 @@ runs:
         grep -q "^${whoami_user}:" /etc/subuid || sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "${whoami_user}"
         podman system migrate
         podman info
+        systemctl --user start podman.socket
 
-    - name: Start Podman API service
+    - name: Set OpenShell version
       shell: bash
       run: |
-        SOCKET_PATH="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/podman/podman.sock"
-        if [ ! -S "${SOCKET_PATH}" ]; then
-          mkdir -p "$(dirname "${SOCKET_PATH}")"
-          podman system service --time=0 "unix://${SOCKET_PATH}" &
-          for i in $(seq 1 30); do
-            [ -S "${SOCKET_PATH}" ] && podman --url "unix://${SOCKET_PATH}" info >/dev/null 2>&1 && break
-            sleep 1
-          done
-          [ -S "${SOCKET_PATH}" ] || { echo "::error::Podman socket not ready"; exit 1; }
-        fi
-        echo "Podman API service ready at ${SOCKET_PATH}"
+        echo "OPENSHELL_VERSION=0.0.54" >> "${GITHUB_ENV}"
+        # SHA corresponding to 0.0.54
+        echo "OPENSHELL_SHA=79aa355dd008e496a7d8f97b361a7b2866066fbc" >> "${GITHUB_ENV}"
 
-    - name: Start openshell-gateway
+    - name: Install OpenShell CLI
       shell: bash
       run: |
-        set -euo pipefail
+        mkdir -p $HOME/.config/openshell/
+        cat > $HOME/.config/openshell/gateway.env << EOF
+        OPENSHELL_BIND_ADDRESS=0.0.0.0
+        EOF
 
-        GATEWAY_LOG="${GITHUB_WORKSPACE}/output/openshell-gateway.log"
-        mkdir -p "${GITHUB_WORKSPACE}/output"
-
-        export OPENSHELL_SSH_HANDSHAKE_SECRET="ci-$(openssl rand -hex 16)"
-        echo "::add-mask::${OPENSHELL_SSH_HANDSHAKE_SECRET}"
-        # Version-tagged images start at 0.0.41; for 0.0.38 use the release commit SHA.
-        # TODO: pass via --podman-supervisor-image flag when one exists (Docker driver has --docker-supervisor-image).
-        export OPENSHELL_SUPERVISOR_IMAGE="ghcr.io/nvidia/openshell/supervisor:dfd47683e7da4f1a4a8fa5d77f92d3696e6a41f9"
-
-        "${RUNNER_TEMP}/fullsend/openshell-gateway" \
-          --bind-address 0.0.0.0 \
-          --health-port 8081 \
-          --drivers podman \
-          --disable-tls \
-          --db-url "sqlite:/tmp/gateway.db?mode=rwc" \
-          >"${GATEWAY_LOG}" 2>&1 &
-
-        for i in $(seq 1 30); do
-          curl -sf http://127.0.0.1:8081/healthz >/dev/null 2>&1 && break
-          sleep 2
-        done
-        curl -sf http://127.0.0.1:8081/healthz >/dev/null 2>&1 || {
-          echo "::error::Gateway health check failed after 60s"
-          echo "::group::Gateway logs"
-          cat "${GATEWAY_LOG}" 2>/dev/null || echo "(no log file)"
-          echo "::endgroup::"
-          exit 1
-        }
-
-        openshell gateway add http://127.0.0.1:8080 --local --name local
-        openshell gateway select local
+        curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/${OPENSHELL_SHA}/install.sh | OPENSHELL_VERSION=v${OPENSHELL_VERSION} sh
+        openshell --version
 
     - name: Pre-pull sandbox image
       shell: bash

docs/architecture.md

@@ -556,10 +556,10 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
                  ║ │ │                                                       │ │ ║
                  ║ │ │ Created with --from image, --policy code.yaml.        │ │ ║
                  ║ │ │ Bootstrapped via openshell upload/exec:               │ │ ║
-                 ║ │ │   agent def    → /tmp/claude-config/agents/           │ │ ║
-                 ║ │ │   skills       → /tmp/claude-config/skills/           │ │ ║
+                 ║ │ │   agent def    → /sandbox/claude-config/agents/       │ │ ║
+                 ║ │ │   skills       → /sandbox/claude-config/skills/       │ │ ║
                  ║ │ │   .env, host files (GCP creds), security hooks        │ │ ║
-                 ║ │ │   target repo  → /tmp/workspace/target-repo/          │ │ ║
+                 ║ │ │   target repo  → /sandbox/workspace/target-repo/      │ │ ║
                  ║ │ │                                                       │ │ ║
                  ║ │ │ Network policy enforced (L7, per-binary):             │ │ ║
                  ║ │ │   Vertex AI     → claude, node only                   │ │ ║
@@ -585,7 +585,7 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
                  ║ │ └───────────────────────────────────────────────────────┘ │ ║
                  ║ │                                                           │ ║
                  ║ │ Extracts from destroyed sandbox:                          │ ║
-                 ║ │   /tmp/workspace/output/, JSONL transcripts,              │ ║
+                 ║ │   /sandbox/workspace/output/, JSONL transcripts,          │ ║
                  ║ │   rsync repo back (--no-links, exclude .git/hooks/)       │ ║
                  ║ │                                                           │ ║
                  ║ │ Post-agent secret scan (redact from extracted output).    │ ║

docs/guides/dev/cli-internals.md

@@ -280,8 +280,8 @@ Per-repo mode does not use the layer stack — it runs the same phases inline in
 │  │  └── security hooks                      │                   │
 │  │                                          │                   │
 │  │  bootstrapEnv() writes:                  │                   │
-│  │  ├── PATH=/tmp/workspace/bin:$PATH       │                   │
-│  │  ├── CLAUDE_CONFIG_DIR=/tmp/claude-config│                   │
+│  │  ├── PATH=/sandbox/workspace/bin:$PATH       │               │
+│  │  ├── CLAUDE_CONFIG_DIR=/sandbox/claude-config│               │
 │  │  ├── FULLSEND_OUTPUT_DIR=...             │                   │
 │  │  └── sources .env.d/*.env files          │                   │
 │  └──────────┬───────────────────────────────┘                   │
@@ -342,8 +342,8 @@ Per-repo mode does not use the layer stack — it runs the same phases inline in
 ### Sandbox Constants
 
 ```go
-SandboxWorkspace    = "/tmp/workspace"
-SandboxClaudeConfig = "/tmp/claude-config"
+SandboxWorkspace    = "/sandbox/workspace"
+SandboxClaudeConfig = "/sandbox/claude-config"
 ```
 
 ### Key Sandbox Operations

docs/guides/dev/local-dev.md

@@ -7,7 +7,7 @@ This guide walks through running fullsend agents locally on macOS and Linux. PR
 | Requirement | macOS | Linux |
 |-------------|-------|-------|
 | Container runtime | Podman Desktop with a running machine | Podman |
-| OpenShell | 0.0.37-dev+ (Podman support) | 0.0.37-dev+ |
+| OpenShell | 0.0.54 (Podman support) | 0.0.54 |
 | GCP credentials | Service account key (`Vertex AI User` role) | Same |
 | GitHub PAT | `repo` scope for the target org | Same |
 | Go toolchain | Optional — only needed when building the CLI from source | Same |

docs/guides/user/customizing-agents.md

@@ -25,12 +25,12 @@ plugins:
 
 host_files:
   - src: env/gcp-vertex.env
-    dest: /tmp/workspace/.env.d/gcp-vertex.env
+    dest: /sandbox/workspace/.env.d/gcp-vertex.env
     expand: true
   - src: ${GOOGLE_APPLICATION_CREDENTIALS}
-    dest: /tmp/workspace/.gcp-credentials.json
+    dest: /tmp/.gcp-credentials.json
   - src: ${GCP_OIDC_TOKEN_FILE}
-    dest: /tmp/workspace/.gcp-oidc-token
+    dest: /sandbox/workspace/.gcp-oidc-token
     optional: true
 
 pre_script: scripts/pre-code.sh
@@ -259,12 +259,12 @@ plugins:
 
 host_files:
   - src: env/gcp-vertex.env
-    dest: /tmp/workspace/.env.d/gcp-vertex.env
+    dest: /sandbox/workspace/.env.d/gcp-vertex.env
     expand: true
   - src: ${GOOGLE_APPLICATION_CREDENTIALS}
-    dest: /tmp/workspace/.gcp-credentials.json
+    dest: /tmp/.gcp-credentials.json
   - src: ${GCP_OIDC_TOKEN_FILE}
-    dest: /tmp/workspace/.gcp-oidc-token
+    dest: /sandbox/workspace/.gcp-oidc-token
     optional: true
 
 pre_script: scripts/pre-code.sh

docs/guides/user/running-agents-locally.md

@@ -48,25 +48,13 @@ fullsend --version
 
 [OpenShell](https://github.com/NVIDIA/OpenShell) provides the sandbox runtime. There are multiple ways
 to install it, here we use one similar to how we download it on Fullsend. Use the same version
-printed on your Fullsend workflow for better reproducibility. Install the CLI and download
-the gateway binary:
+printed on your Fullsend workflow for better reproducibility.
 
 ```bash
-# Install the CLI (requires uv — https://docs.astral.sh/uv/)
-uv tool install openshell==0.0.38
-
+curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v${OPENSHELL_VERSION}/install.sh | OPENSHELL_VERSION=v${OPENSHELL_VERSION} sh
 openshell --version
 ```
 
-Download the gateway binary from the [OpenShell releases](https://github.com/NVIDIA/OpenShell/releases/tag/v0.0.38) page. Pick the archive matching your platform and extract it:
-
-```bash
-# Example for macOS (Apple Silicon)
-curl -fsSL https://github.com/NVIDIA/OpenShell/releases/download/v0.0.38/openshell-gateway-aarch64-apple-darwin.tar.gz \
-  -o /tmp/openshell-gateway.tar.gz
-tar xzf /tmp/openshell-gateway.tar.gz -C $HOME/.local/bin/
-```
-
 ## Get Google Cloud Platform credentials
 
 Fullsend uses GCP's VertexAI to run inference, so you need a GCP project. After authenticating on `gcloud` run:
@@ -122,47 +110,13 @@ clone Fullsend's repository. To learn more about custom agents visit
 git clone --depth 1 https://github.com/fullsend-ai/fullsend.git /tmp/fullsend-ai_fullsend/
 ```
 
-## Start the OpenShell gateway
-
-OpenShell requires a gateway to work, start one on a different terminal using Podman:
-
-```bash
-# On arm64 hosts (Apple Silicon, Graviton), uncomment these lines:
-# export FULLSEND_SANDBOX_IMAGE=ghcr.io/fullsend-ai/fullsend-sandbox:dev
-# podman machine start
-
-export OPENSHELL_SSH_HANDSHAKE_SECRET="local-$(openssl rand -hex 16)"
-# v0.0.38 requires an explicit supervisor image (version-tagged images start at 0.0.41)
-export OPENSHELL_SUPERVISOR_IMAGE="ghcr.io/nvidia/openshell/supervisor:dfd47683e7da4f1a4a8fa5d77f92d3696e6a41f9"
-
-openshell-gateway \
-  --bind-address 0.0.0.0 \
-  --health-port 8081 \
-  --drivers podman \
-  --disable-tls \
-  --db-url "sqlite:/tmp/gateway.db?mode=rwc"
-```
-
-Wait for the health check to pass, then register the gateway:
-
-```bash
-# Health endpoint is on port 8081, API on port 8080
-for i in $(seq 1 15); do
-  curl -sf http://127.0.0.1:8081/healthz >/dev/null 2>&1 && break
-  sleep 2
-done
-
-# Register and select the local gateway
-openshell gateway add http://127.0.0.1:8080 --local --name local
-openshell gateway select local
-```
-
 ## Run default agents
 
 Depending on the agent you want to run you need a different set of environment variables.
 Check the variables they need in their environment files, referenced in their harness files.
 
-**Tip**: use `--no-post-script` in the `fullsend run` calls to avoid side-effects.
+**Tip**: use `--no-post-script` in the `fullsend run` calls to avoid side-effects. You
+can also use `--keep-sandbox` to debug failures (but remember to remove them).
 
 **Note**: to run custom agents set `--fullsend-dir` to the directory where your
 custom agent definitions exist.
@@ -300,6 +254,10 @@ When you execute `fullsend run`, pass `--fullsend-dir` as `/tmp/agents/`.
 ### Linux
 
 - **Rootless Podman**: Podman runs rootless by default. Ensure your user has subuids/subgids configured (`grep $USER /etc/subuid`). If not, run `sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER && podman system migrate`.
+- **Rootless Podman**: The sandbox does not move to Ready state and its logs say that it can't connect
+to the server (gateway). It is likely that you need to bind the gateway to `0.0.0.0`. Add
+`OPENSHELL_BIND_ADDRESS` on `$HOME/.config/openshell/gateway.env` and restart the
+`openshell-gateway` service.
 - **SELinux**: on Fedora/RHEL, bind-mounted volumes may need the `:z` suffix for standalone `podman run`. OpenShell handles this automatically.
 
 ## Troubleshooting

docs/plans/universal-harness-access.md

@@ -35,7 +35,7 @@ pre_script: scripts/pre-code.sh
 post_script: scripts/post-code.sh
 host_files:
   - src: env/gcp-vertex.env
-    dest: /tmp/workspace/.env.d/gcp-vertex.env
+    dest: /sandbox/workspace/.env.d/gcp-vertex.env
 ```
 
 Resolution logic (`internal/harness/harness.go`):