---
title: "Hosted App Deployment Guide"
description: "Explains how to deploy applications of any tech stack as AI GO Hosted Apps: CLI and API deployment flows, environment variables, platform data access, custom domains, and quotas."
canonical: "https://www.ai-go.app/en-US/docs/hosted-app"
locale: "en-US"
last_updated: "2026-09-01"
source: "AI GO（https://www.ai-go.app）"
---

# 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.

---

## Table of Contents

1. [How Hosted Apps differ from Custom Apps](#1-how-hosted-apps-differ-from-custom-apps)
2. [Prerequisites](#2-prerequisites)
3. [Quick start (CLI)](#3-quick-start-cli)
4. [Application shape requirements](#4-application-shape-requirements)
5. [Environment variables](#5-environment-variables)
6. [Accessing AI GO platform data](#6-accessing-ai-go-platform-data)
7. [Internal apps and login handling](#7-internal-apps-and-login-handling)
8. [Data persistence](#8-data-persistence)
9. [Custom domains](#9-custom-domains)
10. [Management features and the REST API](#10-management-features-and-the-rest-api)
11. [Quotas and error reference](#11-quotas-and-error-reference)

---

## 1. How Hosted Apps differ from Custom Apps

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

| | Custom App | Hosted App |
|---|---|---|
| Development | Inside the platform Builder (React + TypeScript + Python actions) | Locally, in any language / framework |
| Artifact | A micro-app inside the platform (Shadow DOM) | A containerized standalone application |
| URL | Inside the platform | `https://{slug}.deploy.ai-go.app` (custom domains supported) |
| Build | Compiled by the platform | Container built with automatic language detection (no Dockerfile required) |
| Platform data access | Built-in SDKs (`db.ts` / `ctx`) | Injected API credentials + REST |
| Best for | Business interfaces inside the platform, deep use of tenant data | Migrating an existing service; needing long-running processes / WebSocket / your own framework |

**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):

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

Deployment in three steps:

```bash
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:

| Requirement | Symptom when violated |
|---|---|
| Open a **single HTTP port** only | Build pre-check warning, rollout failure |
| Listen on the **`$PORT`** environment variable, bind **`0.0.0.0`** | `connection refused`, failed health checks |
| **Single foreground process** (no supervisord / pm2 / multi-service compose) | Blocked by pre-check |
| **Commit your lockfile** (package-lock.yaml / go.sum, etc.) | `frozen-lockfile`-style errors |
| Build resource limits: 2 CPU / 4 GiB, 900 seconds by default | `OOMKilled` / `exit code 137` / timeout |
| No monorepos or empty directories | Blocked by pre-check; an unrecognizable directory is deployed as a static site |

- 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

| Location | Persistent? |
|---|---|
| Container filesystem | ❌ Gone on redeploy / restart / scale-to-zero |
| Persistent disk `/data` (once enabled in settings; `AIGO_DATA_DIR` points to it) | ✅ 10 GiB, retained across deployments |
| Platform data (written via the `/open` API) | ✅ |

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

| Error | Meaning | Remedy |
|---|---|---|
| 403 `hosted_app_requires_paid_plan` | Free plan | Upgrade the plan; retrying won't help |
| 429 `hosted_app_quota_exceeded` | Per-tenant app count limit reached | Delete unused apps (this frees slots) or contact the platform for an adjustment |
| 422 | Environment variable / parameter out of bounds | Fix per the message |
| 503 (build pipeline not ready) | Transient platform-side state | Retry later |
| Deployment `failed` | Build or startup failure | Read the build logs; check against the shape requirements in Chapter 4 |
| 403 (management endpoint) | A Deploy Token was used | Switch to a login session |