Warpdrive CLI guide

The Warpdrive CLI drives the engine underneath Warpdrive: it gives each project its own Instance — an isolated container — 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 container — Docker, Podman, or another supported runtime provides the isolation — 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. The engine itself never sends your code anywhere; what an agent sends to its AI provider is covered in Trust & Privacy.

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. Your container runtime — Docker, Podman, or another supported one — 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 Instance 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 path that keeps your work at home: your code and your Instances 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. Commands and terminal output you send through it do cross the relay; see Trust & Privacy.

# mint a pairing code in the desktop or mobile app first (they expire in 10 minutes)
# codes are 20 characters in five groups of four
warpdrive remote pair --gateway=https://your-gateway --code=XXXX-XXXX-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.

Container runtime#

Leave it unset and the engine uses whichever known client it finds on PATH, in this order: docker, podman, nerdctl, Apple container. To pin one — or to use any other client that speaks the docker CLI — name its binary or full path in the global config:

{ "containerCli": "podman" }

The WARPDRIVE_CONTAINER_CLI environment variable does the same for one shell and wins over the config file. The choice is read at start-up, so restart the engine after changing it.

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 a second port and a second state root together:

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

API and manifest reference#

Everything the TUI and the apps do goes through the engine's local HTTP API on port 7777. The API and manifest reference covers that API, the warpdrive.manifest.yml Orchestrator format, MCP server wiring, and publishing to the Store.

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. The engine does not ship those sign-ins 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#

• One engine drives one machine. A Gateway is what makes several machines feel like one fleet.
• Apple Container needs macOS 26 or later. Any other client has to accept the docker CLI's commands and flags, because the engine shells out to it the same way.
• 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.