AityUahn — Test & Launch Guide

Complete reference for how AityUahn works, how to launch it, and how to verify every layer. Version 0.2.1.

How it works

AityUahn has three layers that can run in different places:

Browser UI — GitHub Pages or aityuahn serve (landing, controller, docs)
Local forge API — aityuahn serve on port 8765 (role: forge): kanban, ideas, backlogs, agents, files on disk
Cloud SaaS API — Vercel + Neon (role: saas): sign-in, teams, TON billing

Browser  ──forge──►  http://127.0.0.1:8765     (your PC)
Browser  ──auth──►  https://YOUR-APP.vercel.app  (defaultSaasApi)

Controller header pills: Forge live + optional cloud v…. Never paste the Vercel URL into the forge field.

Launch paths

A — One-line install

PowerShell:

irm https://raw.githubusercontent.com/HyperlinksSpace/AityUahn/main/scripts/install.ps1 | iex

Git Bash:

curl -LsSf https://raw.githubusercontent.com/HyperlinksSpace/AityUahn/main/scripts/install.sh | sh

Then: cd ~/AityUahn (or %USERPROFILE%\AityUahn) → serve.bat or aityuahn serve.

B — Windows .exe

Download aityuahn-installer.exe (requires Python 3.11+).

C — Developer clone

git clone https://github.com/HyperlinksSpace/AityUahn.git
cd AityUahn
python -m venv .venv && source .venv/Scripts/activate
pip install -e ".[dev]"
cp config/forge.example.yaml forge.yaml && cp .env.example .env
aityuahn serve --demo

Step-by-step launch

Edit forge.yaml — set workspace_root
Run aityuahn serve --demo — keep terminal open
Open Controller at http://127.0.0.1:8765/controller.html
Paste http://127.0.0.1:8765 → Connect → Forge live
Optional cloud: deploy Vercel, set defaultSaasApi in config, rebuild Pages

Verify setup

curl http://127.0.0.1:8765/api/health
aityuahn verify
aityuahn doctor
aityuahn version
bash scripts/verify_setup.sh          # Git Bash
.\scripts\verify_setup.ps1            # PowerShell

Expected forge health: "ok": true, "role": "forge", "version": "0.2.1".

With cloud: SAAS_URL=https://YOUR-APP.vercel.app bash scripts/verify_setup.sh

Testing checklist (summary)

Layer	Quick test	Pass
CLI	`aityuahn version`	prints version
Forge	`curl …/api/health`	role=forge, ok=true
UI	Connect in controller	Forge live pill
Kanban	Move a task	No error
Demo	`?demo=1`	Works without API
Cloud	`curl …/api/health` on Vercel	role=saas, ok=true
Auth	Register on landing	Token returned
Dev	`pytest -q`	All green

Full 22-item checklist: TEST_AND_LAUNCH.md §5

Windows notes

Use PowerShell for irm | iex — not Git Bash
Use Git Bash for curl | sh install script
Activate venv: source .venv/Scripts/activate (Bash) or .\.venv\Scripts\Activate.ps1 (PS)
From GitHub Pages, localhost is not reachable — open UI from aityuahn serve or use a tunnel

Troubleshooting

Problem	Fix
Connect fails from Pages	Use UI from `aityuahn serve` or ngrok tunnel
“Expected forge… got saas”	Forge URL must be `:8765`, not Vercel
Cloud pill shows issues	Set `DATABASE_URL` + `AITYUAHN_JWT_SECRET` on Vercel
Sign-in 405 on Pages	Set `defaultSaasApi` in config.json
`doctor` forge fail	Start `aityuahn serve`

More docs

HOW_IT_WORKS.md — architecture deep-dive
TEST_AND_LAUNCH.md — full markdown guide (22-item checklist)
DEPLOY_VERCEL.md — Vercel + Neon
INSTALL_RELEASE.md — Windows exe releases
Setup docs — install, configure, run