Quick start

AityUahn forges projects from prompts: idea → backlog → scaffold. Use the Controller for kanban, tasks, forge, and agents.

The web UI can run on GitHub Pages, but forge, agents, sign-in, and team billing require the Python backend (aityuahn serve). Follow the steps below to download it, run it, and verify everything works.

Full guide: Test & Launch Guide (browse) · markdown

How it works

AityUahn splits into local forge (your PC) and cloud SaaS (Vercel + Neon):

• Local forge — aityuahn serve on port 8765: kanban, ideas, backlogs, agents, project files on disk.
• Cloud SaaS — Vercel URL from defaultSaasApi: register, sign-in, team projects, TON billing. Data in Neon Postgres.
• Static UI — GitHub Pages or the same HTML from aityuahn serve; connects to both APIs.

Controller header pills: Forge live (local) and cloud v… (SaaS health). Do not paste the Vercel URL into the forge field — use http://127.0.0.1:8765.

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

Launch checklist (summary)

1. Install — one-line script, .exe, or git clone + pip install -e ".[dev]"
2. Configure — forge.yaml, optional .env API keys
3. Run — aityuahn serve --demo
4. Verify — curl http://127.0.0.1:8765/api/health and aityuahn doctor
5. Connect — Controller → paste forge URL → Forge live
6. Cloud (optional) — deploy SaaS, set defaultSaasApi, rebuild Pages

See the full testing checklist (CLI, UI, SaaS, CI).

Download the local forge (Windows)

The local forge runs on your PC (aityuahn serve). Cloud sign-in/billing is separate on Vercel — see the Vercel deploy guide.

• Download installer (.exe)
• All releases
• Download ZIP
• Repository

Stable download URL (always points at the newest build):

https://github.com/HyperlinksSpace/AityUahn/releases/latest/download/aityuahn-installer.exe

Releases page (version history, build notes):

https://github.com/HyperlinksSpace/AityUahn/releases

Every push to main that touches the forge code triggers .github/workflows/release-installer.yml, which builds aityuahn-installer.exe on GitHub Actions and publishes a new GitHub Release (same pattern as HyperlinksSpaceProgram).

The installer requires Python 3.11+ already installed on Windows. It clones the repo to %USERPROFILE%\AityUahn, creates a venv, and adds serve.bat.

One-line install

Same pattern as other tools — paste in a terminal. Works on Windows via PowerShell; Git Bash uses the shell script.

Windows (PowerShell) — run as your user (not necessarily admin):

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

Git Bash / WSL / macOS / Linux:

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

Default install folder: %USERPROFILE%\AityUahn on Windows, ~/AityUahn elsewhere. Override with AITYUAHN_INSTALL_DIR (env var).

After install, start the API:

cd %USERPROFILE%\AityUahn
serve.bat
# or:  aityuahn serve

Manual release build (maintainers): pip install -e ".[installer]" then python scripts/build_installer.py → dist/aityuahn-installer.exe.

Or clone with Git:

git clone https://github.com/HyperlinksSpace/AityUahn.git
cd AityUahn

After extracting or cloning, open a terminal in the AityUahn folder for the next steps.

Prerequisites

• Python 3.11+ — check with python --version
• Git (optional, for clone) and a terminal — Git Bash, PowerShell, or WSL on Windows
• API keys (optional for first run) — Claude/Cursor keys in .env for AI forge and agents

Install

Create a virtual environment and install AityUahn in editable mode:

cd AityUahn
python -m venv .venv

Activate (pick your shell):

# Git Bash / Linux / macOS
source .venv/Scripts/activate   # Windows Git Bash
source .venv/bin/activate         # Linux / macOS

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install -e ".[dev]"

Confirm the CLI is available:

aityuahn --help
aityuahn init

Configure

cp config/forge.example.yaml forge.yaml
cp .env.example .env

Edit forge.yaml:

• Set workspace_root to the parent folder where forged projects should appear (e.g. C:/1/1/1/1/1 on Windows).
• Enable providers and set api_key_env names.

Edit .env and add keys for enabled providers (never commit .env):

ANTHROPIC_API_KEY=sk-ant-...
CURSOR_API_KEY=crsr_...

Sign-up and team features work without AI keys; forge and agents need at least one configured provider.

Run the backend

aityuahn serve

Default URLs (keep this terminal open while testing):

• Landing: http://127.0.0.1:8765/
• Controller: http://127.0.0.1:8765/controller.html
• API health: http://127.0.0.1:8765/api/health
• OpenAPI: http://127.0.0.1:8765/docs

Seed sample kanban data on first run:

aityuahn serve --demo

Use a different port if 8765 is taken: aityuahn serve --port 9000 — then use that port in the controller.

Verify the backend is running

In a second terminal (with the server still running):

curl http://127.0.0.1:8765/api/health
aityuahn doctor
aityuahn version

Forge health should include "ok": true, "role": "forge", and "version". Cloud SaaS (if deployed) returns "role": "saas" — see DEPLOY_VERCEL.md.

Then connect the controller:

1. Open Controller (local serve URL or GitHub Pages).
2. Paste http://127.0.0.1:8765 into Local forge API.
3. Click Connect — status should show Forge live (and a cloud pill if defaultSaasApi is set).

From GitHub Pages (hyperlinksspace.github.io/AityUahn), the UI cannot reach 127.0.0.1 on your PC unless you use a tunnel (Cloudflare Tunnel, ngrok) and paste the public HTTPS URL instead.

Test the program (UI)

1. Offline demo (no backend)

Open Controller · demo mode or click Offline demo. You should see sample kanban tasks. Drag tasks, switch views — forge and agents stay disabled until you connect a live API.

2. Live dashboard

With aityuahn serve --demo running and connected:

• Kanban — change task status on the demo project.
• Task list — add a task, mark it done.
• Forge & backlog — refresh backlog; run tests (needs a forged project with tests).
• Agents — send a prompt (requires API keys in .env).
• Team & API — register, sign in, create a team project (runs on the same backend).

3. Full forge (CLI smoke test)

aityuahn forge "A tiny hello-world CLI that prints the current time"
aityuahn list
aityuahn backlog my-project

Requires a working AI provider in forge.yaml + .env.

Test AityUahn itself (developers)

pip install -e ".[dev]"
pytest -q
ruff check python tests

Docker (optional)

cp config/forge.example.yaml config/forge.yaml
docker compose --profile cli build
docker compose --profile cli run --rm aityuahn list

See the repository README for volume mounts and cloud deployment.

Controller views

• Kanban — move tasks across backlog, in progress, review, blocked, done
• Task list — add tasks, change status
• Forge & backlog — full forge, AI backlog, run tests
• Agents — send prompts to configured providers

CLI reference (same backend)

aityuahn forge "A tiny HTTP service for embeddings"
aityuahn backlog my-project --generate
aityuahn task my-project add "Add CI"
aityuahn task my-project done --id T-xxxxxxxx
aityuahn test my-project

Configuration

Edit forge.yaml for workspace path, AI providers (Claude, Cursor, Ollama, etc.), and role routing. API keys go in .env — never commit secrets.

Repository & guides

• github.com/HyperlinksSpace/AityUahn
• Test & Launch Guide (browse)
• TEST_AND_LAUNCH.md
• Deploy SaaS to Vercel + Neon
• Windows installer releases
• README