Make it yours.
Run it your way.

Getting Started

Your first ten minutes

1. Request access. Open app.warpdrive.md and choose Request access on the sign-in screen. Warpdrive is in beta, so each request is reviewed before the account opens.
2. Sign in. Once your request is approved, sign in on the same screen. You start in Basic Mode.
3. Choose your AI. When you make your first Space, choose the AI it uses: Warpdrive AI, which needs no key; Local AI, a model on your own computer; or an AI account you already have, such as Codex or Claude Code, which you sign in to from the running Space.
4. Ask the Assistant to build an App. In the Chat, say what you want — “build me a …” — and who it is for and what it should keep track of.
5. Open it in Apps. The finished App appears in your Space's Apps. Open it, use it, and come back to the same Chat when you want a change.
6. Optional: bring your own computer and phone. Install the Warpdrive desktop app from Settings → About to run Spaces on your own computer. It runs your own Gateway — the connection point your other devices use. Then pair your phone by scanning a QR code.

Choose your path

After the first ten minutes, pick the smallest path that matches what you want to do:

Where the installers are

Builds are not published on this site. Sign in with an approved account and the installers are in the app under Settings → About; an installed copy updates itself from there. These are the files you will find:

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 your Space, its Assistant, your Apps, Chats, and the Store. A Space is your lasting place for Apps, Chats, and work in progress.

1. Open your Space and choose the kind of help you want from the Assistant selector.
2. Describe the App or change you want in plain language.
3. Open the live result from Apps.
4. Return to the same Chat when you want a change.

Switch to Advanced Mode, when your account includes it, to choose an exact Workspace, AI provider, Instance, or Conductor.

Advanced Mode

Advanced Mode exposes the full operating surface: Instances, Workspaces, Studio, Orchestrators, Conductors, terminals, files, previews, snapshots, and activity. The Instance is the same resource Basic Mode calls a Space.

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.

Apps

Apps are live, owned results. They can come from a Chat, 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.

In Advanced Mode you also see each App's Preview: the technical view that tells you whether the App has started and is ready to open. The App itself is what 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 Warpdrive AI, 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 — Basic Mode calls it a Space. It binds a Workspace to the tools, provider, and optional Orchestrator selected for that job, and each one runs in its own isolated container.

Engine requirements

Engine configuration file

The engine reads JSON configuration. Precedence is project .warpdrive/config.json, then global ~/.warpdrive/config.json, then built-in defaults. Use containerCli in the global file to pin a container client, and sandbox.mounts for extra folders. Host paths must be absolute:

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

Engine environment variables

These override the configuration file for one shell or one service, which is useful for scripts and for running a second engine beside the first.

The CLI guide covers both in more detail.

Orchestrators

An Orchestrator is a reusable definition of how coordinated work runs: which agents take part, in what sequence, where the work stops for your approval, and which providers, MCP servers, and tools it requires. Selecting one changes future work on a compatible Instance; it never replaces the Instance or its Workspace.

There are two ways to author one:

• In the app: open Studio in Advanced Mode, then add the agents, sequence, limits, and approval points. Studio shows whether an Instance is Ready here or Needs setup for it.
• As a manifest: write a Git repository with a warpdrive.manifest.yml at its root that declares the sessions, background processes, and actions an Instance should have. The engine loads it by repository and branch, which suits the CLI. A Studio Orchestrator can call the actions a manifest declares. The format is in the manifest reference.

Orchestrator vs Conductor

Auto-Tune

Auto-Tune is an optional Studio setting that tries improvements to an Orchestrator on its own. It proposes a small change, benchmarks it against a metric — pass_rate by default — and checks it on a separate holdout set of cases. A change is kept only when it measurably beats the current version and does not make the holdout results worse.

• Each change is limited in size: by default at most 3 files and 120 changed lines.
• Runs are bounded by cost, run time, and consecutive failures, all set by the Gateway operator.
• It runs only where the Gateway operator has switched it on, and only on Linux hosts. If your Gateway has not enabled it, the Studio setting has no effect.

Conductors

A Conductor runs an Orchestrator: it coordinates work across one or more agents and keeps you in one Chat. 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 its Chat and in Activity.

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

Gateway

The Gateway is the connection point your clients use. It signs the session in and routes each request to the service that owns the work. It does not become a copy of your Workspace.

How the components fit

The Warpdrive desktop app runs your own Gateway — the connection point your other devices use — on 127.0.0.1:8787, and a local engine on 127.0.0.1:7777. A hosted Gateway serves browsers and phones over HTTPS, while paired machines make outbound relay connections to it.

Running a hosted Gateway yourself? Its settings are in For operators.

CLI

The Warpdrive CLI is the terminal-first interface for creating, running, attaching to, and remotely connecting Instances. The Warpdrive 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 your agents use a model running on your own hardware, with no key and no per-question bill. In Basic Mode, choose Local AI as your Space's AI and your Assistant uses it — it runs through OpenCode, which is what the local model connects to. The model runs on the computer with the Warpdrive desktop app.

To set it up, 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 are 20 characters in five groups of four, and 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.
• Durable audit state: pairing, relay, command, revocation, and rotation events are recorded.
• Local AI scope: local-model inference stays on the machine, but sign-in, the Store, the Gateway, Chat history, and any cloud provider you enable still use the network.

For where each kind of data is stored, read Trust & Privacy. Hosted Gateway signing keys and backups are covered in For operators.

Troubleshooting

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

API and manifest reference

Building on Warpdrive rather than using it? The API and manifest reference covers the engine's local HTTP API on port 7777, the warpdrive.manifest.yml Orchestrator format, MCP server wiring, and publishing to the Store.

For operators

This section is for people who run a hosted Gateway for others. You do not need any of it to use Warpdrive, the desktop app, or the CLI.

Hosted Gateway configuration

A hosted Gateway reads these environment variables. They are separate from the engine's JSON configuration.

• Terminate TLS before the Gateway, expose only the intended HTTPS origin, and restrict trusted browser origins.
• Give every signing key a unique, non-placeholder value of at least 32 characters.
• Back up relay state and Gateway logs together, so pairing and command history can be audited.
• Auto-Tune is switched on or off for the whole Gateway by the control plane's AgentAutoTune__Enabled setting, and runs only on Linux hosts.