Docs
Contents

Runtime environment (endpoint and region)

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment, and verify that the project and credentials belong to that environment.

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

EnvironmentAPI endpoint (SDK setEndpoint)Console origin
Managed SIT (testing)https://appbuild-sit.oceanbase.com/v1https://appbuild-sit.oceanbase.com
Managed productionhttps://appbuild.oceanbase.com/v1https://appbuild.oceanbase.com
Self-hostedhttps://<你的实例域名或IP>:<port>/v1origin 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

Managed environment differences

Self-hosted differences

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:

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 ?? '<APPBASE_ENDPOINT_WITH_V1>';
const projectId = process.env.APPBASE_PROJECT_ID ?? '<APPBASE_PROJECT_ID>';
const apiKey = process.env.APPBASE_API_KEY!;

const client = new Client()
    .setEndpoint(endpoint)
    .setProject(projectId)
    .setKey(apiKey)
    .setLocale('zh-CN');
{
  const prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}

// 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}`);

Database table schemas (Shared V2 vs JsonTable) and environment pool tags (poolTag)

DimensionShared V2 schema (enterprise recommended)JsonTable / standalone table schema
Applicable capabilitiesMemory (long-term memory, profile, experience and skill distillation) mandates Shared V2; also fully supports TablesDB, the knowledge base, the lexicon, and the AI gatewaySupports basic TablesDB, Storage, and Functions; the Memory service cannot be enabled
Selected at creationIn 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 migrationSupports project table schema conversion and read/write fence draining via the standard procedure in the platform Admin planeCan be converted online to Shared V2 via the platform Admin plane

Common environment configuration errors and troubleshooting

Symptom / error responseRoot cause analysisResolution
404 Project with the requested ID could not be foundAPPBASE_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-hangzhouAlways pass region: 'default' (pass Region.DEFAULT in Java)
Browser reports a CORS error Access-Control-Allow-OriginThe 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 environmentIn 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 failedA self-signed TLS certificate is used when connecting to the self-hosted test instanceCall .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": "<APPBASE_ENDPOINT_WITH_V1>",
  "consoleOrigin": "<APPBASE_CONSOLE_ORIGIN>",
  "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.