AI Cockpit — Manual Install Guide

You are reading this because you chose the manual-install zip, not the scripted installer. This is the hand-copy path for people who want full control or want to see exactly what goes where before running anything.

Prefer automation instead? Every install script from the scripted path is included in this same zip, unchanged — install_cockpit.sh (Linux), install_cockpit_macos.sh (macOS), install_windows.ps1 (Windows, via WSL2). You can switch to that path at any point by just running the relevant script from a terminal in the folder you extracted — nothing about having unzipped first changes how they work.

Full account vs Stand-alone — one app, one flag

There's only one copy of the app in this zip now — Full account and Stand-alone aren't separate downloads anymore, just a choice you make by hand at the end of setup:

• Full account (default — do nothing) — adds the online Marketplace (premium Power Combos), account sync, and the Everywhere relay (remote phone/tablet access). A free account is optional but unlocks those.
• Stand-alone — fully local, no account ever, zero network calls to our servers. Same core app (chat, Power Combos free tier, Workers, Tools) minus the three items above.

To get Stand-alone behavior: after setup, create an empty file at ~/scripts/cockpit_data/.edition_standalone (e.g. touch ~/scripts/cockpit_data/.edition_standalone). Its mere presence is the whole switch — auth.php checks for it before its one network call (an anonymous "first account created" ping), and it's your own reminder never to sign in. Delete that file any time to switch back to Full — nothing else about the install changes either way, and your chats/projects are untouched regardless.

What you need before starting

• Linux (Ubuntu/Mint or similar) or macOS, natively — or Windows via WSL2 (Ubuntu inside WSL2; the Windows host itself never runs the app directly).
• Apache2 + PHP (8.x) — the app is plain PHP, no Node/build step.
• tmux — used to run each AI CLI agent in its own persistent session.
• Optional, per Supplier Slot you plan to use: Ollama (local models), LocalAI v4.7.1 (local models, second engine — needed for Dual mode), a Claude/Codex/Qwen CLI subscription (Card 1), a free-tier key for Gemini or Groq (Card 2).

Linux / macOS — manual steps

1. Web files. Copy everything under web/ into your Apache document root for the app, e.g. /var/www/html/cockpit/. Set ownership so your normal user and the web server user (www-data on Debian/Ubuntu) can both read it; the app's PHP writes queue/session files under this tree at runtime, so it also needs to be writable by the web server user.
2. Scripts. Copy everything under scripts/ into ~/scripts/ in your own home directory (not the web server's), and make the .sh files executable (chmod +x ~/scripts/*.sh). These drive the tmux agent sessions and (Full account edition only) the Everywhere relay poller.
3. Apache. Point a vhost (or /cockpit alias on your default site) at the web root from step 1, with PHP enabled. Restart Apache.
4. Ollama (optional, for Card 3 / Power Combos): install per ollama.com's own instructions, then ollama pull whichever models you want available in the app.
5. LocalAI (optional, for Dual mode): download the release matching your platform from the v4.7.1 release page, verify its checksum, place the binary somewhere on your PATH, and set LOCALAI_MODELS_PATH / LOCALAI_DATA_PATH / LOCALAI_BACKENDS_PATH to directories of your choosing before starting it. See SETUP_GUIDE.html's LocalAI section (also in this zip) for exact commands and the current checksum, since that's the same source the scripted installer uses and stays accurate if the version changes.
6. Start the agent sessions. Run ~/scripts/cockpit_start.sh once per login. It launches the tmux sessions the app drives (Claude/Codex/Qwen, Gemini/Groq, Ollama) and starts the Everywhere relay poller automatically (it no-ops safely if you haven't signed in, don't have Everywhere on your account, or created the Stand-alone flag file above).
7. First open. Visit the app in a browser (http://localhost/cockpit/ or your vhost's URL). If no users.json exists yet, the app's own first-run screen creates your local login. Full account edition: SaaS sign-in/registration is separate and optional, from the Account tab inside the app.

Windows — manual steps

Windows always goes through WSL2 — there is no native Windows install of the app itself, only of the setup tooling around it.

1. Enable WSL2 and install an Ubuntu distro, if you haven't already (wsl --install -d Ubuntu-24.04 from an elevated PowerShell — or just run install_windows.ps1 from this zip, which automates this step plus VS Code + the Remote-WSL extension).
2. Open a terminal inside WSL2 (wsl, or VS Code's Remote-WSL). From there, follow the Linux / macOS — manual steps section above exactly — inside WSL2 you are running real Ubuntu, same as a native Linux machine.
3. The app is reached from your normal Windows browser at http://localhost/cockpit/ — WSL2 forwards that port to Windows automatically.

Note: this Windows/WSL2 path is written and reviewed but not yet verified end-to-end by our CI on a real Windows machine — if you hit something that doesn't match this guide, that's the most likely reason.

Other guides in this zip

• SETUP_GUIDE.html — the full walkthrough behind the scripted installer, step by step, all OSes. Useful even for a manual install as a reference for what each phase actually does.
• USER_GUIDE.html — the in-app feature walkthrough (also reachable from inside the app itself once running).