Run · local first

Run AI17Z on your own hardware.

Every installer checks the SHA-256 its release published, and stops if anything does not match.

Release details are unavailable right now — GitHub could not be reached. The commands below do not depend on this: each installer resolves the newest release itself and checks its SHA-256. See releases on GitHub.

Install

Pick your platform.

Install AI17Z only with the commands published here and in the canonical repository. Nowhere else distributes it.

Install on Windows

Open Windows Terminal and paste this. It checks the PC, installs what is missing, installs AI17Z, starts it and opens it.

Windows Terminal · PowerShell

irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install.ps1 | iex

Open Windows Terminal — no security setting is changed
Paste the command and press Enter
Follow what it tells you; it verifies the setup program’s SHA-256 before running it

See what it would do first

Dry run · changes nothing

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install.ps1))) -WhatIfOnly

More than one AI17Z on this PC

Several independent installations can live side by side; updating one leaves the others exactly as they are.

PowerShell

$s = irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install.ps1
& ([scriptblock]::Create($s)) -List                 # what is installed
& ([scriptblock]::Create($s)) -NewInstance          # install another
& ([scriptblock]::Create($s)) -Instance AI17Z-test  # update that one

Install on macOS

Download, read, and run the installer. Reading it first is the documented route.

Terminal · zsh

curl -fsSLO https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install-ai17z-macos.sh
less install-ai17z-macos.sh
bash install-ai17z-macos.sh

Download the installer
Read it with less
Run it — no sudo, ever, for AI17Z itself

Not signed with an Apple Developer ID and not notarized; Gatekeeper is never disabled. What that means.

Install on Ubuntu

Download, read, and run the installer as yourself. It installs a hash-checked .deb with apt.

bash

curl -fsSLO https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/install-ai17z-ubuntu.sh
less install-ai17z-ubuntu.sh
bash install-ai17z-ubuntu.sh

Download the installer
Read it with less
Run it; it asks for sudo only to install the package

Ubuntu Server works too — everything except browser-backed channels. Reach it through an SSH tunnel rather than exposing it.

Build from source

For people who work on AI17Z itself. Clone the official repository and install from the checkout, or let the bootstrap clone it.

macOS / Ubuntu · by hand

git clone https://github.com/ShiftAboveCtrl/ai17z.git ai17z
cd ai17z
./install-ai17z.sh --start

Windows · by hand

git clone https://github.com/ShiftAboveCtrl/ai17z.git ai17z
cd ai17z
.\install-ai17z.ps1 -Start

Bootstrap scripts

Windows · clones into .\ai17z

irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/bootstrap.ps1 | iex

Windows · read it first

irm https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/bootstrap.ps1 -OutFile bootstrap.ps1
notepad bootstrap.ps1
.\bootstrap.ps1

Ubuntu

curl -fsSL https://raw.githubusercontent.com/ShiftAboveCtrl/ai17z/main/bootstrap.sh | bash

No Git?

Download the ZIP from the repository (Code → Download ZIP), extract it and run the installer inside:

PowerShell

cd ai17z-main
.\install-ai17z.ps1 -Start

Not inside OneDrive, Dropbox or Google Drive: npm’s symlinks fail there with EBUSY.

Drive Docker yourself

For people who would rather run the stack by hand. A containerised worker has no browser, so it leaves browser-backed accounts alone — run a native worker on the machine with the browser for those.

With Docker

npm run setup          # writes .env with a master key, if there is not one
docker compose up -d

Without Docker · Node 22 + your own Postgres

npm install
npm run dev                   # api + worker + web

Web: http://localhost:8080
API: http://localhost:8787
Postgres: localhost:55432

Docker operations guide

Requirements

Docker: Docker Desktop — runs Postgres, the API and the interface
WSL 2: What Docker Desktop runs on (wsl --install)
Node 22: For the browser worker; fetched with winget if missing
Chrome: Only for browser-backed channels such as X
Git: Not needed

Verification

Installs only a release whose SHA-256 matches its published SHA256SUMS.txt
Runs the exact bytes it checked, from a folder you can read
Never asks you to disable SmartScreen, Defender or antivirus

Open http://localhost:8080
Create your owner account — it lives on this machine
Optional, later: link it to Studio

What the installer does

Short, public, and checked before it runs.

AI17Z is not code-signed on any platform. That is why the normal Windows path is a command rather than an executable, and why nobody will ever ask you to disable SmartScreen, Defender, Gatekeeper or your antivirus. Code signing policy.

Resolves the newest release
Asks GitHub for the newest published release of ShiftAboveCtrl/ai17z — pre-releases included — and refuses a tag that is not a version number.
Checks the hash first
Compares the download’s SHA-256 with the release’s SHA256SUMS.txt. A mismatch stops everything; nothing is replaced.
Runs the bytes it checked
Writes it somewhere you can read it and runs exactly those bytes. Your data directory and .env are never touched on update.

How to audit AI17Z Setup install.ps1 ↗macOS installer ↗Ubuntu installer ↗

Living with it

Launch, doctor, update, stop, restart.

Run these from the installation folder. Each reads the port from its own .env, so two installations never cross.

Lifecycle commands
Task	Windows	macOS / Ubuntu
Open it Starts everything and opens the app.	`.\launch-ai17z.ps1`	`./launch-ai17z.sh`
Diagnose Tells working, not set up yet, and broken apart.	`.\doctor-ai17z.ps1`	`./doctor-ai17z.sh`
Check for an update Shows what an update would bring; changes nothing.	`.\update-ai17z.ps1 -Check`	`./update-ai17z.sh --check`
Update Hash-checked; your data and .env are never touched.	`.\update-ai17z.ps1`	`./update-ai17z.sh`
Stop Data survives. --volumes deletes it, after asking.	`.\stop-ai17z.ps1`	`./stop-ai17z.sh`
Restart Your signed-in Chrome survives a restart.	`.\restart-ai17z.ps1`	`./restart-ai17z.sh`

AI17Z tells you about new versions on the Version panel in Settings and never updates itself. The older full Windows installer (AI17Z-Setup-<version>.exe) remains on the releases page for installations made with it; you do not need it.

Troubleshooting

When something is off.

“Docker is installed but not running.”

Start Docker Desktop, wait for it to settle, then run the start script again.

Ports already in use

Something else has 8080, 8787 or 55432. Set AI17Z_WEB_PORT, AI17Z_API_PORT or POSTGRES_PORT in .env.

“Google Chrome not found.”

Install Google Chrome. Chromium and Edge are different browsers and are not used as substitutes.

EBUSY: resource busy or locked, symlink

The folder is inside OneDrive, Dropbox or another syncing folder. Install somewhere that is not synced.

An X account will not connect

Connecting opens a real Chrome window; finish any code, CAPTCHA or unusual-login check yourself. AI17Z never answers a security challenge.

The agent runs but never replies

Open the agent’s Activity. Every decision is recorded, including the decision not to answer and why.

Something is wrong and you cannot tell what

Run the doctor.

Linking an installation to a Studio account is optional and comes later — AI17Z works fully without Studio. Link an installation.

Run AI17Z on your own hardware.

Install on Windows

Install on macOS

Install on Ubuntu

Build from source

Drive Docker yourself

Resolves the newest release

Checks the hash first

Runs the bytes it checked