Addon Stack API

The Addon Stack API lets hosting providers generate Docker Compose overlay files that add services to an existing OpenClaw infrastructure. Unlike the full-stack generate() pipeline, these functions produce only the addon layer — no gateway, no Redis, no PostgreSQL, no reverse proxy.

This is the recommended integration point for platforms like Clawexa that already provision core infrastructure via cloud-init or similar tooling.

Installation

npm install @better-openclaw/core
# or
pnpm add @better-openclaw/core

Quick Example

import { generateAddonStack } from "@better-openclaw/core";

const result = generateAddonStack({
  instanceId: "user-abc-123",
  services: ["n8n", "qdrant", "meilisearch"],
  generateSecrets: true,
  reservedPorts: [3000, 5432, 6379], // ports used by your infra
});

// result.composeOverride  → Docker Compose YAML string
// result.envFile          → .env file contents
// result.proxyRoutes      → routes to register in your reverse proxy
// result.openclawConfigPatch → openclaw.json skill entries
// result.metadata         → resolved services, port assignments, etc.

generateAddonStack(input)

Generates a complete addon stack from a list of service IDs. Returns Docker Compose YAML, environment variables, proxy routes, and skill configuration — ready to write to disk and docker compose up.

Parameters

Return Value: AddonStackResult

Skipped Services

Services may be skipped (excluded from output) without throwing an error. Each skipped service includes a reason:

updateAddonStack(input)

Incrementally adds or removes services from an existing addon stack. Preserves user-modified environment values and computes diffs for orchestration.

Parameters

Return Value: AddonStackUpdateResult

Infrastructure Filtering

The addon stack API automatically filters out infrastructure services that are expected to be managed by the hosting platform:

// These service IDs are always excluded from addon output:
openclaw-gateway, openclaw-cli, redis, postgresql,
open-webui, caddy, traefik, postgres-setup,
convex, convex-dashboard, mission-control

If a user requests an infrastructure service, it's silently removed and a warning is added to the result. Services that depend on infrastructure (like n8n needing PostgreSQL) automatically get a postgres-setup init container that connects to the existing database.

Port Conflict Resolution

Pass your infrastructure's occupied ports via reservedPorts. When an addon service's default port conflicts, it's automatically reassigned to port + 1000. The actual assignments are reported in metadata.portAssignments.

const result = generateAddonStack({
  instanceId: "prod-01",
  services: ["n8n"],
  reservedPorts: [5678], // n8n's default port is taken
});

// n8n will be assigned port 6678 instead
console.log(result.metadata.portAssignments);
// { "n8n:5678": 6678 }

Proxy Routes

Each service with a proxyPath definition generates a proxy route. Use these to configure your reverse proxy (Caddy, Traefik, nginx):

for (const route of result.proxyRoutes) {
  console.log(route);
  // { serviceId: "n8n", path: "/n8n", port: 5678, protocol: "http", stripPrefix: true }
}

// Caddy example:
// handle_path /n8n/* {
//   reverse_proxy n8n:5678
// }

Environment Quirks

Some services have known environment variable issues. The addon stack API handles these automatically via the envQuirks system:

• empty_string_crashes — setting an env var to an empty string causes the service to crash. The API sets a safe default value.
• min_length — the value must be at least N bytes. The API generates appropriately-sized secrets.
• must_sync — two env vars must have the same value. The API syncs them automatically.

Zod Schemas

All input/output types are defined as Zod schemas and exported from @better-openclaw/core:

import {
  AddonStackInputSchema,
  AddonStackResultSchema,
  AddonStackUpdateInputSchema,
  AddonStackUpdateResultSchema,
  ProxyRouteSchema,
  SkippedServiceSchema,
} from "@better-openclaw/core";

// Validate external input before passing to generateAddonStack:
const parsed = AddonStackInputSchema.parse(untrustedInput);
const result = generateAddonStack(parsed);

See also: REST API Endpoints | Hosting Provider Integration Guide