Test OpenClaude Portable Before It Touches Your Repo

The useful part of OpenClaude Portable is not the USB pitch. The better story is isolation by convention: a bundled Node runtime, OpenClaude engine install, provider settings, sessions, cache, local model files, proxy logs, and dashboard state all live under one folder when the launchers are used.

That makes it worth rescuing from the rewrite queue. A Codex or Claude Code user can use this shape as a disposable agent lab before letting a new runtime near a real repository. It also has sharp edges. The launcher downloads code during first setup. Provider keys land in data/ai_settings.env. The dashboard exposes file-write and command tools. Limitless Mode skips approval prompts. A serious article should teach those boundaries rather than repeat the portable marketing line.

Why this candidate is worth saving

The original article failed because it read like a feature list: portable, local models, dashboard, provider choices. The source supports a better article. The README, start.sh, START.bat, tools/local-proxy.js, tools/change_provider.sh, tools/setup_local_models.sh, tools/open_dashboard.sh, and dashboard/server.mjs show exactly what a reader must inspect before using the tool.

That is the quality bar for this site. A topic is useful when it changes how someone runs agent work. OpenClaude Portable qualifies if the reader uses it as a controlled test folder, not as proof that any USB-based agent setup is safe.

Treat portability as a boundary, not a sandbox

The Linux and macOS launcher redirects CLAUDE_CONFIG_DIR, HOME, USERPROFILE, APPDATA, LOCALAPPDATA, XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_CACHE_HOME into data/. The Windows launcher creates the same kind of local data boundary. That is the main technical idea.

It is not an operating-system sandbox. If the dashboard workdir points at a real repository, its tools operate there. If a provider key is saved, the portable folder now carries a secret. If a shell command runs from the dashboard, it runs on the host machine with the permissions of the current user. The folder boundary makes state easier to inspect and remove; it does not make unsafe agent behavior harmless.

Audit the first run

A careful first run starts in a scratch folder:

git clone https://github.com/techjarves/OpenClaude-Portable.git
cd OpenClaude-Portable
chmod +x start.sh
./start.sh

start.sh downloads Node.js 22.14.0 into engine/node-<platform>-<arch>, installs @gitlawb/openclaude@latest into engine/node_modules, and uses data/npm-cache for npm cache isolation. On Windows, START.bat can also download GitPortable 2.54.0 when Git Bash support is needed.

That means the first run is a supply-chain event, not a pure offline launch. Save offline mode for the second phase:

./start.sh --offline

Offline mode skips update checks only after the engine exists. Before moving the folder to a USB drive, inspect engine/, data/, and the install log. If the first setup fails, delete the folder and restart from a known clean copy rather than patching a half-installed agent runtime.

Verify what lands in data

The folder to inspect is data/. The README maps the important paths: data/ai_settings.env stores active provider settings, data/openclaude/ stores session history and agent memory, data/ollama/ stores local Ollama binaries and model data, and data/proxy.log records local proxy events.

Run this before treating the runtime as portable:

grep -n "CLAUDE_CONFIG_DIR\|XDG_CONFIG_HOME\|XDG_DATA_HOME" start.sh
cat data/ai_settings.env
du -sh engine data

Pass means the env redirects point at data/, the provider file matches the endpoint you meant to use, and the folder size is realistic for the drive that will carry it. Fail means stop. Do not put this folder in cloud sync or a shared drive once real keys are present. The advantage is that state is local and reviewable. The cost is that the whole folder becomes sensitive.

Read provider setup like an API contract

Provider setup is not just a menu. start.sh and tools/change_provider.sh save concrete environment variables into data/ai_settings.env. For OpenAI-compatible backends the file can include CLAUDE_CODE_USE_OPENAI=1, OPENAI_BASE_URL, OPENAI_API_FORMAT=chat_completions, OPENAI_API_KEY, and OPENAI_MODEL.

The scripts cover OpenRouter, Gemini, Anthropic, NVIDIA NIM, DeepSeek, OpenAI, Ollama, LM Studio, and custom OpenAI-compatible endpoints. LM Studio checks http://localhost:1234/v1/models by default. Custom providers ask for a base URL ending in /v1, an optional key, and a model name. For OpenAI-compatible mode, the launcher relies on env vars rather than passing --provider openai.

The adoption rule is simple: after provider setup, read data/ai_settings.env before launching an agent. Confirm the base URL, model ID, and key location. If the provider uses local networking, verify the local service before using the dashboard or CLI.

The local proxy changes the problem

tools/local-proxy.js sits between OpenClaude and Ollama: OpenClaude talks to 127.0.0.1:11435, and the proxy forwards to Ollama on 127.0.0.1:11434. It only modifies POST requests to /chat/completions. Its main behavior is trimming system prompts to a 1200-character cap and appending a note that the prompt was truncated for local model performance.

That is a real tradeoff. Local models can be easier to run when a giant system prompt is cut down, but the agent may receive less policy, role, or tool context than the upstream runtime expected. Do not treat proxy speed as free quality. After trying local Ollama mode, read the log:

tail -n 80 data/proxy.log

If results get strange, compare a task with proxy mode off and on. The proxy is a local-model adapter, not a proof that a small local model can follow the same agent contract.

The dashboard is an agent runtime

The dashboard matters because it is not a passive status page. dashboard/server.mjs defines tools named write_file, read_file, list_directory, execute_command, and search_files. The server treats write_file and execute_command as write tools. It also has routes for config import and export, model discovery, key verification, Ollama start and stop, system info, logs, workdir selection, chat history, and agent chat streaming.

The default WORK_DIR is the OpenClaude Portable root until /api/workdir changes it. execute_command runs with cwd: WORK_DIR and a 30-second timeout. write_file can create parent directories and overwrite files under the resolved path.

That is valuable for a disposable repo and risky for a real one. Before using the dashboard, ask what directory it can touch:

curl -s http://127.0.0.1:3000/api/workdir
grep -n "execute_command\|write_file\|WORK_DIR" dashboard/server.mjs

The pass condition is narrow: the dashboard points at a scratch checkout, the first task is read-only, and the command log shows nothing surprising. If it points at your main repo by accident, fix the workdir before sending another prompt. If the workflow later moves to a production repo, record what commands the agent attempted.

Normal Mode should be the default

The launcher menu offers Normal Mode and Limitless Mode. In start.sh, Limitless Mode maps to --dangerously-skip-permissions when launching the bundled OpenClaude binary. The README says Normal Mode asks before writing files or running commands, while Limitless Mode runs without approval prompts.

That boundary should decide adoption. Normal Mode is for first contact with a repo. Limitless Mode belongs only after the project, provider, model, prompt behavior, dashboard workdir, and rollback path are all known. On an unknown repository, Limitless Mode turns a portable test into a host-level automation risk.

Local model setup still needs review

tools/setup_local_models.sh installs Ollama under data/ollama, stores model data under data/ollama/data, and warns when free disk space is below 5GB. That is a reasonable folder shape for USB-style work, but model files can still be large and slow on removable storage.

The practical test is disk and latency, not optimism. Run local setup on a fast disk first, confirm model storage size, then move the folder only if startup and first response times are acceptable. If a local model is used for real coding work, keep tasks narrow: inspect files, propose edits, run one small command. Broad refactors are where truncated prompts and weaker local models tend to fail.

Where it fits in a Codex workflow

OpenClaude Portable is a good fit for experiments that should not touch host dotfiles: workshops, machine-to-machine demos, provider trials, offline-ish local model tests, and agent dashboard trials against a disposable repository. For Codex ecosystem readers, the pattern is the point: isolate state first, then evaluate agent behavior.

It is a weaker fit when the project already depends on managed credentials, corporate endpoint policy, centralized audit logs, or a real sandbox. It is also a poor first choice for production repositories where a host-installed and already-reviewed agent environment exists. The portable folder is easier to delete; it is not automatically easier to govern.

The scratch-repo test

Use this as the article's pass/fail test. First, clone into a scratch directory. Second, run the first setup on a trusted network and inspect engine/ and data/. Third, configure one provider and read data/ai_settings.env. Fourth, launch Normal Mode only. Fifth, open the dashboard and confirm /api/workdir points at a disposable checkout. Sixth, ask the agent to summarize one file, then ask it to create one throwaway file. Finish by reading data/openclaude/, data/proxy.log, and the git diff.

Pass means the state is inside data/, the provider endpoint is the one you chose, the dashboard workdir is disposable, the agent asks before writes, and the diff contains only the throwaway file. Fail means the folder stays in lab status. Only after a pass should the runtime move to a USB drive or a real project.

Save OpenClaude Portable as an isolation and audit guide, not as a travel-friendly coding-agent pitch. It is useful when a reader needs a disposable OpenClaude runtime with local state, provider settings, dashboard tools, and optional local models in one folder; it is unsafe when they mistake that folder boundary for a sandbox or use Limitless Mode before proving the workdir and provider behavior.

Practical takeaway

Before using OpenClaude Portable on real work, clone it into a scratch folder, run ./start.sh, inspect data/ai_settings.env, confirm curl -s http://127.0.0.1:3000/api/workdir, stay in Normal Mode, and run one read-only agent task before any write. Treat data/ as secret-bearing once provider keys are saved.