Sign inSign up

aitiai/pi-web

By aitiai

•Updated about 19 hours ago

AITI Web — browser workbench for the pi coding agent (core / full Docker images)

Image
0

1.9K

aitiai/pi-web repository overview

⁠AITI Web — official Docker images (core / full)

English | 中文⁠ | 日本語⁠ | Русский⁠

AITI Web (@aiti-ai/pi-web) is a browser workbench for the pi coding agent⁠. It is a fork of upstream pi-web⁠ that grew into its own distribution — aiti — built for real daily use: 63+ bundled extensions (sessions & queues, git toolchain, page-injected debugging, multi-agent backends, tunnels, voice) with zero per-extension installs, while the engine stays pi (shared JSONL sessions, same local configuration).

This image is the fastest way to run all of it: pi-web + every bundled extension + the pi engine + Node/git + the aiti-bridge in one container; full adds a web desktop (noVNC, Chrome/CDP), speech and tunnels on top. The story behind the fork: aiti.pw/guide/origin.html⁠.

Docs: aiti.pw⁠ (EN / 中文) · Source: aiti-ai/aiti-ai⁠ · Prefer npm? npm i -g @aiti-ai/pi-web · License: MIT⁠


⁠Usage manual

Images: aitiai/pi-web:core (base, 2.13GB) / aitiai/pi-web:full (all-in-one, 7.76GB).

⁠1. Quick start

# Base image: open http://localhost:30144 for the full workbench
docker run -d --name aiti --init \
  -p 30144:30142 \
  -v aiti_data:/opt/aiti/data \
  -v aiti_agent:/opt/aiti/agent \
  -v ~/my-project:/workspace \
  aitiai/pi-web:core
  • First launch: sidebar "Select project → Use default directory" (= /workspace) → "New session" → "Settings" at the bottom to configure a model key → chat.
  • Data lives in two volumes: aiti_data (extension runtime data) and aiti_agent (pi sessions / model config) — upgrading the image keeps your data.
  • ⚠ Mount only sub-paths of /opt/aiti, never the whole /opt/aiti: a named volume is populated once, so mounting the root would make image upgrades ineffective forever (see test report O22).

⁠2. Choosing an image

corefull
Size2.13GB7.76GB
pi-web + bundled extensions + pi engine + justget + bridge✅✅
GUI (Xvfb/VNC/noVNC/Chrome+CDP)—✅
ASR speech recognition (funasr, four models, :8767)—✅
TTS edge-tts / web terminal ttyd (:7681)—✅
Tunnels cloudflared/ngrok/frpc—✅
Memory floor1GB8GB (full + voice; 2–6GB OOMs)

full's extra phases are controlled with AITI_PHASES (see §4).

⁠3. Ports

PortServiceDefault
30142pi-web main UImust map
8777aiti-bridge (page injection / MCP / agent REST)map when using external agents / injection
8767ASR WS/HTTP (full)on by default in full; map as needed
6080noVNC web desktop (full)loopback, map as needed
5900VNC (full)loopback
9222Chrome CDP (full)loopback
7681ttyd web terminal (full)loopback

AITI_PIWEB_PORT / AITI_BRIDGE_PORT change the container-side ports (rarely needed).

⁠4. Environment variables

VariableDefaultMeaning
AITI_PHASESpiweb,bridgeComma-separated: piweb,bridge,gui,asr,term. gui/asr/term are implemented in full only (core logs and skips them)
PUID/PGID1000Runtime uid/gid (align with the host user so mounted directories just work). ⚠ Do not use UID (read-only bash builtin)
TZUTCe.g. Asia/Shanghai
AITI_PIWEB_PORT / AITI_BRIDGE_PORT30142 / 8777Container-side ports; HEALTHCHECK follows automatically
AITI_MODEautocore/full/auto (per image-layer marker); setting core on a full image downgrades to the base phases
AITI_DEV01 = mount sources and run next dev with hot reload (development mode)
AITI_SKIP_CHOWN01 = skip root initialization when starting directly with --user
AITI_GUI_NOFILE65536GUI session fd limit (do not raise — a large NOFILE deadlocks x11vnc, test report O20)
AITI_GUI_SIZE1920x1080x24Virtual display resolution
⁠Domain / reverse-proxy (same semantics as pi-web)
VariableMeaning
PI_WEB_ALLOWED_HOSTSTrusted hostnames (comma-separated) — reverse-proxy domains must be listed or requests 403. Unlisted hosts stay rejected (the Host gate remains)
PI_WEB_BASE_DOMAINDomain used to build service-tunnels expose URLs (host:port)
AITI_BASE_URLPublic base URL for aiti-devtools injection pages / MCP (set to your proxy URL)
API_ALLOW_ORIGINSBridge CORS (* or explicit origins; needed when the proxy domain differs from the served origin)
PI_WEB_EXTRA_EXTENSIONS_DIRSExtra extension directories (container paths, comma-separated; pair with -v mounts for user extensions)

Reverse-proxy example (domain → 127.0.0.1:30144, bridge → 18777):

docker run -d --name aiti --init \
  -p 127.0.0.1:30144:30142 -p 127.0.0.1:18777:8777 \
  -e PI_WEB_ALLOWED_HOSTS="pi.example.com,aiti.pi.example.com" \
  -e PI_WEB_BASE_DOMAIN="pi.example.com:8443" \
  -e AITI_BASE_URL="https://aiti.pi.example.com:8443" \
  -e API_ALLOW_ORIGINS="*" \
  -v aiti_data:/opt/aiti/data -v aiti_agent:/opt/aiti/agent \
  aitiai/pi-web:core

Measured behavior (test reports T-E/T-H): listed Hosts answer 200, unlisted 403; adding subdomains under a *.pi.example.com wildcard + wildcard certificate needs no extra work.

⁠5. Volumes & persistence

MountContentsRecommendation
/opt/aiti/dataExtension runtime data (config store / indexes / caches)Named volume
/opt/aiti/agentpi session JSONL / models.json / mcp-cacheNamed volume (the moat — always persist)
/workspaceWorkspace (default cwd at startup; pi sessions group by project)Bind-mount a host project directory
/home/aiti/.piOptional: inherit host pi configAdopts auth.json/models.json on first run; settings.json is jq-merged with the built-in defaults (user keys win, packages union)
/opt/aiti/extensionsExtension codeDo not mount — owned by the image layer; upgrading refreshes it

⁠6. full-image features at a glance

FeatureEntry point
Web desktopnoVNC :6080/vnc.html (RFB via websockify→x11vnc→Xvfb :99)
CDP debuggingChrome :9222 (headful, --user-data-dir=/opt/aiti/data/chrome-profile)
Voice inputASR ws://<host>:8767/ws/stream (realtime) / /voice/quick (quick) / /voice/transcribe (refined) / /ws/vad (segmentation) — the aiti-ai-input extension wires up automatically via AITI_ASR_STREAM_BASE
Voice readoutedge-tts installed; enable the tts.edge feature in the aiti-ai-speek extension
Web terminalttyd :7681
Tunnelscloudflared / ngrok / frpc usable inside the container (ngrok needs your own authtoken)
Download tooljustget <url> -o <file> -m <mirror-url> multi-source racing

⁠7. Operations

docker logs -f aiti                 # logs (extension readiness / bridge / banner all here)
docker exec -it aiti bash           # into the container (user aiti, passwordless sudo)
docker stats aiti                   # resources
docker inspect aiti --format '{{.State.Health.Status}}'   # healthy = OK
docker stop aiti && docker rm aiti  # stop & remove (volumes kept)
docker volume rm aiti_data aiti_agent   # remove the data too (careful)
  • Graceful stop: docker stop exits within ~1s (signals are forwarded to each service by the entrypoint).
  • Upgrading: docker pull the new image, then remove and recreate the container (same-name volumes carry the data); extensions refresh with the image.
  • Rebuild + smoke: ./docker/scripts/rebuild-and-smoke.sh core full (CI-ready; exit code = number of failures).

⁠8. Building & publishing (maintainers)

# Non-CN network / GitHub CI: official mirrors directly
./docker/build.sh --target core --tag aitiai/pi-web:core
./docker/build.sh --target full --tag aitiai/pi-web:full     # requires core first

# CN local builds: --cn injects mirrors (apt=tuna / npm=npmmirror / hf=hf-mirror / pypi=tuna)
./docker/build.sh --target core --tag aitiai/pi-web:core --cn
# Equivalent env: AITI_CN=1 (pre-set in the systemd unit template)

./docker/scripts/smoke.sh full [--keep]                  # 22-check smoke suite (exit = failure count)
node docker/scripts/e2e-ui.mjs                           # UI journey E2E (needs playwright-core + chromium)
node docker/scripts/gen-deps.mjs                         # S3 dependency matrix (reads extension `aiti` metadata blocks)

--cn only affects public-source mirrors; the @aiti-ai/* private registry is a separate temporary channel: --private-registry <private-registry-url> (or env AITI_PRIVATE_REGISTRY) — for local testing only. Once @aiti-ai/* is on public npm, omit it and the official registry is used. Same at runtime: docker run -e AITI_NPM_REGISTRY=<private-registry-url> lets pi pull private packages on first boot (written into the in-container ~/.npmrc). Known limitations (see the test report's remaining-issues section): arm64 has no official Chrome (CDP missing; all other download layers ready); ngrok/frpc downloads occasionally need retries (the build carries a gh-mirror racing fallback); UI E2E depends on host chromium.

⁠9. Troubleshooting

SymptomCause / fix
Container restart-loopingdocker logs for the first error; usually port conflicts / volume permissions (align PUID)
Reverse proxy 403Domain not in PI_WEB_ALLOWED_HOSTS
/api/models 403Normal — it only allows existing session cwds; the health check uses /api/home
x11vnc connects but no picture / very slowNOFILE deadlock (O20) — confirm AITI_GUI_NOFILE was not raised and use the image's own 50-gui-start
CDP 9222 unreachableConfirm --user-data-dir is among the flags (Chrome 136+ ignores CDP on the default profile) + first-run EULA skipped
ASR first response slowModels are not baked into the image — the first voice turn downloads them automatically (modelscope, cached in /opt/aiti-asr/models; switching models downloads incrementally)
OOMfull + voice needs ≥8GB memory (2–6GB OOMs in practice, test report T-H5)

Tag summary

Content type

Image

Digest

sha256:b1961579f…

Size

1.3 GB

Last updated

about 19 hours ago

docker pull aitiai/pi-web