CLI guide

Alpha is the engine underneath Warpdrive: it builds an isolated container per project and runs your coding agents inside it. This page is the terminal way in — install it, start it, get an instance running, and pair it to a gateway so the desktop and phone apps can drive it. Same engine either way.

What the engine is#

One warpdrive process on your machine manages instances. An instance is a Docker container with your project folder bind-mounted at /ws, a tmux server for the agents to live in, whichever coding CLIs you enabled, and its own MCP servers. Your code never leaves the machine.

Nothing about that requires a GUI, an account, or an internet connection. The TUI, the desktop app, and the phone app are three front ends over that same engine, and the terminal is the one that needs the least installed.

Console or app?#

They are two front ends over one engine, so this is not a fork in the road you have to commit to. Most people run the app for daily work and reach for the console when they want to automate something or when the machine doing the work has no screen.

Install#

Runs on macOS, Windows, and Linux. Pick the archive for your machine — macos-arm64, macos-x64, linux-x64, linux-arm64, or the Windows zip. They differ only in the bundled TUI binary, which is native code. Optional native accelerators fall back to pure JS off their build architecture.

tar -xzf warpdrive-alpha-macos-arm64.tar.gz -C ~/
cd ~/warpdrive-alpha-*
./install.sh          # or double-click "Install Warpdrive.command"
warpdrive -h

The installer puts warpdrive on your PATH and nothing else — /usr/local/bin when it can write there, ~/.local/bin otherwise. It checks for Node and a container runtime and tells you what is missing rather than installing either behind your back, and it never touches an engine it did not start.

Extract somewhere permanent and keep the folder intact — the launcher resolves the engine and the TUI binary next to itself. Moving the whole folder later is fine; copying warpdrive out of it is not, which is why the line above symlinks. On Windows the entry point is warpdrive.cmd.

To upgrade, unpack the new archive beside the old one and repoint the symlink. State lives in ~/.warpdrive/, not in the bundle, so instances, pairings, and config survive.

Quickstart#

Same four steps on macOS, Linux, and Windows. Docker (or Podman) has to be running before the first one.

1. Point it at your projects

   warpdrive set-workspace-root ~/code   # the folder your repos live in

   Saved to ~/.warpdrive/config.json. Skip this if you only ever work in one folder — every command below defaults to the directory you are standing in.

2. Build an instance for a project

   cd ~/code/my-project
   warpdrive build      # builds the container for this folder and starts it

   The first build pulls and builds the image, so give it a few minutes. Your folder is mounted at /ws inside the container — it is the real folder, so edits inside the box are edits on disk.

3. Sit down inside it

   warpdrive attach
   # Created tmux session "warpdrive-my-project". Press <prefix>+s to switch.

   Ordinary tmux from there — start Claude Code, Codex, or whatever you enabled, and <prefix>+d detaches and leaves every agent running.

4. Or drive it from the TUI

   warpdrive            # the full-screen console: create, start, stop, attach

   The TUI does everything build and attach do, plus instance management, and it is the easier way in if you are just looking around.

Concepts#

Command reference#

warpdrive attach#

attach resolves the instance from your current directory and opens its first session in your own terminal. Run it again later and it reports the existing session instead of creating a second one. The TUI's attach and this command are the same mechanism, so they cannot drift apart.

Pair with a gateway#

This is the free, private path: your code and your containers stay on your machine while a hosted gateway provides identity, notifications, and the Store. Your machine opens one outbound authenticated WebSocket — the gateway never dials into you, so there is nothing to port-forward and nothing to expose.

# mint a pairing code in the desktop or mobile app first (they expire in 10 minutes)
warpdrive remote pair --gateway=https://your-gateway --code=XXXX-XXXX-XXXX
warpdrive remote relay

# keep it up across reboots (macOS)
warpdrive remote install-agent

--json is available on every read command and always redacts the device credential, which makes these safe to pipe into jq in a script or a log.

Configuration#

Precedence is project .warpdrive/config.json → global ~/.warpdrive/config.json → built-in defaults. Drop a project file in a repo and it wins for that repo only; everything else falls back to the global one.

Extra mounts#

{
  "sandbox": {
    "sshPort": 2222,
    "mounts": [
      { "hostPath": "/Users/you/shared-data", "containerPath": "/data", "readOnly": false },
      { "hostPath": "/Users/you/secrets",     "containerPath": "/secrets", "readOnly": true }
    ]
  }
}

hostPath must be absolute. readOnly defaults to false. The workspace folder is always mounted at /ws and does not need an entry here.

Environment variables#

A scratch engine that cannot disturb your real instances is those first three together:

WARPDRIVE_API_PORT=7788 WARPDRIVE_HOST_HOME=/tmp/wd-scratch warpdrive

Security model#

The short version: the engine listens on your machine only, and pairing a gateway to it grants that gateway nothing until you name what it may touch.

• The engine is local. It binds loopback and stays there. It can run commands in every instance you own, which is exactly why it is not something to expose to a network — pair to a gateway instead. The relay is outbound-only and authenticated, so nothing on your machine has to listen for it.
• Remote reach is bounded by bindings, not by pairing. A gateway can only touch the workspaces and providers you approved by ID with bind-workspace and bind-provider. Anything unbound is refused.
• Provider credentials stay here. You sign in to Claude Code, Codex, or Copilot inside the instance. Nothing ships those keys to a hosted service.
• Instances are isolated from each other. Each one is its own container, its own tmux server, and its own workspace mount.
• Watching is not driving. Read-only session access is a real boundary, not a UI hint — it is what lets a phone watch a run without being able to type into it.

Troubleshooting#

Known limits#

• Docker only. Warpdrive is not runtime-abstracted and is not multi-machine — a gateway is what makes several machines feel like one fleet.
• No in-browser code editor. Attach, or open your own editor against the instance.
• In the standalone tarball, the vault worker builds its container from a Dockerfile that ships with the full desktop install. Vault capture warns and retries; everything else runs normally.
• The bundle is unsigned. macOS Gatekeeper does not quarantine extracted tarballs the way it does DMGs, so no extra step is normally needed.