AI GO Hosted App — Deployment Guide

Hosted Apps (called "自訂 App" in the platform UI) let you deploy an application built on any technology stack to the AI GO platform: upload your source code, the platform automatically builds it into a container and runs it at its own URL, and the bundled credentials give it secure access to your AI GO tenant data.

This product line launched in Q3 2026; some advanced features are still being rolled out tenant by tenant.

1. How Hosted Apps differ from Custom Apps

They are parallel product lines — choose based on your needs:

How to choose: building an internal tool inside AI GO that works directly with ERP and custom tables → Custom App (see the Custom App Developer Guide). Bringing over an existing system, or needing technology the platform Builder doesn't support → Hosted App.

2. Prerequisites

• Paid plan: the free tier cannot create Hosted Apps (returns 403 hosted_app_requires_paid_plan).
• Permission: the operating account needs the hosted_apps.deploy permission (without it, the platform UI does not show the creation entry point).
• Creation entry point: platform Builder page "My Apps" → "自訂 App"; the detail page lives in the Dashboard's "AI Apps" section.

3. Quick start (CLI)

Install the aigo CLI (macOS Apple Silicon / Linux x86_64; on Windows, run it under Git Bash):

curl -fsSL https://raw.githubusercontent.com/AI-GO-APP/aigo-cli-releases/main/install.sh | bash

Deployment in three steps:

aigo login --token        # paste your Deploy Token (issued on the app detail page's Settings tab)
cd my-app                 # project root (.git / node_modules are excluded automatically when packing)
aigo hosted deploy --slug my-app

• If --slug matches an existing app, it redeploys (the URL is unchanged); otherwise it registers a new app (consuming a quota slot). Run aigo hosted list first to check.
• Build logs stream live; the state machine is queued → building → active | failed.
• aigo --help is the authority on command details (the CLI is released independently; this document does not duplicate its command surface).
• You can also deploy entirely through the REST API (POST /api/v1/hosted-apps to obtain upload information, then upload the tarball) — well suited to CI environments.

4. Application shape requirements

These are the most common causes of build and deployment failures — check each one before starting:

• Mainstream language frameworks are auto-detected; if the project contains a Dockerfile, the build follows the Dockerfile.
• Package sources reachable at build time are allowlisted (npm / PyPI / Docker Hub, etc.); private registries cannot be used.
• Apps default to scale-to-zero (scaled down to zero when idle, woken on traffic); enable always-on in settings if you need a resident process.

5. Environment variables

Set them on the detail page's "Environment Variables" tab or via PUT /api/v1/hosted-apps/{id}/runtime-settings:

• Key format ^[A-Z][A-Z0-9_]*$, ≤64 characters; at most 128 variables, ≤32 KiB per value, ≤128 KiB total (422 when exceeded).
• PORT, the K_ prefix, and the AIGO_ prefix are reserved by the platform and cannot be set.
• Each variable can be tagged "runtime / build-time / both" (rolling out from 2026-09). ⚠️ Build-time values are baked into the image and appear in build logs — tag secrets runtime-only.
• Changes take effect immediately; no rebuild is needed.

6. Accessing AI GO platform data

When a Hosted App is created, the platform automatically issues it a dedicated set of API credentials, injected into the container via environment variables only (they never appear in any API response):

AIGO_API_TOKEN         # Bearer token
AIGO_PLATFORM_API_URL  # platform API address (container-internal; use your tenant domain for local development)
AIGO_APP_ID / AIGO_TENANT_ID / AIGO_APP_URL / AIGO_ENV

Usage: call $AIGO_PLATFORM_API_URL/api/v1/open/... with Authorization: Bearer $AIGO_API_TOKEN.

⚠️ ERP tables start with zero authorization: a new app gets 403 on every ERP table call — first add data references on the detail page's "Data Access" tab and publish. Data Center custom tables, by contrast, are tenant-wide by default.

Credential management (on the detail page): re-issue (idempotent) / rotate (old and new overlap for 30 minutes) / revoke (immediate).

7. Internal apps and login handling

With visibility set to internal, access is restricted to tenant members and login is handled by the platform's proxy. The app has almost nothing to do — just one thing to get right:

• Page navigations are redirected to login automatically; background fetch/XHR instead receives 401 + JSON {"code": "hosted_app_auth_required", ...}.
• When the front end sees code === "hosted_app_auth_required", call window.location.reload() to trigger a top-level navigation — that is all. Do not redirect to the login_origin in the response yourself, and do not retry in a loop.
• Login sessions last 24 hours; platform cookies never reach your container, so there is nothing to handle.

8. Data persistence

Duplicating an app does not copy the persistent disk contents or the Deploy Token.

9. Custom domains

On the detail page's "Domains" tab (or POST /api/v1/hosted-apps/{id}/domains):

1. Add the domain → the platform returns the DNS records to configure
2. Configure them at your DNS provider
3. Verify → live once the certificate is issued (pending_dns → pending_cert → active)

Restrictions: nothing under the ai-go.app domain tree, no wildcards; the app must already have a running revision.

10. Management features and the REST API

The detail page provides: overview, deployment history, logs (build + runtime, with AI interpretation), file management and a web terminal on the live container (for debugging; writes are not persisted), domains, environment variables, data access, and settings (Deploy Token management).

The REST prefix is https://{tenant}.ai-go.app/api/v1/hosted-apps (login session). The day-to-day deployment surface (create, deploy, logs, restart, runtime-settings) also accepts a Deploy Token; the management surface (delete, duplicate, rename, domains, files / terminal, credentials) is login-session only — calling it with a Deploy Token returns 403, which is expected behavior.

11. Quotas and error reference