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:

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

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

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.