Make it yours.
Run it your way.

Getting Started

Choose the smallest path that matches what you want to do:

Complete download table

Published files live in /downloads/. A build that has not been released yet will not be available at its link.

Verify a download

Each published file has a matching .sha256.txt file beside it. Download both files, then verify before installing:

# macOS or Linux
shasum -a 256 -c Warpdrive.dmg.sha256.txt

# Windows PowerShell — compare this value with the .sha256.txt file
Get-FileHash .\WarpdriveSetup.exe -Algorithm SHA256

Do not install a file when the digest differs. Download it again; if the second copy also differs, report the release.

Basic Mode

Basic Mode is the everyday path. It keeps configuration out of the way and centers the Assistant, your Apps, conversations, and the Store.

1. Open Assistant and choose the Assistant you want to use.
2. Describe the App or change you want in plain language.
3. Open the live result from Apps.
4. Return to the same conversation when you want a change.

Switch to Advanced Mode when you need to choose an exact Workspace, AI provider, Instance, or Conductor.

Advanced Mode

Advanced Mode exposes the full operating surface: Instances, Workspaces, Studio, Conductors, terminals, files, previews, snapshots, and activity.

1. Add or choose a Workspace.
2. Enable the AI providers and tools that should be available.
3. Create an Instance and choose the Workspace, provider, and optional Orchestrator.
4. Connect the provider from inside the running Instance.
5. Work from chat, terminal, files, previews, or a Conductor queue.

Apps

Apps are live, owned results. They can come from a conversation, the Store, or a Workspace you already maintain.

• Create: ask the Assistant for an App and describe the people, data, and task it should support.
• Install: choose an App in the Store and select Get.
• Change: open the App and ask for a change from the same context.
• Open: use the published App address from desktop, web, or mobile.

Preview is the technical readiness surface in Advanced Mode. Apps are the owned destination people use.

Assistants

Assistants give Basic Mode a plain-language starting point. In Advanced Mode, the same work is configured through providers, tools, and Instances.

• Use a provider account you already have, an API-backed provider, or Local AI.
• Keep display names separate from backend provider IDs when using APIs or automation.
• Grant only the Workspace and provider access that a remote machine needs.

Instances

An Instance is one running place for AI work. It binds a Workspace to the tools, provider, and optional Orchestrator selected for that job.

Engine requirements

Engine configuration

Configuration precedence is project .warpdrive/config.json, then global ~/.warpdrive/config.json, then built-in defaults.

Extra mounts belong in the project or global configuration. Host paths must be absolute:

{
  "containerCli": "podman",
  "sandbox": {
    "mounts": [
      { "hostPath": "/Users/you/shared", "containerPath": "/data", "readOnly": true }
    ]
  }
}

Conductors

Conductors coordinate work across one or more agents. Use one when a goal has repeatable steps, review gates, retries, or work that can run in parallel.

1. Open Studio and choose or create an Orchestrator.
2. Add the agents, sequence, limits, and approval points.
3. Save the Orchestrator and attach it when creating an Instance.
4. Give the Conductor a concrete goal, then follow progress in the conversation and Activity.

Use a direct Assistant conversation for a single small task. Use a Conductor when coordination itself is part of the work.

Gateway

The Gateway is the selected access boundary for clients. It authenticates the session and routes requests to the service that owns the work. It does not become a copy of your Workspace.

How the components fit

The desktop package starts a local Gateway on 127.0.0.1:8787 and a local engine on 127.0.0.1:7777. A hosted Gateway terminates browser or phone traffic over HTTPS while paired machines make outbound relay connections.

Hosted Gateway configuration

Terminate TLS before the Gateway, expose only the intended HTTPS origin, restrict trusted browser origins, and back up relay state with Gateway logs.

CLI

The CLI is the terminal-first interface for creating, running, attaching to, and remotely connecting Instances. The complete CLI guide contains every command and flag.

Install and add it to PATH

tar -xzf warpdrive-alpha-macos-arm64.tar.gz -C ~/
cd ~/warpdrive-alpha-*
./install.sh
warpdrive --help

The installer links warpdrive into /usr/local/bin when writable, otherwise ~/.local/bin. If needed, add the latter to your shell:

export PATH="$HOME/.local/bin:$PATH"

Keep the extracted archive together. The launcher resolves its runtime beside itself. On Windows, extract the zip and run Install Warpdrive.bat.

Core commands

Headless installation

1. Install Node.js 20 or newer and a supported container runtime.
2. Download the archive for the server architecture and verify its checksum.
3. Extract it to a permanent folder and run ./install.sh --yes.
4. Run warpdrive serve in the foreground once and confirm the engine listens on loopback.
5. Create a systemd, launchd, or equivalent service under the same OS user that owns ~/.warpdrive/. Set it to restart on failure and keep the service logs.
6. For remote control, complete the pairing and binding steps.

Local AI

Local AI lets supported agents use a model running on your hardware. Open Settings → Local AI, review the model Warpdrive recommends for the machine, then select Set up on this machine.

From the CLI, use:

warpdrive local-ai setup
warpdrive local-ai status

The Local AI guide covers hardware sizing, model choice, existing Ollama or LM Studio installs, ports, checksums, privacy, and troubleshooting.

Remote Access

A paired machine opens one outbound authenticated relay to the selected Gateway. It does not expose the local engine, container runtime, SSH, or preview ports to the public internet.

1. Create a pairing code in Warpdrive. Codes expire after 10 minutes.
2. Redeem the code on the machine that will run work:

warpdrive remote pair \
  --gateway=https://gateway.example.com \
  --code=XXXX-XXXX-XXXX-XXXX-XXXX

Approve exact backend Workspace and provider IDs before remote commands may use them:

warpdrive remote bind-workspace \
  --workspace-id=<backend-id> \
  --path=/absolute/path/to/project

warpdrive remote bind-provider \
  --provider-id=<backend-id> \
  --provider=claude-code

Start and inspect the relay:

warpdrive remote relay
warpdrive remote status

# macOS: keep the relay running after login and across reboots
warpdrive remote install-agent

Use warpdrive remote relay --once to diagnose one foreground connection. Use warpdrive remote uninstall-agent to remove the macOS LaunchAgent.

Security

• Short-lived pairing: codes are single use and expire after 10 minutes by default.
• Outbound-only workers: paired machines initiate the relay; they do not open a public listener.
• Bound access: pairing alone grants no Workspace or provider access. Bind exact backend-owned IDs.
• Protected credentials: device credentials are encrypted locally and redacted from status and JSON output.
• Separate keys: hosted Gateway signing keys must be unique, non-placeholder values of at least 32 characters.
• Durable audit state: back up relay state and logs together. Pairing, relay, command, revocation, and rotation events are recorded.
• Local AI scope: local-model prompts stay on the machine, but sign-in, Store, Gateway, and any cloud provider you enable still use the network.

Troubleshooting

For more detail, use the CLI troubleshooting table or the Local AI troubleshooting table.