Provision a dedicated Mind

Free and Pro are specified as dedicated Firecracker VM-based Akasha instances. Free is capped; Pro changes the resource and usage arrangement. The latest local customer provisioning code delegates creation to the Minds ensure service and fails closed when it is unconfigured. The dashboard flow rejects mode: "shared".

The initial audit found a Render provisioning path. The engineering coordinator reports that the hosted application still uses that earlier path while the replacement is prepared. The local change has not yet been verified through a deployed instance-to-VM trace. Runtime verification status.

Before creating an instance

Sign in, select an organization, and choose a name. GET /api/provisioning/instances/preflight is currently a legacy diagnostic: it checks Render and Cloudflare configuration, but does not check the new ensure service. Its result is not a reliable readiness gate for the ensure-based create path.

Use the returned region choices in the UI. Do not hardcode a legacy management-region identifier into the dashboard flow: the dashboard planner and older management API have different region vocabularies.

Create the Mind

From the signed-in dashboard origin, send:

const response = await fetch('/api/provisioning/instances', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Research memory',
    mode: 'dedicated',
    plan: 'free',
  }),
});
if (!response.ok) throw new Error(`Provisioning: HTTP ${response.status}`);
const { instance } = await response.json();

The request's name is required after trimming. plan defaults to free; mode is dedicated. The request schema retains optional region, services, modules, hotLoading, and customHostnames fields. However, the current ensure request forwards only the organization as customer_id and an optional region. Do not assume plan capacity, service selection, or custom hostnames were applied. The accepted schema and returned ProvisionedInstance shape are in the schema reference.

The server checks organization context and entitlements, then sends POST /v1/minds/ensure to the configured ensure service with the signed-in bearer token. Ensure must return a Mind ID and base URL. Dashboard success is 201 {instance}, with the returned ID, endpoint, region, and provisioning status. Keep these values rather than constructing an endpoint from the display name. A 201 response does not establish readiness or prove that every requested option was applied.

Check readiness separately

GET /api/provisioning/instances/readiness?endpoint=... checks /health/ready on a normalized HTTPS endpoint under minds.sh. It removes any supplied path, query, or fragment. Other domains and non-HTTPS inputs are rejected.

Use a bounded polling interval and let the user retry. A ready response verifies the health endpoint; complete a scoped memory read and the intended user journey before declaring an integration ready.

This unauthenticated probe checks only the upstream HTTP status, without inspecting its body. It does not verify ownership, authentication, memory operations, or VM isolation. An ensure endpoint outside the allowed Minds hostname policy cannot be checked through this route.

Request an upgrade

POST /api/provisioning/instances/upgrade takes an instanceId and optional provider-resolution fields. If plan is supplied, it must be pro. The server can resolve missing provider identifiers from the active organization's tenant/service records.

{ "instanceId": "<existing-instance-id>", "plan": "pro" }

The POST wrapper returns {instance, sameInstanceId:true} on success. The main /api/provisioning/instances route also exposes a PATCH upgrade operation with plan:"pro" and optional services, returning {instance}. Use one flow consistently; do not issue both as a retry strategy.

The current local upgrade implementation requests the organization's Mind from ensure and returns Pro capacity metadata, but sends no explicit plan or capacity change and does not forward the signed-in bearer token. It also accepts substring matches when comparing instance IDs. Actual resizing, applied service choices, and strict preservation of the existing ID remain unverified. A successful response, including sameInstanceId:true, is not proof that an upgrade occurred.

Service controls

The product contract uses service toggles to control running workloads and cost, rather than separately purchased feature tiers. The current ensure integration does not forward these choices, so their effect needs verification. Existing API schemas may retain starter or old bundle names for compatibility; current customer packaging is Free, Pro, and Enterprise.

Recover from a failure

401 means sign-in is required. 409 NO_ORGANIZATION means context is missing. The create route currently also wraps ensure failures under INVALID_PROVISIONING_REQUEST, so inspect the HTTP status and message instead of assuming this code always means bad input. Missing ensure configuration returns 503; an ensure response without the required ID or URL produces 502. Retain the instance state and request evidence before retrying, because a failed HTTP request can follow a partially completed provider action.

Source: minds-ui/apps/app/lib/provisioning/service.ts, ensure-client.ts, upgrade.ts, types.ts, and the dashboard provisioning route modules. This page describes the local implementation audited on September 12, 2026; hosted Firecracker lifecycle and Free-to-Pro resizing still require runtime verification.