Runtime environment (endpoint and region)
Before SDK integration, two environment facts must be determined: API endpoint (the absolute base URL the SDK calls) and region (the deployment region of the project; 2.6.0 has only default). This page also explains the differences between the managed environment and self-hosted instances, and the derivation rules for Sites access addresses.
Endpoint specification
Must be an absolute
http://orhttps://URL, and may use a domain name, IPv4, IPv6, and an explicit port.The API path allows only empty,
/, or/v1; when used by the SDK it is normalized uniformly to a single/v1(setEndpoint('https://<host>/v1')).Rejects userinfo, query, fragment, and other business paths.
consoleOriginis the origin of the canonical endpoint with/v1removed, and must preserve the scheme and port (used by both Console pages and Webhook reporting).
| Environment | API endpoint (SDK setEndpoint) | Console origin |
|---|---|---|
| Managed SIT (testing) | https://appbuild-sit.oceanbase.com/v1 | https://appbuild-sit.oceanbase.com |
| Managed production | https://appbuild.oceanbase.com/v1 | https://appbuild.oceanbase.com |
| Self-hosted | https://<你的实例域名或IP>:<port>/v1 | origin of the same instance with /v1 removed |
If you are unsure of the current environment: log in to the corresponding Console, find any /v1/... request in browser developer tools → Network, and copy its origin + /v1. Agentbase does not use Appwrite Cloud regional endpoints (*.cloud.appwrite.io), and silently falling back to another environment is forbidden.
Region
The 2.6.0 instance configuration (
app/config/regions.php) registers only one region:default(enabled by default).When creating a project, just pass
defaultasregion; passing another region value yieldsInvalid 'region' param: Value must be one of (default).Do not use Appwrite Cloud regional enums such as
Region.Fra/Region.Sgp; after project creation the API base address matches the environment, and no project-specific domain is generated based on region.When creating a project, you may also pass an optional
poolTagto specify a database pool tag (when omitted, the fallback pool with an empty tag is matched); see overview.md.
Managed environment differences
Testing and production are two independent environments: accounts, projects, Platform registrations, and API Keys are not shared; for multiple environments, create projects and register Platforms separately.
The Console management plane's "Console project" commonly has ID
console; Console SDK initialization first loadssetProject('console')(or the environment's actual Console project ID), then switches tosetProject(应用项目 ID)after the application project is created.Sites and the API share the same origin: Site access address = endpoint with
/v1removed (e.g.,https://appbuild-sit.oceanbase.com/v1corresponds tohttps://appbuild-sit.oceanbase.com); both the Sites subdomain and the Proxy rule domain are derived from this origin, and no additional "subdomain + IP" address is generated.
Self-hosted differences
The endpoint uses your own instance address; the behavior baseline is consistent with the managed instance, but capability switches are determined by instance environment variables (e.g., the Sites whitelist, Function sandbox backend, module gating), and the upgrade cadence follows instance operations.
2.6.0 security defaults also apply in self-hosting: external URLs (migration source, Custom OAuth2 endpoint, remote preview, etc.) reject localhost / private network / cloud metadata addresses; remote Avatar/Favicon/Screenshot are unavailable by default; Functions/Sites run with restricted identities. Do not recommend disabling SSRF protection long-term to restore old behavior.
Self-hosted troubleshooting involving background workers (e.g., list status stuck at
processing, queue backlog) is covered in troubleshooting.md.
Multi-language SDK environment initialization and certificate/timeout configuration
When switching between managed SIT (testing https://appbuild-sit.oceanbase.com/v1), managed production (https://appbuild.oceanbase.com/v1), and self-hosted instances, SDKs in all languages load environment parameters via a unified setEndpoint (or WithEndpoint) and setProject (or WithProject). Below are the standard environment initialization templates for each language on the server side and client side:
- Node.js (Server)
- Web (user session)
- Java
- Python
- Go
- REST (curl)
import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';
// Read from environment variables first; hardcoding cross-environment fallback logic in business code is forbidden
const endpoint = process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1';
const projectId = process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210';
const apiKey = process.env.APPBASE_API_KEY!;
const client = new Client()
.setEndpoint(endpoint)
.setProject(projectId)
.setKey(apiKey)
.setLocale('zh-CN');
// Enable only when using self-signed TLS certificates in self-hosted development/test environments; strictly forbidden in production
if (process.env.APPBASE_SELF_SIGNED === 'true') {
client.setSelfSigned(true);
}
const health = new Health(client);
const status = await health.get();
console.log(`环境连通成功: endpoint=${endpoint}, status=${status.status}`);import { Client, Account } from 'agentbase-web-sdk';
// The browser side configures only the Endpoint and Project ID; injecting any API key is strictly forbidden
const client = new Client()
.setEndpoint(import.meta.env.VITE_APPBASE_ENDPOINT || 'https://appbuild-sit.oceanbase.com/v1')
.setProject(import.meta.env.VITE_APPBASE_PROJECT_ID || 'enterprise-ai-hub-210')
.setLocale('zh-CN');
const account = new Account(client);
// Before cross-origin requests in the browser, ensure the current frontend domain is registered as a Web platform under Console -> Overview -> Platformsimport io.agentbase.Client;
import io.agentbase.services.Health;
String endpoint = System.getenv().getOrDefault("APPBASE_ENDPOINT", "https://appbuild-sit.oceanbase.com/v1");
String projectId = System.getenv().getOrDefault("APPBASE_PROJECT_ID", "enterprise-ai-hub-210");
String apiKey = System.getenv("APPBASE_API_KEY");
Client client = new Client()
.setEndpoint(endpoint)
.setProject(projectId)
.setKey(apiKey)
.setSelfSigned("true".equalsIgnoreCase(System.getenv("APPBASE_SELF_SIGNED")));
Health health = new Health(client);
System.out.println("Gateway status: " + health.get().getStatus());import os
from agentbase.client import Client
from agentbase.services.health import Health
endpoint = os.environ.get('APPBASE_ENDPOINT', 'https://appbuild-sit.oceanbase.com/v1')
project_id = os.environ.get('APPBASE_PROJECT_ID', 'enterprise-ai-hub-210')
api_key = os.environ['APPBASE_API_KEY']
client = (
Client()
.set_endpoint(endpoint)
.set_project(project_id)
.set_key(api_key)
.set_self_signed(os.environ.get('APPBASE_SELF_SIGNED', '').lower() == 'true')
)
health = Health(client)
print('Gateway status:', health.get().status)package main
import (
"fmt"
"os"
"time"
"agentbase-go-sdk/agentbase"
)
func main() {
endpoint := os.Getenv("APPBASE_ENDPOINT")
if endpoint == "" {
endpoint = "https://appbuild-sit.oceanbase.com/v1"
}
cl := agentbase.NewClient(
agentbase.WithEndpoint(endpoint),
agentbase.WithProject(os.Getenv("APPBASE_PROJECT_ID")),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
agentbase.WithTimeout(30*time.Second),
)
health := agentbase.NewHealth(cl)
st, err := health.Get()
fmt.Println(st, err)
}# Verify that the current environment's Endpoint, Project ID and API Key triple match
export APPBASE_ENDPOINT="https://appbuild-sit.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
curl -sS "$APPBASE_ENDPOINT/health" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"Database table schemas (Shared V2 vs JsonTable) and environment pool tags (poolTag)
| Dimension | Shared V2 schema (enterprise recommended) | JsonTable / standalone table schema |
|---|---|---|
| Applicable capabilities | Memory (long-term memory, profile, experience and skill distillation) mandates Shared V2; also fully supports TablesDB, the knowledge base, the lexicon, and the AI gateway | Supports basic TablesDB, Storage, and Functions; the Memory service cannot be enabled |
| Selected at creation | In the Console's new project dialog or in projects.create, specify the database pool poolTag belonging to Shared V2 (or use the default Shared V2 pool) | Specify the poolTag of the corresponding schema |
| Environment migration | Supports project table schema conversion and read/write fence draining via the standard procedure in the platform Admin plane | Can be converted online to Shared V2 via the platform Admin plane |
Common environment configuration errors and troubleshooting
| Symptom / error response | Root cause analysis | Resolution |
|---|---|---|
404 Project with the requested ID could not be found | APPBASE_ENDPOINT Points to the production environment (appbuild.oceanbase.com), but passes a projectId created in the SIT environment (appbuild-sit.oceanbase.com) (or vice versa) | Verify that endpoint and projectId belong to the same environment; SIT and production environments are fully isolated |
Invalid 'region' param: Value must be one of (default) | Calling projects.create passes non-standard region values such as fra, sgp, cn-hangzhou | Always pass region: 'default' (pass Region.DEFAULT in Java) |
Browser reports a CORS error Access-Control-Allow-Origin | The current frontend running domain (e.g., localhost:5173 or the production business domain) is not registered as a Web Platform under the target project in the target environment | In the corresponding environment's Console → project Overview → Platforms (or call the Console SDK projects.createPlatform) register the hostname |
DEPTH_ZERO_SELF_SIGNED_CERT / PKIX path building failed | A self-signed TLS certificate is used when connecting to the self-hosted test instance | Call .setSelfSigned(true) only in a controlled test environment, or import the internal root CA into the runtime trust store |
Environment context file (optional convention)
When environment metadata must be handed to automation (Agent / deployment scripts), you can save non-sensitive context (endpoint, region, source); never write credentials such as email, password, Session, API Key, or Project ID:
{
"schemaVersion": 1,
"apiEndpoint": "https://appbuild.oceanbase.com/v1",
"consoleOrigin": "https://appbuild.oceanbase.com",
"region": "default",
"source": "console-skill-card"
}Storage location: user-level ${XDG_CONFIG_HOME:-$HOME/.config}/ob-agentbase/environment.json; project-level <projectRoot>/.agentbase/environment.json overrides user-level. Resolution order: explicitly given in the request → project-level → APPBASE_ENDPOINT in the project .env (compatible with APPWRITE_ENDPOINT) → user-level → ask the user.