Run a Local Stack

TL;DR

Run npx zozohq@latest up on a personal macOS, Linux, or Windows machine to start a Local Stack. It runs agents as you with access to your files, stays on loopback, and stops when its terminal closes.

A Local Stack is a self-hosted Zozo Stack for one person on their own machine. Its Dashboard and services are reachable only from that machine, and its agents run as that person with access to that person's files and Runtime configuration. Use it for personal work on your own machine.

Requirements

• Node.js 22 or later
• macOS, Linux, or Windows 10 22H2 / 11 (Git for Windows on PATH)
• On Windows, Git for Windows on PATH and Windows long paths enabled (enable Enable Win32 long paths in Group Policy, or set LongPathsEnabled to 1 under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem and restart)
• GitHub CLI 2.94 or newer, if you will use the Dispatcher (optional)
• At least one Runtime login from claude auth login or codex login, or an API key that you add later in the Dashboard

Windows runs the Local Stack natively from PowerShell or Windows Terminal. WSL is a fallback if you prefer a Linux environment. On Windows, use a Claude Code login; the Codex Provider isn't supported there yet.

Start the Stack

Run the latest release without installing it globally:

npx zozohq@latest up

To keep the command installed, use:

npm i -g zozohq
zozo up

On the first run, Zozo asks you to acknowledge that agents run unrestricted as you, with your files and Runtime configuration. If the GitHub CLI is logged in, Zozo also offers to import the current gh login as the Stack's GitHub Credential. It then opens the Dashboard at Setup.

By default, zozo up keeps the terminal focused on setup and the Stack's status. Run zozo up --verbose (or zozo up -v) to include Server and Dispatcher logs when troubleshooting.

Keep the terminal open

The Local Stack and its work stop when the terminal running zozo up closes.

On Windows, the Dashboard token and secret files are protected by your user profile's permissions. Keep your profile private to your account.

Laptop Limitations

A Local Stack depends on the services available on your laptop:

• Prototype capture is unavailable without a system Chromium installation.
• Web Push and Stack Backup aren't available.
• Work stops when the zozo up terminal closes.

When you want an always-on Stack with managed browser notifications and backups, create a hosted Stack with Onramp.

Environments and Private Reach

Create an Environment in Settings to supply plain and secret Variables, then pin it to a Project. A saved Tailnet Key is unused on a Local Stack with the host Executor. Runs use your host's own network, including its Tailscale connection if configured; configure private access on the host.

Machine Configuration

Set ZOZO_GH_PATH to the GitHub CLI executable path when it is outside PATH. Zozo reads it at zozo up and passes it to the Dispatcher. ZOZO_CHROMIUM_PATH similarly selects the system Chromium executable.

Restart after installing GitHub CLI

Install GitHub CLI from cli.github.com, then run zozo up again so the Dispatcher can use the updated PATH. A pasted token stays unproven until the Dispatcher can check it with GitHub CLI.

Network Connections

A Local Stack contacts GitHub for repository and Issue work, the Runtime vendors for agent sessions, and the npm registry to check for a newer zozohq release. Set ZOZO_DISABLE_UPDATE_CHECK=1 to disable the npm update check:

ZOZO_DISABLE_UPDATE_CHECK=1 zozo up

In PowerShell:

$env:ZOZO_DISABLE_UPDATE_CHECK = "1"
zozo up