Docs
Contents

Sites

Sites is a fully managed frontend and full-stack web application hosting service provided by Agentbase, supporting mainstream frameworks such as Next.js, SvelteKit, React, Vue, Nuxt, and Astro. With Sites, development teams can clone directly from official templates, connect GitHub repositories, or manually upload .tar.gz source packages to complete automated cloud builds and deployments, and within the same project context manage multi-version deployments, one-click rollback, build and runtime logs, custom domain SSL certificates, and site-level environment variables.

Feature Overview

When building enterprise customer service portals, internal knowledge base retrieval sites, or agent conversation web frontends (such as the frontend portal of project 企业智能客服与知识中台 enterprise-ai-hub-210), traditional approaches require separately purchasing static hosting or container clusters, individually configuring CI/CD build pipelines, manually applying for HTTPS certificates, and configuring cross-origin whitelists.

Agentbase Sites deeply integrates frontend/full-stack application hosting within the Project resource boundary, providing four core capabilities:

  1. Three access sources with framework-adaptive builds: Supports cloning from a curated template library, connecting a GitHub repository (automatically detecting branches and commits), or manually dragging and uploading a .tar.gz source package, automatically matching build commands and output directories for frameworks such as Next.js and SvelteKit.

  2. Zero-downtime deployment and one-click Instant Rollback: Each build generates an independent Deployment version; from the site overview page, Instant rollback allows you to switch back with one click to any previously activated historical stable version whose status is ready.

  3. Dual-layer security admission and restricted identity execution: Controlled by a dual gate consisting of the instance-level switch _APP_SITES_ENABLED and the capability email allowlist; build and SSR runtime identity and network restrictions depend on the executor and deployment configuration.

  4. Custom domain automation and same-origin context injection: Preview domains are automatically assigned and enterprise custom domains can be bound (with automatic SSL certificate issuance); project-level Global variables and site-specific environment variables are automatically injected at build and runtime.

Core management dimensionConsole tab locationCore feature characteristicsRisks and security boundaries
Site overview and quick rollbackOverviewView the current active deployment, click Visit to access the live site, click Instant rollback for one-click rollbackOnly deployments already in ready status that were historically activated can serve as one-click rollback targets
Deployments pipelineDeploymentsCreate new deployments via Git (recommended) / CLI / Manual; supports Cancel / Redeploy / Delete and viewing build metricsAn additional high-risk warning appears when deleting the active deployment currently serving live traffic
Build and runtime logs (Logs)LogsView build output and SSR runtime logsOn build failure, inspect recorded output; logs may be truncated or missing due to the execution path
Domains and certificates (Domains)DomainsManage default subdomains, preview domains, and enterprise custom domains; view SSL certificate issuance status and support retry on failureCustom domains require DNS records to be pointed correctly before certificates can be successfully issued
Site settings and destruction (Settings)Settings · UsageModify build commands, Root/Output directories, site-level environment variables, compute specs, Timeout, and Danger zone site deletionDelete site permanently destroys the site and all its historical deployment records; this cannot be undone

Core Concepts and Architecture

1. Sites capability enablement conditions and email allowlist validation rules (key points)

Because frontend and full-stack site builds consume cloud build compute and public network egress resources, Agentbase enforces strict three-level admission control on the Sites module. Only when all three of the following conditions are met can a user create and deploy sites in a project:

Admission levelConfiguration item or validation dimensionDetailed rules and system behavior when not satisfied
Level One: instance deployment switch_APP_SITES_ENABLEDApplication code treats enabled as on and defaults to enabled when unset; other values, including disabled, do not enable it. A deployment may explicitly override this. The Console sidebar also checks the current user's email allowlist.
Level Two: capability email allowlistInstance-level Sites Email Allowlist• If the allowlist is empty: the Sites capability is disabled for all users (Fail-Closed);
• If the allowlist is non-empty: the system strictly verifies whether the email corresponding to the requester's identity is on the allowlist—including: ① the email of the user currently signed in to the Console session; ② the email of the user owning the account-level API Key; or ③ the confirmed (Confirmed) organization Owner email within the team owning the project/organization API Key.
• If the allowlist condition is not met, the request will fail immediately and return an explicit permission error.
Level Three: project write permissionsites.writeThe operating member must hold a write role (owner, admin, developer, or editor) in the organization the project belongs to; organization billing and analyst lack projects.read by default and cannot enter the project on those roles alone in self-hosted deployments.

2. Architectural division of labor: Sites versus Functions

Within the same project (e.g. enterprise-ai-hub-210), Sites and Functions use their configured executors and project global variables, but each plays a distinct architectural role:

Comparison dimensionSitesFunctions
Core positioningFrontend/full-stack web site hosting and domain delivery for end-user browsersEvent-driven, scheduled task, and API microservice computing for backend logic
Typical technology stacksNext.js, SvelteKit, React, Vue, Nuxt, static HTML/JS/CSS artifactsNode.js, Python, java-17.0 (supports prebuilt JARs), Go, PHP, Deno
Access and trigger methodsUsers directly access the site's subdomain or custom HTTPS domain via browserTriggered via SDK executions endpoints, internal database/storage Events, or Cron schedules
How they work togetherThe site frontend directly calls the same project's Auth, Databases, agent endpoints, and Functions via @alipay/agentbase-web-sdk@2.12.0 or agentbase-web-sdk@2.12.0Provides the site frontend with protected custom backend business logic, third-party Webhook callback handling, and asynchronous batch processing

Roles, Entry Points, and Relationships

1. Console navigation path and sub-tab structure

  1. List page entry: After entering the project Console, click Sites in the left navigation bar (path /console/project-{region}-{project}/sites). On the list page, press the keyboard shortcut C or click Create site in the top-right corner to launch the site creation wizard (/sites/create-site).

  2. Six tabs of the site details page (path prefix /console/project-{region}-{project}/sites/site-{site}):

    • Overview (.../site-{site}): Displays the current live active deployment card, the access link (Visit), the one-click rollback button (Instant rollback), and real-time build status indicators.

    • Deployments (.../deployments): Manages all historical and in-progress deployment versions; supports creating deployments, canceling builds, redeploying, and deleting deployments.

    • Logs (.../logs): View site build logs and runtime logs.

    • Domains (.../domains): Manage site custom domains, preview domains, and SSL certificate issuance status.

    • Usage (.../usage): View request and bandwidth consumption trends for the site.

    • Settings (.../settings): Maintain the site name, Git repository binding, build commands, runtime specs, site-level environment variables, timeout, log toggles, and site deletion (Danger zone).

2. Relationship with project Global Variables and Platforms

Feature Details and Operation Guide

1. Creating and deploying your first site (three access methods explained)

On the Sites list page, click Create site (or press the shortcut C), then choose one of the following paths depending on how your team manages code:

  1. Select Connect Git repository. If the current project is not yet linked to a GitHub App, follow the on-screen guidance to complete GitHub authorization and installation first (connections can also be managed in the project's Settings → Git).

  2. Select the target frontend code repository and production branch (e.g. main) from the authorized list, then click to enter the Deploy site (deployment configuration) page.

Method Two: Clone from Official Templates (Clone Template, quick start)

  1. Select Clone template. The template library supports filtering by Use case (business scenario, e.g. AI Chat, Starter, Dashboard) or Framework (frontend framework, e.g. Next.js, SvelteKit, Vue).

  2. After selecting a template, you enter the deployment configuration page, where the system automatically fills in the full set of build commands and environment variables required by the template.

Method Three: Manual Upload (Manual Upload, offline/intranet delivery)

  1. Select Manual, package your local frontend project source code into a .tar.gz format archive (package size is constrained by the current plan and instance configuration limits), then drag and drop or select the file to upload and enter the deployment configuration page.

Filling In the Deployment Configuration Parameters Table (Deploy Site)

In the deployment configuration wizard, verify the parameters and submit according to the 6 sections from top to bottom:

Configuration sectionCore field nameDefault value / format constraintFilling instructions and production recommendations
1. Details (basic information)Name / Site ID ($id) / Framework / execution planFramework is auto-detected or selected manually from a dropdownFor example, enter the name 企业智能客服Web工作台, set a custom Site ID of enterprise-support-portal, and choose framework Next.js or SvelteKit.
2. Git configurationRoot directoryDefault ./If the frontend project is in a subdirectory of a Monorepo repository (e.g. ./apps/web-portal), enter the relative subdirectory path here.
3. Build configurationInstall commandDefault npm installDependency installation command (if using pnpm or yarn, change to pnpm install / yarn install).
Build commandDefault npm run buildProduction build command; runtime identity depends on the executor and deployment configuration.
Output directoryDefault dist (automatically adjusted per framework preset)Build artifact output directory (e.g. typically dist for Vite/Vue; Next.js/SvelteKit follow their respective adapter directories).
4. Environment variablesKey-value pair list (Key / Value)Supports pre-filling from the repository or manual additionFor example, enter PUBLIC_AGENTBASE_ENDPOINT=<APPBASE_ENDPOINT_WITH_V1> and PUBLIC_AGENTBASE_PROJECT_ID=<APPBASE_PROJECT_ID>.
5. Domain (site domain)Subdomain (site subdomain)Globally unique valid subdomain prefixThe default access subdomain assigned to the site by the system.
6. Submit buildDeploy buttonAfter submission, automatically redirects to the build waiting pageThe waiting page refreshes progress in real time until the build is complete; once ready, click Visit to access the site.

2. Daily Releases, Status Monitoring, and One-Click Instant Rollback

  1. Trigger a new version deployment:

    • Switch to the Deployments tab on the site details page and click Create deployment.

    • You can choose Git (recommended, pulls the latest branch commit for building), CLI (publish via command-line tool), or Manual (upload a new .tar.gz package).

  2. Handling the configuration-change-not-applied notice:

    • After you modify the build command, Output directory, runtime spec, or site environment variables on the site Settings page, the previous active deployment does not change automatically; a prominent yellow warning banner appears at the top of the page. Simply click the Redeploy button on the banner to rebuild and go live based on the new configuration.

  3. Perform an emergency rollback in production (two methods):

    • Method A (Instant rollback on the Overview page): when a newly deployed version shows a frontend white screen or style issues, go to the site Overview tab and click Instant rollback directly on the current active deployment card (this button is only available when an old deployment with status ready exists that has been activated before), switching back to the previous stable version in one click.

    • Method B (precise switching in the Deployments list): go to the Deployments tab, find the target deployment version with status ready in the history list, and click activate to set it as the current active deployment.

  4. Canceling and deleting deployments:

    • For tasks currently building, click Cancel to terminate; for historical deployments no longer needed, click Delete to clean up (deletion is irreversible; if you attempt to delete the currently serving active deployment, an additional high-risk confirmation prompt appears).

3. Binding a Custom Domain and Managing Site Settings

  1. Bind a custom domain (Domains tab):

    • Go to the site details Domains tab and click to add a custom domain (e.g. chat.enterprise.example.com).

    • Configure the pointing records in your enterprise DNS as prompted by the interface, and monitor the SSL certificate status in the domain list; if certificate generation fails (Certificate generation failed), troubleshoot DNS propagation and click Retry.

  2. Adjusting runtime spec and danger zone destruction (Settings tab):

    • In the Settings tab, you can update the site name at any time, disconnect or reconnect the Git repository (Disconnect repository), adjust build and runtime resource specs, and modify execution timeout (Timeout) and log collection toggles.

    • To fully take a test site offline, scroll to the bottom Danger zone and click Delete site; after completing the secondary confirmation, the site and all of its historical deployment artifacts are permanently deleted (irreversible), and you are automatically returned to the Sites list page.

FAQ and Troubleshooting

Q1: The project sidebar shows the Sites entry; why does clicking Create site to submit fail immediately with an error saying I have no permission to use Sites?

Cause and troubleshooting steps: The sidebar reflects the instance switch and current signed-in user's Sites email allowlist; a submitted request is also checked against its actual caller, current configuration, and permissions. If the entry is visible but an operation fails, check the following:

  1. If the platform administrator has not configured an email allowlist (the list is empty), the Sites feature is disabled for all users.

  2. If the allowlist is not empty, the system checks whether your current login account email (or, when called with a project/organization API Key, the confirmed Owner email of the organization the project belongs to) is on the allowlist. Please contact the platform administrator to add your developer email and organization Owner email to the instance's Sites allowlist.

Q2: Why is the "Instant rollback" button on the site Overview page grayed out and unclickable?

Cause and troubleshooting steps: Instant rollback requires that the current site has at least one old deployment version, besides the current active deployment, whose build status is ready and that has been activated and gone live before. If the site was just created and only has the 1st deployment version, or all previous deployments are failed (never successfully activated and gone live), there is no valid rollback target and the button is automatically disabled.

Q3: Why does the site build log report Permission denied or inability to access intranet addresses?

Cause and troubleshooting steps: Investigate executor identity and network configuration separately:

  1. Runtime identity and permissions: the restricted execution paths for ACS E2B and OpenSandbox check non-root identity and privileges and reject that path if the check fails. Verify the actual identity for other executors. Check Install command, Build command, and scripts for writable-directory and permission requirements; failure behavior depends on the runtime and script.

  2. Build and runtime networking: outbound access during build or SSR depends on the execution environment and network policy. Verify loopback, private-network, and cloud-metadata restrictions in the target deployment; do not assume a single SSRF guard covers all requests.