Developer Guide

Deployment

Current developer setup, delivery flow, and environment contract after the Core-first cutover.

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.

Delivery Flow

Local edit
  -> local test / review
  -> commit + push to next
  -> GitHub pipeline builds the image
  -> image is pushed to Docker Hub
  -> operator deploys a fresh managed Core/runtime pod from the immutable digest
  -> rotation runbook updates runtime ID and Vercel/Core token wiring

No direct pod edits.
No ssh patching on the live Core pod.
No ad-hoc pip install on managed runtime.

Managed Runtime Rotation

RunPod pod IDs are runtime instances, not source constants. They change during rotation and must never be hardcoded in product code. The current ID belongs in operator evidence and local environment coordination only.

Use the image digest from the successful GitHub/DockerHub pipeline, not a floating tag.
Run the rotation helper/runbook to sync local managed runtime ID, Vercel env presence, and runtime health checks.
For Core service-token rotation, set the same token value in Core and Vercel.
After deploy, prove AIJIM_ENV=prod rejects relaxed auth even when the relaxed flag is absent or set to 1.

Runtime Topology

Surface	Runtime	Notes
`apps/aijim-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_SIGNING_KEY_ID / AIJIM_SIGNING_PRIVATE_KEY	Current Ed25519 producer key. The production signer-registry row must be derived from the live key, not from a guessed value.	managed runtime secret refs
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

GitHub Actions Secrets

The reusable app-tests workflow now references all four secrets below. The current audit status and the remaining operator work are documented indocumentation/runbooks/OPS_AUDIT_POST_E3.md.

AIJIM_API_KEY
AIJIM_SERVICE_TOKENS
AIJIM_SIGNING_KEY_ID
AIJIM_SIGNING_PRIVATE_KEY
AIJIM_CORE_AUDIT_DB_URL
NEXT_PUBLIC_SUPABASE_URL
AIJIM_LINA_SIGNER_REGISTRY_OPERATOR_USER_IDS
AIJIM_CORE_URL

If the relevant secrets are absent, integration coverage silently narrows: some jobs skip entirely, and some tests fail closed by design. Where older workflows still exportAIJIM_CORE_STAGING_DB_URL, Core keeps read-side compatibility.

Source references

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