aradotso/skills/openclaude-portable

---
name: openclaude-portable
description: Run Claude Code and other AI coding agents from a USB drive or any folder with zero installation required
triggers:
  - "set up openclaude portable"
  - "run claude code from USB"
  - "portable AI coding agent"
  - "openclaude no install"
  - "configure openclaude provider"
  - "openclaude ollama offline mode"
  - "openclaude dashboard setup"
  - "use openclaude on any PC"
---

# OpenClaude Portable

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenClaude Portable bundles a self-contained Node.js runtime, the OpenClaude AI coding engine, a system-prompt proxy for local models, and a web dashboard — all inside a single folder. Plug a USB drive into any Windows, Linux, or macOS machine and launch a full AI coding agent with no installation.

---

## Installation

### Option 1 — Clone to USB or any folder
```bash
git clone https://github.com/techjarves/OpenClaude-Portable
cd OpenClaude-Portable

Option 2 — Download ZIP

Download and extract from GitHub, then navigate into the folder.

First Launch (downloads Node.js ~25 MB and engine ~5 MB automatically)

Windows:

.\START.bat

Linux / macOS:

chmod +x start.sh
./start.sh

First-time setup requires internet. All downloads go into engine/ and data/ — nothing touches the host machine.

---

Project Structure

OpenClaude-Portable/
├── START.bat               # Windows entry point
├── start.sh                # Linux/macOS entry point
├── RESUME.bat              # Resume a session by ID (Windows)
│
├── data/                   # ALL persistent data lives here
│   ├── ai_settings.env     # Active provider, model, API key
│   ├── openclaude/         # Session history and agent memory
│   ├── ollama/             # Local Ollama binary and models
│   └── proxy.log           # Speed proxy log (silent)
│
├── engine/                 # Bundled Node.js + OpenClaude package
│   ├── node-win-x64/
│   └── node_modules/@gitlawb/openclaude/
│
├── tools/
│   ├── local-proxy.js      # System-prompt trimming proxy
│   ├── Change_Provider.bat / change_provider.sh
│   ├── Open_Dashboard.bat  / open_dashboard.sh
│   └── Setup_Local_Models.bat / setup_local_models.sh
│
└── dashboard/
    ├── server.mjs
    └── index.html

---

Main Menu

Running START.bat or start.sh presents:

1) Launch AI       — Normal Mode      (asks before writing files or running commands)
2) Limitless Mode  — Auto-executes    (fully autonomous, no approval prompts)
3) Open Dashboard  — Web UI at http://localhost:3000
4) Change Provider — Switch model or API key
5) Setup Offline   — Download local Ollama models

Auto-selects Normal Mode after 10 seconds if no key is pressed.

---

Configuring an AI Provider

Provider settings are stored in data/ai_settings.env. You can edit this file directly or run the interactive switcher:

Windows:

.\tools\Change_Provider.bat

Linux / macOS:

./tools/change_provider.sh

data/ai_settings.env format

PROVIDER=openrouter
MODEL=openai/gpt-4o
API_KEY=$OPENROUTER_API_KEY

Supported PROVIDER values and where to get keys:

| Provider | PROVIDER value | Key source | |---|---|---| | NVIDIA NIM | nvidia | build.nvidia.com | | DeepSeek | deepseek | platform.deepseek.com | | OpenRouter | openrouter | openrouter.ai | | Google Gemini | gemini | aistudio.google.com | | Anthropic Claude | anthropic | console.anthropic.com | | OpenAI | openai | platform.openai.com | | Ollama (offline) | ollama | No key needed |

Never hard-code API keys. Reference environment variables or let the interactive setup write data/ai_settings.env for you. The file lives only on your drive and is not tracked by git if you add it to .gitignore.

---

Session Management

Resume an interrupted session (Windows)

.\RESUME.bat <session-id>

Session IDs are stored in data/openclaude/. List available sessions:

dir data\openclaude

Linux / macOS equivalent:

ls data/openclaude/
openclaude --resume <session-id>

---

Web Dashboard

The dashboard provides a ChatGPT-style UI with agent mode, tool cards, and thinking visualisation.

Launch:

.\tools\Open_Dashboard.bat        # Windows
./tools/open_dashboard.sh         # Linux/macOS

Then open http://localhost:3000 in any browser.

The dashboard server (dashboard/server.mjs) uses the same data/ai_settings.env as the CLI — no separate configuration needed.

---

Offline Mode with Ollama

Download a local model

Windows:

.\tools\Setup_Local_Models.bat

Linux / macOS:

./tools/setup_local_models.sh

Recommended models for CPU inference

| Model | Size | Speed | |---|---|---| | gemma3:1b | ~800 MB | Fastest | | qwen2.5:1.5b | ~1 GB | Fast | | phi3:mini | ~2.3 GB | Moderate |

Models download into data/ollama/ — everything stays on the drive.

Speed proxy for local models

tools/local-proxy.js intercepts every Ollama request and trims the OpenClaude system prompt from ~10 000 tokens to ~300 tokens before forwarding. This drops first-token latency from 60–120 s to 5–20 s on CPU-only hardware.

The proxy runs silently in the background and logs to data/proxy.log. It binds to port 11435 (not the default Ollama port 11434).

To inspect proxy activity:

# Linux/macOS
tail -f data/proxy.log

# Windows PowerShell
Get-Content data\proxy.log -Wait

If you need to run the proxy manually:

node tools/local-proxy.js

---

Environment Variables Set at Runtime

OpenClaude Portable redirects all config paths into data/ so nothing touches the host:

XDG_CONFIG_HOME   → <drive>/data
XDG_DATA_HOME     → <drive>/data
CLAUDE_CONFIG_DIR → <drive>/data

These are set inside START.bat / start.sh — you do not need to set them manually.

---

Real Code Examples

Custom wrapper script (Linux/macOS) — launch with a specific provider

#!/usr/bin/env bash
# launch-with-gemini.sh — override provider for a single session

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

export XDG_CONFIG_HOME="$SCRIPT_DIR/data"
export XDG_DATA_HOME="$SCRIPT_DIR/data"
export CLAUDE_CONFIG_DIR="$SCRIPT_DIR/data"

# Temporarily override provider
cat > "$SCRIPT_DIR/data/ai_settings.env" <<EOF
PROVIDER=gemini
MODEL=gemini-2.0-flash
API_KEY=$GEMINI_API_KEY
EOF

NODE="$SCRIPT_DIR/engine/node-linux-x64/bin/node"
OPENCLAUDE="$SCRIPT_DIR/engine/node_modules/@gitlawb/openclaude/dist/cli.mjs"

"$NODE" "$OPENCLAUDE" "$@"

Read current provider settings in a script

#!/usr/bin/env bash
# print-provider.sh

source ./data/ai_settings.env
echo "Provider : $PROVIDER"
echo "Model    : $MODEL"
# Do NOT echo API_KEY

PowerShell — list and resume sessions

# list-sessions.ps1
$sessions = Get-ChildItem -Path ".\data\openclaude" -Directory
foreach ($s in $sessions) {
    Write-Host $s.Name
}

# Resume the most recent session
$latest = $sessions | Sort-Object LastWriteTime -Descending | Select-Object -First 1
if ($latest) {
    Write-Host "Resuming $($latest.Name)"
    .\RESUME.bat $latest.Name
}

Check proxy is running (Node.js)

// check-proxy.js — run with bundled Node
import http from 'http';

const req = http.request(
  { hostname: 'localhost', port: 11435, path: '/health', method: 'GET' },
  (res) => {
    console.log(`Proxy status: ${res.statusCode}`);
  }
);
req.on('error', () => console.log('Proxy not running'));
req.end();

Run it:

./engine/node-linux-x64/bin/node check-proxy.js

Dashboard server — add a custom API route

// dashboard/server.mjs (extend with your own endpoint)
import express from 'express';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import path from 'path';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const app = express();

app.use(express.static(path.join(__dirname)));
app.use(express.json());

// Custom endpoint — return current provider info
app.get('/api/provider', (_req, res) => {
  try {
    const env = readFileSync(
      path.join(__dirname, '../data/ai_settings.env'),
      'utf8'
    );
    const provider = env.match(/^PROVIDER=(.+)$/m)?.[1] ?? 'unknown';
    const model    = env.match(/^MODEL=(.+)$/m)?.[1]    ?? 'unknown';
    res.json({ provider, model });
  } catch {
    res.status(500).json({ error: 'Could not read settings' });
  }
});

app.listen(3000, () => console.log('Dashboard → http://localhost:3000'));

---

Common Patterns

Pattern 1 — Daily portable workflow

1. Plug in USB drive
2. .\START.bat  (or ./start.sh)
3. Choose option 1 (Normal Mode) or 2 (Limitless)
4. Work on your project
5. Unplug — all history in data/, host is clean

Pattern 2 — Switch provider mid-project

REM Windows
.\tools\Change_Provider.bat
REM Select new provider, enter key, done
.\START.bat

Pattern 3 — Offline day (no internet)

REM Ensure models already downloaded
.\tools\Setup_Local_Models.bat

REM Set provider to ollama in data\ai_settings.env
REM PROVIDER=ollama
REM MODEL=gemma3:1b

.\START.bat
REM Speed proxy starts automatically, trims prompts for local model

Pattern 4 — Shared USB across OSes

The data/ folder is platform-agnostic. Work on Windows, switch to Linux:

./start.sh          # picks up same data/ai_settings.env and session history

---

Troubleshooting

| Symptom | Fix | |---|---| | Node.js not found | Run START.bat — it downloads Node automatically | | EADDRINUSE: port 11435 | Old proxy still running; START.bat kills it on next launch, or kill manually: taskkill /F /IM node.exe (Win) / pkill -f local-proxy (Unix) | | openclaude: dist/cli.mjs not found | Interrupted install — pull latest and run START.bat again to repair | | npm error could not determine executable to run | Pull latest launcher; it now calls the verified bundled binary directly | | Claude Code on Windows requires git-bash | Pull latest START.bat; it installs bundled GitPortable automatically | | 'D_ARGS' is not recognized | Outdated START.bat — pull latest version | | Ollama very slow | Use gemma3:1b; copy data/ollama/ to local SSD if on USB 2.0 | | API key rejected | Re-run option 4 to update; verify key at provider's website | | Port 3000 in use | Dashboard already running — browse to http://localhost:3000 directly | | openclaude not found in PowerShell | Use .\RESUME.bat <session-id> instead of calling openclaude directly |

---

Security Notes

• data/ai_settings.env contains your API key — keep the drive physically secure.
• Add data/ai_settings.env to .gitignore before pushing any fork to a public repo.
• Normal Mode (option 1) asks for approval before every file write or shell command — use it on untrusted codebases.
• Limitless Mode (option 2) is fully autonomous — only use it when you trust the codebase and the task.
• All telemetry is disabled; traffic goes only to your chosen AI provider.