PortableCoder

A portable Claude Code launcher you can copy to any Windows, macOS, or Linux computer — or put on a flash drive — and run without a system-wide install.

Currently supports Claude Code. Support for other AI coding CLIs (OpenAI Codex, Gemini CLI, etc.) is planned.

What it does

• Runs Claude Code from a self-contained folder — no system-wide install of Node.js or Claude Code needed
• Stores OAuth credentials portably inside state/auth/ — no registry writes, no system config files
• Claude Code has full access to files on the host machine
• Supports API key mode as an alternative to OAuth

How it works

PortableCoder bundles a portable Node.js runtime and a local Claude Code installation inside the folder. When you run scripts\pcoder, it uses these bundled tools to launch Claude Code directly on the host — no VM, no container, no install. Your OAuth credentials are stored in state/auth/ and travel with the folder.

A fallback VM mode is also available on Windows, which runs Claude Code inside a QEMU Linux VM for environments where host-native execution isn't possible.

Quick Start

1 — Bootstrap (first time only)

You need Node.js available on the machine (or already bundled in runtime/node/) to run the bootstrap. After bootstrap completes, the bundled Node.js is used for everything — no system Node.js required on future machines.

Windows

scripts\pcoder setup --init
scripts\pcoder runtime bootstrap-host-native

Linux / macOS

scripts/pcoder setup --init
scripts/pcoder runtime bootstrap-host-native

This downloads a portable Node.js and installs Claude Code into the folder (~50 MB).

2 — Authenticate

scripts\pcoder auth login

Opens a browser for Anthropic OAuth. Credentials are saved to state/auth/ (gitignored).

3 — Launch

REM Launch in the current directory
scripts\pcoder

REM Launch in a specific project folder
scripts\pcoder run --project C:\path\to\my-project

REM Pass extra arguments directly to claude
scripts\pcoder -- --resume
scripts\pcoder -- --print "explain this codebase"

On Linux / macOS, use scripts/pcoder with forward slashes.

Run Modes

Mode	How it works	File access	Setup
host-native (default)	Runs Claude Code directly on the host via bundled Node.js	Full host filesystem	runtime bootstrap-host-native
linux-portable	Runs Claude Code inside a QEMU Linux VM	Synced project directory only	runtime bootstrap

Host-native is the default when a bundled Claude Code runtime is detected. If only the VM runtime is present, VM mode is used automatically.

Switching modes

REM Force VM mode
scripts\pcoder setup --windows-mode linux-portable

REM Force host-native mode
scripts\pcoder setup --windows-mode host-native

REM Override for a single session
scripts\pcoder run --mode linux-portable

Authentication

OAuth (default)

OAuth credentials are written to state/auth/claude/host/ and travel with the folder. No credentials are stored in system directories.

scripts\pcoder auth login       &REM Log in via browser
scripts\pcoder auth status      &REM Show current auth state
scripts\pcoder auth logout      &REM Remove stored credentials

API key mode

scripts\pcoder setup --claude-auth api
set ANTHROPIC_API_KEY=sk-ant-...
scripts\pcoder

On Linux / macOS:

export ANTHROPIC_API_KEY=sk-ant-...
scripts/pcoder

ANTHROPIC_AUTH_TOKEN is also accepted as an alias for ANTHROPIC_API_KEY.

VM Mode (Windows)

VM mode runs Claude Code inside a self-contained QEMU Linux VM. This is useful when you cannot or do not want to run Claude Code directly on the host. Claude Code runs inside the VM and does not have direct access to host files — project files are synced in and out via SSH.

REM One-time setup: download QEMU + Ubuntu image (~1 GB)
scripts\pcoder runtime bootstrap

REM Optional: verify the VM boots and tools are provisioned
scripts\runtime\windows\smoke-check.cmd

REM Launch
scripts\pcoder run --mode linux-portable

VM mode uses Windows Hypervisor Platform (WHPX) acceleration when available, and falls back to software emulation (TCG) if not.

All Commands

Command	Description
pcoder	Launch Claude Code in the current directory
pcoder [-- <claude args>]	Launch and pass extra args directly to claude
pcoder doctor	Check environment health
pcoder setup --init	Initialize state/settings.json with defaults
pcoder setup --show	Print current settings
pcoder setup --claude-auth <oauth|api>	Change authentication mode
pcoder setup --windows-mode <linux-portable|host-native>	Change Windows run mode
pcoder setup --sync-back <true|false>	Control whether VM files sync back after a run
pcoder auth status	Show authentication status
pcoder auth login	Log in via OAuth
pcoder auth logout	Log out and clear stored credentials
pcoder runtime probe	Show available runtime backends
pcoder runtime bootstrap [--force]	Download VM runtime (QEMU + Ubuntu)
pcoder runtime bootstrap-host-native [--force]	Download Node.js + Claude Code for host-native mode
pcoder run [--project <path>]	Run in a specific project directory
pcoder run [--mode <linux-portable|host-native>]	Override run mode for one session
pcoder run [--no-sync-back]	Skip syncing VM files back after this run
pcoder run [-- <claude args>]	Pass extra arguments directly to claude

File Layout

PortableCoder/
  scripts/
    pcoder.cmd              <- Windows entry point
    pcoder                  <- Linux / macOS entry point
    pcoder.cjs              <- Main launcher logic (Node.js, cross-platform)
    lib/
      paths.cjs             <- Shared path helpers and utilities
    adapters/
      catalog.json          <- Tool adapter definitions
    runtime/
      bootstrap-host-native.cjs  <- Host-native bootstrap (downloads Node + Claude Code)
      windows/              <- Windows VM helper scripts
        lib/
          common.ps1        <- Shared PowerShell functions
        bootstrap-runtime.ps1/.cmd
        start-vm.ps1/.cmd
        stop-vm.ps1/.cmd
        smoke-check.ps1/.cmd
      linux/
        smoke-check.sh      <- Linux smoke test
  runtime/                  <- Runtime binaries (gitignored, travels with the folder)
    node/                   <- Bundled portable Node.js (populated by bootstrap-host-native)
    claude/                 <- Bundled Claude Code (populated by bootstrap-host-native)
    qemu/                   <- QEMU binaries (populated by runtime bootstrap)
    linux/
      images/               <- Ubuntu VM image (populated by runtime bootstrap)
      ssh/                  <- Generated SSH keypair for VM access
      vm-manifest.json      <- VM configuration
      cloud-init/           <- Cloud-init configuration for VM provisioning
  state/                    <- Runtime state (gitignored, travels with the folder)
    settings.json           <- Your settings (created by setup --init)
    auth/
      claude/host/          <- Portable OAuth credentials (gitignored)
    vm/                     <- VM runtime state (PID, SSH port, logs)
    tmp/                    <- Temporary working files
  profiles/
    profiles.json           <- Environment profile definitions
    defaults/               <- Default secrets policy documentation
    local/                  <- Local .env overrides (gitignored)

Environment Variables

Variable	Purpose
ANTHROPIC_API_KEY	API key (api auth mode)
ANTHROPIC_AUTH_TOKEN	Alias for ANTHROPIC_API_KEY
ANTHROPIC_BASE_URL	Override the Anthropic API base URL
PCODER_CLAUDE_CMD	Override the path/command used to run claude
PCODER_VM_SSH_TIMEOUT_SECONDS	Max seconds to wait for VM SSH (default: 300)
PCODER_VM_HOST	VM SSH hostname (default: 127.0.0.1)
PCODER_VM_USER	VM SSH username (default: portable)
PCODER_VM_SSH_KEY	Path to VM SSH private key
PCODER_VM_PROJECTS_ROOT	Remote path for synced projects (default: /home/portable/projects)
PCODER_SSH_CMD	Override SSH client path
HTTP_PROXY / HTTPS_PROXY / NO_PROXY	Proxy settings forwarded into the VM

Security

• OAuth credentials are stored in state/auth/ which is gitignored. They will not be committed to the repository.
• API keys are passed via environment variables and never written to disk by PortableCoder.
• Host-native mode gives Claude Code the same file access as any program you run. It can read and write any file your user account can access.
• VM mode isolates Claude Code inside a QEMU VM. It can only access files explicitly synced into the VM.
• SSH keys for VM access are generated locally and stored in runtime/linux/ssh/ (gitignored).

Portability

• Copy the entire PortableCoder/ folder to a USB drive or new machine and it works
• No registry writes, no system PATH changes, no admin rights required
• OAuth credentials and settings travel with the folder
• All runtime binaries (runtime/node/, runtime/claude/, runtime/qemu/) are gitignored — they are populated by bootstrap scripts and stay local
• Settings are stored in state/settings.json (gitignored so personal config is never committed)