Docs
Contents

Sites

Overview and use cases

Sites build and host Web frontends within the platform (static sites static or server-rendered ssr), and each Site has its own preview domain. Build and run are performed by the platform's executor; Sites host only the frontend — the auth, TablesDB, Storage, Functions, etc. called within pages still go through the unified /v1 API base URL.

Use cases: providing an application with an accessible Web entry point (admin console, user portal, landing page); ops-free frontend delivery of "submit source → platform builds → get URL"; hosting SSR frameworks (Next.js/Nuxt/SvelteKit/Astro).

Prerequisites

Usage workflow

  1. listFrameworks() / listSpecifications() Confirm the frameworks, build runtimes, and specs supported by the target instance; do not hardcode defaults.

  2. Create a Site: specify siteId, name, framework, buildRuntime (e.g. node-22), adapter (static or ssr), build command (installCommand / buildCommand / startCommand), outputDirectory; SPA requires fallbackFile: 'index.html'; SSR sets the request timeout timeout (seconds).

  3. Package thesource code (including package.json, excluding node_modules, build artifacts, and .env) as a tar.gz and createDeployment({ siteId, code, activate: true }) upload — the response is HTTP 202; the build is asynchronous.

  4. Poll getDeployment({ siteId, deploymentId }) until the state machine reaches waiting → processing → building → ready | failed | canceled; on failed read the build logs (listLogs / the deployment's buildLogs).

  5. Use thecurrent deploymentId to resolve the preview domain via Proxy rules (Console SDK's proxy.listRules(); the Server SDK has no Proxy service), filtering by deploymentResourceId + deploymentResourceType: 'site' and matching rule.deploymentId; taking rules[0] or reusing an old URL is forbidden.

  6. (Optional) Custom domains: proxy.createSiteRule({ domain, siteId }); use createVcsDeployment for VCS deployments, createTemplateDeployment for template deployments, and updateSiteDeployment to switch the active deployment for rollback.

  7. Build-time variables are managed with createVariable({ siteId, variableId, key, value, secret }); after modifying variables you must create a new createDeployment for them to enter the build/runtime.

Key parameters and returns

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Enumerate frameworks and specs

Before creating, confirm the frameworks, build runtimes, and specs supported by the instance; do not hardcode defaults. (The client SDK does not expose Sites management; there is no web tab.)

const frameworks = await sites.listFrameworks();
const specs = await sites.listSpecifications();

Create a site

For create, the framework / buildRuntime / adapter are all semantically required (mismatches raise Adapter not supported for the selected framework directly); SPA must fallbackFile: 'index.html'. (The client SDK does not expose Sites management; there is no web tab.)

import { Client, Sites } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // Must include /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);        // sites.write minimal scope
const sites = new Sites(client);

await sites.create({
    siteId: 'portal',
    name: '用户门户',
    framework: 'react',              // The full list is subject to sites.listFrameworks(); do not hardcode
    buildRuntime: 'node-22',
    adapter: 'static',               // SSR uses 'ssr' and sets timeout (seconds)
    installCommand: 'npm install',
    buildCommand: 'npm run build',
    outputDirectory: 'dist',
    fallbackFile: 'index.html'       // Required for SPA (browser router)
});

Site variables

Variables are injected as environment variables into the build and SSR runtime; pass secret values as secret: true (masked on read, never echoed in plaintext). After modifying variables, you must create a new createDeployment for them to take effect in the build/runtime. (The client SDK does not expose Sites management; there is no web tab.)

import { ID } from 'agentbase-node-sdk';

await sites.createVariable({
    siteId: 'portal',
    variableId: ID.unique(),
    key: 'VITE_API_BASE',
    value: 'https://example.com/v1'
});

Deploy by uploading source code

Package source code (including package.json, excluding node_modules, build artifacts, .env) as tar.gz and upload; the response is HTTP 202 and the build is asynchronous; activate: true means it is automatically set as the active deployment after a successful build. (The client SDK does not expose Sites management; there is no web tab.)

import { InputFile } from 'agentbase-node-sdk/file';

const dep = await sites.createDeployment({
    siteId: 'portal',
    code: InputFile.fromPath('./site.tar.gz'),   // Source package, not a local dist build artifact
    activate: true                               // Automatically set as the active deployment after a successful build
});                                              // HTTP 202: build runs asynchronously

Poll build status

Poll getDeployment until the state machine reaches waiting → processing → building → ready | failed | canceled; on failed, read buildLogs from the deployment record. (The client SDK does not expose Sites management; there is no web tab.)

let d = await sites.getDeployment({ siteId: 'portal', deploymentId: dep.$id }); // The ID returned by this createDeployment call
while (!['ready', 'failed', 'canceled'].includes(d.status)) {
    await new Promise((r) => setTimeout(r, 5000));   // Asynchronous build: poll at intervals
    d = await sites.getDeployment({ siteId: 'portal', deploymentId: dep.$id });
}
if (d.status === 'failed') {
    console.log(d.buildLogs);                        // Build log; locate the cause of failure
}

Domains (resolving the preview address and custom domains)

Domains are generated automatically only on the first deployment; to resolve the preview address, use the Console SDK's proxy.listRules() filtered by deploymentResourceId + deploymentResourceType: 'site', then match the current rule.deploymentId; do not take rules[0] or reuse old URLs; use proxy.createSiteRule({ domain, siteId }) for fixed subdomains/custom domains. (Proxy is provided only by the Console SDK: the Server SDK has no Proxy service and REST has no proxy rules endpoint, so there are no other tabs.)

import { Client, Proxy, Query } from 'agentbase-console-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT)
    .setProject(process.env.APPBASE_PROJECT_ID);
// Console Session or project API Key (rules.read / rules.write); loading instructions see console-sdk/nodejs.md
const proxy = new Proxy(client);

// Resolve the preview domain of this deployment (dep.$id is the value returned by this createDeployment call)
const rules = await proxy.listRules({
    queries: [
        Query.equal('deploymentResourceId', ['portal']),
        Query.equal('deploymentResourceType', ['site'])
    ]
});
const bound = rules.rules.find((r) => r.domain && r.deploymentId === dep.$id);
console.log(bound.domain);   // Preview URL; must not fetch rules[0]

// (Optional) Fixed subdomain or custom domain (generates a trigger=manual public rule)
await proxy.createSiteRule({
    domain: 'app.example.com',
    siteId: 'portal',
    branch: 'main'           // Optional: bind a Git branch
});

VCS and template deployments, rollback

For sites linked to a VCS, use createVcsDeployment to build by branch/commit/tag; for template deployments, use createTemplateDeployment to specify the repository/owner/directory/reference; for rollback, use updateSiteDeployment to switch the active deployment back to the target deploymentId (visitors will then access the old deployment's artifacts). (The client SDK does not expose Sites management; there is no web tab.)

// VCS deployment: HTTP 202, build is asynchronous
await sites.createVcsDeployment({
    siteId: 'portal',
    type: 'commit',              // branch / commit / tag, depending on reference
    reference: 'prod',
    activate: true
});

// Template deployment: create from the template repository
await sites.createTemplateDeployment({
    siteId: 'portal',
    repository: 'agentbase/function-templates',
    owner: 'agentbase',
    rootDirectory: 'hello-world',
    type: 'branch',
    reference: 'main',
    activate: true
});

// Rollback: switch the active deployment
await sites.updateSiteDeployment({ siteId: 'portal', deploymentId: '<previousDeploymentId>' });

Example Guide