Developer Guide

Deployment

Local setup, static topology, and the currently contained remote-publication boundary.

Remote publication is currently contained

The seven DockerHub publishers and the direct Vercel, coordinated promotion, and RunPod deployment workflows remain contained. DockerHub, coordinated promotion, and RunPod are typed no-trigger tombstones; direct Vercel is a manual-only, read-only probe whose sole job reports the blocking marker and fails. Repository-held write credentials have been removed. This page does not authorize a provider deployment, runtime mutation, Preview, or Production publication; each requires a separately ratified successor contract and exact target evidence.

Canonical Local Start

The canonical local reset path remains./aijim.sh reset --with-seed. The script also supports hybrid managed mode, docs startup, and app-only restarts. The operational command surface lives inaijim.shitself and should be treated as the source artifact.

Current Delivery Boundary

Local edit
  -> local test / review
  -> commit to a feature branch
  -> repository quality and containment gates
  -> STOP: no current DockerHub, RunPod, Vercel, or coordinated-promotion authority

The former remote-delivery sequence is historical only.
Independent privileged provider or local-CLI authority is outside this
bounded repository-path closure and is not admitted by it.

Successor Rotation Requirements

RunPod pod IDs are runtime instances, not source constants. They change during rotation and must never be hardcoded in product code. No repository path currently creates, mutates, or retires a remote runtime. The following are requirements for a future authorized successor, not operator instructions.

Bind an immutable image digest produced by a separately authorized publisher; never use a floating tag as evidence.
Bind the exact provider account, template, runtime, rollback target, and cost authority before mutation.
Keep Core and App credentials synchronized without exposing their values.
Prove runtime identity, health, failure, rollback, and AIJIM_ENV=prod fail-closed behavior before acceptance.

Runtime Topology

Surface	Runtime	Notes
`apps/shark-app`	Vercel / local Next.js runtime	Browser UI plus BFF/proxy routes.
Megabundle services pod	managed runtime A40 pod	`aijim-core`, `aijim-ecamx`, `aijim-copilot`, and derived writer. Current doc anchor: ports `8000/8010/8020/8030`.
`voice-renderer`	Separate managed runtime	Voice synthesis stays out of the audit/Core scope.
Supabase	Hosted Postgres + auth	Canonical database and auth substrate.

Environment Variables

Variable	What It Does	Typical Location
AIJIM_CORE_URL	Base URL used by app-side proxies to reach the live `aijim-core` FastAPI surface.	.env / .env.local / GitHub Actions secret
AIJIM_API_KEY	Vercel-side proxy credential. Must match the current Core service-token value; presence is release-gated without logging the secret.	Vercel production env
AIJIM_SERVICE_TOKENS	Core service-token allowlist. Runtime templates use secret refs; the value must be rotated in lockstep with Vercel AIJIM_API_KEY.	managed runtime secret / pod env
AIJIM_ENV	prod on managed runtime. Relaxed auth is allowed only for explicit non-production environments.	managed runtime template
AIJIM_SIGN_AUDIT_BUNDLES	Enables Core publication signing. Unsigned bundles remain explicit L1; trusted L2 requires registry trust.	managed runtime template
AIJIM_WORKSPACE_SIGNING_KEYSTORE_MASTER_KEY / AIJIM_WORKSPACE_SIGNING_KEYSTORE_JSON_B64	Workspace-scoped encrypted signing custody. Versioned Production templates never use the historical raw AIJIM_SIGNING_KEY_ID / AIJIM_SIGNING_PRIVATE_KEY bootstrap pair.	local development or a separately authorized runtime custody contract
AIJIM_CORE_AUDIT_DB_URL	Canonical audit/staging Postgres DSN for `aijim-core` integration tests and audit cleanup helpers. `AIJIM_CORE_STAGING_DB_URL` remains a legacy read-side alias.	.env / GitHub Actions secret
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL for browser/runtime configuration and staging allowlist checks.	.env / .env.local / GitHub Actions secret
AIJIM_LINA_SIGNER_REGISTRY_OPERATOR_USER_IDS	Comma-separated operator allowlist for signer-registry writes in Core-owned audit flows.	.env / GitHub Actions secret

Environment-Name Contract

These names document the static integration contract. Their presence here does not prove that a provider value exists and does not grant remote mutation authority. Current evidence and bounded nonclaims are documented indocumentation/runbooks/OPS_AUDIT_POST_E3.md.

AIJIM_API_KEY
AIJIM_SERVICE_TOKENS
AIJIM_WORKSPACE_SIGNING_KEYSTORE_MASTER_KEY
AIJIM_WORKSPACE_SIGNING_KEYSTORE_JSON_B64
AIJIM_CORE_AUDIT_DB_URL
NEXT_PUBLIC_SUPABASE_URL
AIJIM_LINA_SIGNER_REGISTRY_OPERATOR_USER_IDS
AIJIM_CORE_URL

If required test secrets are absent, integration coverage narrows explicitly or fails closed by design. Where historical workflows exportedAIJIM_CORE_STAGING_DB_URL, Core keeps read-side compatibility.

Source references

Deployment details in this page summarizeaijim.sh,documentation/runbooks/MANAGED_RUNTIME_OPERATIONS.md,documentation/runbooks/LINA_VOICE_RENDERER_OPERATIONS.md, anddocumentation/runbooks/OPS_AUDIT_POST_E3.md.