Warpai warpai DOCS
Home Download 1 中文

Installation & Setup

Warpai 1.7.8.2 is a native desktop application for macOS, Windows, and Linux. Linux desktop packages are available for x64 and ARM64. For remote Linux, macOS, and Windows hosts and Windows WSL 2, use the standalone Warpai Companion.

Desktop Installation

1. macOS (Apple Silicon)

Installation Steps:

  1. Open the downloaded .dmg disk image.
  2. Drag Warpai.app into your /Applications folder.
  3. Launch Warpai from Launchpad or Spotlight.
macOS Gatekeeper Note (Ad-hoc Signature)

Warpai desktop builds are ad-hoc signed. On first launch, macOS may present a dialog saying "Warpai cannot be opened because the developer cannot be verified".

  • Option A (System Settings): Open System Settings > Privacy & Security, scroll to Security, and click Open Anyway.
  • Option B (Terminal Command): Run xattr -d com.apple.quarantine /Applications/Warpai.app
SHOT-22 (P2) macOS Gatekeeper 'Open Anyway'

macOS 初次安装信任指引：展示系统设置“安全性与隐私”中点击“仍要打开”（Open Anyway）的操作界面截图。

建议尺寸: 900x550 目标路径: docs/images/macos-gatekeeper-open-anyway.png 截图待补充 · 对应表格 docs/SCREENSHOT-INVENTORY.xlsx

2. Windows (x64)

Installation Steps:

  1. Double-click WarpaiSetup-1.7.8.2-windows-x64.exe.
  2. If Windows Defender SmartScreen displays “Windows protected your PC”, click More info followed by Run anyway.
  3. Follow the wizard. A desktop shortcut and Start Menu entry will be created.
SHOT-23 (P2) Windows SmartScreen 'Run Anyway'

Windows Defender SmartScreen 拦截指引：展示点击“更多信息”后出现的“仍要运行”按钮操作截图。

建议尺寸: 800x450 目标路径: docs/images/windows-smartscreen-run-anyway.png 截图待补充 · 对应表格 docs/SCREENSHOT-INVENTORY.xlsx

3. Linux Desktop (x64 and ARM64)

  • System requirements: 64-bit x86 or ARM processor and glibc 2.31 or newer.
  • The commands below use x64 filenames; replace x64 with arm64 on ARM64 systems.
  • Ubuntu / Debian (.deb):
  • Fedora / RHEL (.rpm):
  • Arch Linux (.pkg.tar.zst):
  • AppImage: x64 · ARM64 
    chmod +x Warpai-1.7.8.2-linux-x64.AppImage
./Warpai-1.7.8.2-linux-x64.AppImage

Use the package matching your processor architecture. Release checksums are published alongside the installers.

Remote Workspaces & Companions

Warpai enables full terminal, file browsing, in-app editing, and agent collaboration across remote servers and containers without altering your remote environment, powered by the standalone Warpai Companion binary.

For complete host setup, see OpenSSH Server Installation & Setup and Windows WSL Installation & Setup. Both guides cover Companion installation, per-Agent MCP configuration, and the two-tier MCP boundary between the desktop client and the Agent’s environment.

Architecture Highlights:

  • Private Bundled Git: Companion embeds its own private Git runtime. Your remote server does not require Git, Node.js, Python, tmux, or socat to be pre-installed.
  • Zero Background Resource Waste: Companion starts on demand upon terminal connection and automatically terminates after 60 seconds of idle time.
Remote Platform Package Installation Command
Linux x64 (Ubuntu 20.04+, Debian, RHEL) WarpaiCompanion-5.5.0-linux-x64.run chmod +x WarpaiCompanion-*.run && ./WarpaiCompanion-*.run
macOS Apple Silicon WarpaiCompanion-5.5.0-macos-arm64.dmg Copy warpai-companion to ~/.config/warpai/bin/
Windows x64 WarpaiCompanion-5.5.0-windows-x64-setup.exe Run setup installer on remote host.
SHOT-17 (P1) Remote SSH Project Workspace

SSH 远程无缝漫游：终端 SSH 连入云服务器并 cd 进工程，右侧自动列出远程 SFTP 文件树，左侧联动接管远程 Linux 上的 Agent。

建议尺寸: 1440x810 (16:9) 目标路径: docs/images/remote-ssh-workspace.png 截图待补充 · 对应表格 docs/SCREENSHOT-INVENTORY.xlsx

Windows WSL 2 Integration

Warpai on Windows integrates directly with WSL 2 distributions without running a separate network bridge or requiring third-party X11 servers.

SHOT-18 (P1) Windows WSL 2 Direct Integration

Windows 下 WSL 2 深度集成：终端运行 Ubuntu bash 并启动 Linux CLI Agent，Windows 本地 GUI 完美编排调度。

建议尺寸: 1440x810 (16:9) 目标路径: docs/images/windows-wsl2-integration.png 截图待补充 · 对应表格 docs/SCREENSHOT-INVENTORY.xlsx

Configuration & User Data Paths

Warpai maintains all durable data, settings, and caches locally on your machine:

  • macOS / Linux: ~/.config/warpai/
    • Preferences: ~/.config/warpai/settings.toml
    • Agent Communication Cache: ~/.config/warpai/agent_bus/
    • Local Database: ~/.config/warpai/warpai.sqlite
  • Windows: %APPDATA%\Warpai\
    • Preferences: %APPDATA%\Warpai\settings.toml
    • Local Database: %APPDATA%\Warpai\warpai.sqlite