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
Capability allowlist: the instance uses
_APP_SITES_WHITELIST_EMAILSto control who may use Sites. When the list is empty, all requests returnSites capability is disabled; when non-empty — project-level API Keys require the email of at least one confirmed Owner in the project Team to be on the list; user Session/JWT is judged by the current user's email; account-level Keys are judged by the Key owner's email. On allowlist errors, stop and contact instance operations; do not retry in a loop.API Key scopes: Site create/delete/update/read and deployments, and variables require
sites.write; reads and usage requiresites.read; domain rules (Proxy) requirerules.read/rules.write.Restricted identity (2.6.0 secure defaults): Site install/build/start commands run under a restricted identity and fail directly when security conditions are not met, with no fallback to elevated execution.
Registering on the management platform (registering the Site domain as an application Platform) requires Console Session; project API Keys do not have the
platforms.*scope (see deployment.md).
Usage workflow
listFrameworks()/listSpecifications()Confirm the frameworks, build runtimes, and specs supported by the target instance; do not hardcode defaults.Create a Site: specify
siteId,name,framework,buildRuntime(e.g.node-22),adapter(staticorssr), build command (installCommand/buildCommand/startCommand),outputDirectory; SPA requiresfallbackFile: 'index.html'; SSR sets the request timeouttimeout(seconds).Package thesource code (including
package.json, excludingnode_modules, build artifacts, and.env) as a tar.gz andcreateDeployment({ siteId, code, activate: true })upload — the response is HTTP 202; the build is asynchronous.Poll
getDeployment({ siteId, deploymentId })until the state machine reacheswaiting → processing → building → ready | failed | canceled; onfailedread the build logs (listLogs/ the deployment's buildLogs).Use thecurrent
deploymentIdto resolve the preview domain via Proxy rules (Console SDK'sproxy.listRules(); the Server SDK has no Proxy service), filtering bydeploymentResourceId+deploymentResourceType: 'site'and matchingrule.deploymentId; takingrules[0]or reusing an old URL is forbidden.(Optional) Custom domains:
proxy.createSiteRule({ domain, siteId }); usecreateVcsDeploymentfor VCS deployments,createTemplateDeploymentfor template deployments, andupdateSiteDeploymentto switch the active deployment for rollback.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
sites.create:siteId(≤36 characters, alphanumeric plus.,-,_),name(≤128 characters);framework/buildRuntime/adapterare all semantically mandatory (mismatched adapter and framework returnsAdapter not supported for the selected frameworkdirectly); afterenabledis disabled, users cannot access the Site but Server/Console SDKs can still manage it; disablingloggingcan speed up responses;timeoutis the maximum seconds per request.sites.createDeployment:codeis the source package (useInputFile.fromPath()on the SDK side);activate: truemeans the deployment is automatically set as active after a successful build; can overrideinstallCommand/buildCommand/outputDirectory.The returned deployment object carries
status, the build log entry, and$createdAt; the Site object carriesenabled,live, and the framework and runtime specs.Build resources and duration are instance configuration: build memory floor is about 2048MB, and the default build timeout is 900 seconds (self-hosted
_APP_COMPUTE_BUILD_TIMEOUT).
Errors and boundaries
Allowlist denies access:
Sites capability is disabled, or the project Key does not meet the confirmed Owner condition — stop the workflow instead of retrying.What is uploaded is the source code, not the local
dist; the platform performs install and build during the build phase.For SPAs using browser router, missing
fallbackFilecauses subpath refreshes to return 404.The domain is only auto-generated onfirst deployment; afterwards the URL resolution priority is: instance public address > rule bound to this deploymentId > rule with the latest
$createdAt.The preview domain may have a Console login gate (SIT environment): it is expected behavior that visitors are first redirected to log in to Console.
SSR Cookie limitation: the Header whitelist with which the Sites proxy forwards requests to the SSR runtime
Cookiedoes not includeSet-Cookie/ (blocked in both directions). The server-side "write Session Cookie → Server Component reads Cookie" approach is not feasible (redirect loop or 404). A viable split: the Server side performs controlled reads/writes using an injected API Key (Site Variablesecret: true); the browser side uses the Client SDK + user/anonymous Session to connect directly to/v1. Pair Next.js withoutput: 'standalone'and trust the forwarded Host header.
SDK Category Differences
Server SDK (server-sdk/nodejs.md): the
Sitesfull service set (create/deploy/variables/framework spec/logs), suited to automated deployment scripts.Console SDK (console-sdk/nodejs.md): likewise provides the full
Sitesset, plusProxy(domain rules),Domains(domain assets), and platform-registration-related calls.Client SDK (client-sdk/web.md): does not expose the Sites management plane; the browser only accesses pages of deployed sites and the
/v1data plane.
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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const frameworks = await sites.listFrameworks();
const specs = await sites.listSpecifications();import io.agentbase.services.Sites;
Sites sites = new Sites(client); // For client initialization, see server-sdk/java.md
var frameworks = sites.listFrameworks(); // List of supported frameworks
var specs = sites.listSpecifications(); // Build runtime and specification; the specification values for create follow thisframeworks = sites.list_frameworks()
specs = sites.list_specifications()sites := agentbase.NewSites(cl) // facade constructor; cl is a Client already loaded with an API Key
frameworks, err := sites.ListFrameworks() // List of supported frameworks
specs, err := sites.ListSpecifications() // Build runtime and specification; the specification values for create follow thiscurl -sS "$APPBASE_ENDPOINT/sites/frameworks" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# Build specifications: GET /sites/specifications; execution plans: GET /sites/execution-plans?framework=reactCreate 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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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)
});Sites sites = new Sites(client); // For client initialization, see server-sdk/java.md
// create takes the full positional parameter list (most are nullable); for the complete signature, see examples/java.md:
sites.create("portal", "用户门户", Framework.REACT, BuildRuntime.NODE_22,
true, true, 30L,
"npm install", "npm run build", "", "dist",
Adapter.STATIC,
null, "index.html", // installationId, fallbackFile (required for SPA)
null, null, false, null, // VCS-related
null, null, null, null, null); // Specifications / execution plan / retention period, see listSpecifications()from agentbase.services.sites import Sites
sites = Sites(client) # Synchronous call, returns a pydantic model
sites.create(site_id='portal', name='用户门户', framework='react',
build_runtime='node-22', adapter='static',
install_command='npm install', build_command='npm run build',
output_directory='dist', fallback_file='index.html')sites := agentbase.NewSites(cl) // facade constructor; cl is a Client already loaded with an API Key
_, err := sites.Create("portal", "用户门户", "react", "node-22", // framework / buildRuntime are required positional parameters
sites.WithCreateAdapter("static"), // SSR uses "ssr" and sets timeout (seconds)
sites.WithCreateInstallCommand("npm install"),
sites.WithCreateBuildCommand("npm run build"),
sites.WithCreateOutputDirectory("dist"),
sites.WithCreateFallbackFile("index.html")) // Required for SPA (browser router)
// For the full framework list, rely on ListFrameworks(); do not hardcodecurl -sS -X POST "$APPBASE_ENDPOINT/sites" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"siteId":"portal","name":"用户门户","framework":"react","buildRuntime":"node-22","adapter":"static","installCommand":"npm install","buildCommand":"npm run build","outputDirectory":"dist","fallbackFile":"index.html"}'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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
import { ID } from 'agentbase-node-sdk';
await sites.createVariable({
siteId: 'portal',
variableId: ID.unique(),
key: 'VITE_API_BASE',
value: 'https://example.com/v1'
});// Difference from the Node side: Java createVariable has no variableId parameter (the ID is generated server-side)
sites.createVariable("portal", "VITE_API_BASE", "https://example.com/v1",
null); // secret: pass true for secret values, masked when read; after modifying a variable, createDeployment must be re-run to take effect# Difference from the Node side: Python create_variable has no variable_id parameter (the ID is generated server-side)
sites.create_variable(site_id='portal', key='VITE_API_BASE', value='https://example.com/v1',
secret=None) # Pass True for secret values; masked when read_, err := sites.CreateVariable("portal", "VITE_API_BASE", "https://example.com/v1") // No variableId; generated by the server
// Secret values are passed via WithCreateVariableSecret(true) (masked on read); after modifying a variable, a new CreateDeployment is required to take effectcurl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/variables" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"variableId":"v1","key":"VITE_API_BASE","value":"https://example.com/v1","secret":false}'
# List GET /sites/portal/variables (secrets are not echoed back); update PUT /sites/portal/variables/{variableId}; delete DELETE on the same pathDeploy 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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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 asynchronouslyimport io.agentbase.models.InputFile;
var dep = sites.createDeployment("portal",
InputFile.fromPath(java.nio.file.Paths.get("./site.tar.gz")), // Source package, not a local dist build artifact
null, null, null, // installCommand / buildCommand / outputDirectory overrides
true); // activate: automatically set as the active deployment after a successful build; HTTP 202, build is async
// dep.getId() is used by the "Poll build status" cardfrom agentbase.input_file import InputFile
dep = sites.create_deployment(site_id='portal',
code=InputFile.from_path('./site.tar.gz'), # Source package, not a local dist build artifact
activate=True) # HTTP 202: build is asynchronousdep, err := sites.CreateDeployment("portal",
file.NewInputFile("./site.tar.gz", "site.tar.gz"), // Source package (agentbase-go-sdk/file), not a local dist build artifact
sites.WithCreateDeploymentActivate(true)) // Automatically set as the active deployment after a successful build; HTTP 202: build is asynchronouscurl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-F "code=@site.tar.gz" -F "activate=true"
# multipart/form-data; returns 202Poll 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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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
}import io.agentbase.enums.DeploymentStatus;
var d = sites.getDeployment("portal", dep.getId()); // dep is the return value of createDeployment from the "Upload source code deployment" card
while (d.getStatus() != DeploymentStatus.READY && d.getStatus() != DeploymentStatus.FAILED
&& d.getStatus() != DeploymentStatus.CANCELED) {
Thread.sleep(5000); // Asynchronous build: poll at intervals
d = sites.getDeployment("portal", dep.getId());
}
if (d.getStatus() == DeploymentStatus.FAILED) {
System.out.println(d.getBuildLogs()); // Build log; locate the cause of failure
}import time
# dep is the return value of create_deployment from the "Deploy from uploaded source code" card
d = sites.get_deployment(site_id='portal', deployment_id=dep.id)
while d.status not in ('ready', 'failed', 'canceled'):
time.sleep(5) # Asynchronous build: poll at intervals
d = sites.get_deployment(site_id='portal', deployment_id=dep.id)
if d.status == 'failed':
... # Read the buildLogs (build logs) of the deployment record to locate the failure cause// dep is the return value of CreateDeployment from the "Upload source code deployment" card
d, err := sites.GetDeployment("portal", dep.Id)
for d.Status != "ready" && d.Status != "failed" && d.Status != "canceled" {
time.Sleep(5 * time.Second) // Asynchronous build: poll at intervals
d, err = sites.GetDeployment("portal", dep.Id)
}
// When d.Status == "failed", read d.BuildLogs to find the failure causecurl -sS "$APPBASE_ENDPOINT/sites/portal/deployments/$DEPLOYMENT_ID" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# Poll until status is ready | failed | canceled; if failed, read buildLogs from the responseDomains (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.)
- Console (Node.js)
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.)
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
// 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>' });import io.agentbase.enums.TemplateReferenceType;
import io.agentbase.enums.VCSReferenceType;
// VCS deployment: HTTP 202, build is asynchronous
sites.createVcsDeployment("portal", VCSReferenceType.COMMIT, "prod", true);
// Template deployment: create from the template repository
sites.createTemplateDeployment("portal", "agentbase/function-templates", "agentbase",
"hello-world", TemplateReferenceType.BRANCH, "main", true);
// Rollback: switch the active deployment
sites.updateSiteDeployment("portal", "<previousDeploymentId>");sites.create_vcs_deployment(site_id='portal', type='commit', reference='prod',
activate=True) # HTTP 202, build is asynchronous; type: branch / commit / tag
sites.create_template_deployment(site_id='portal', repository='agentbase/function-templates',
owner='agentbase', root_directory='hello-world',
type='branch', reference='main', activate=True)
sites.update_site_deployment(site_id='portal', deployment_id='<previousDeploymentId>') # Rollback: switch the active deployment_, err := sites.CreateVcsDeployment("portal", "commit", "prod",
sites.WithCreateVcsDeploymentActivate(true)) // type: branch / commit / tag; HTTP 202, build is asynchronous
_, err = sites.CreateTemplateDeployment("portal", "agentbase/function-templates", "agentbase",
"hello-world", "branch", "main",
sites.WithCreateTemplateDeploymentActivate(true))
_, err = sites.UpdateSiteDeployment("portal", "<previousDeploymentId>") // Rollback: switch the active deployment# VCS deployment (site already linked to a repository)
curl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/deployments/vcs" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"type":"commit","reference":"prod","activate":true}'
# Template deployment
curl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/deployments/template" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"repository":"agentbase/function-templates","owner":"agentbase","rootDirectory":"hello-world","type":"branch","reference":"main","activate":true}'
# Rollback: switch the active deployment
curl -sS -X PATCH "$APPBASE_ENDPOINT/sites/portal/deployment" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"deploymentId":"<previousDeploymentId>"}'Example Guide
JavaScript (Node deployment scripts / Console workflow): examples/javascript.md
Java (Server / Console SDK call examples): examples/java.md