Skip to main content
Hive is the Tuturuuu research satellite app at https://hive.tuturuuu.com. It uses the centralized Tuturuuu login handoff and keeps protected product APIs inside apps/web under /api/v1/hive/*. Hive consumes cross-app login tokens through /verify-token. That verifier posts the handoff token to /api/auth/verify-app-token, trusts the returned HttpOnly app-session cookies, and then redirects to the requested Hive path. Protected routes require both the Hive-local app-session cookie and the Web-issued app-session cookie used for forwarded central APIs. If only the Hive-local cookie remains, Hive sends the browser through local /login to recover the full cookie pair. Expired access tokens should rotate through same-origin /api/auth/refresh-app-session while refresh cookies remain valid. Hive must not create or refresh a Hive-domain Supabase Auth session. Hive local logout is intentionally app-local: /api/auth/logout clears tuturuuu_app_session, expires stale Supabase Auth cookies on the Hive host, and redirects browser form submissions back to /login. Keep that route outside the generic API proxy guard path so logout does not wait on product API rate-limit checks.

​
Dual-Host Parity

Hive is available through both the standalone satellite host and the main web dashboard. The standalone route shape stays / and /not-whitelisted. Inside apps/web, the route shape is /{wsId}/hive and /{wsId}/hive/not-whitelisted; the wsId segment is only the surrounding web dashboard context and must not filter Hive servers, snapshots, realtime membership, or world data. Both hosts must render the same shared Studio UI, engine, realtime client, data hooks, and access-request card from @tuturuuu/hive-ui. Keep apps/hive and the apps/web Hive routes as thin host wrappers for auth, access resolution, build metadata, and forwarded API context only. Future Hive feature work belongs in packages/hive-ui, @tuturuuu/realtime/hive, or the centralized Hive APIs so the standalone app and web-hosted app stay 1:1.

​
Access Model

  • Production access is resolved from Supabase public.hive_members with enabled = true plus platform-admin roles. The dedicated Hive Postgres hive_members table is still synchronized for product data workflows, but app access gates must not require HIVE_DATABASE_URL just to decide whether a signed-in user can open Hive.
  • Researchers who authenticate successfully but are not enabled land on /not-whitelisted, where they can create or refresh a hive_access_requests row. That page polls /api/v1/hive/access-requests/me every 5 seconds and opens Hive automatically after the request reaches the approved/access-enabled state.
  • Platform admins are users whose platform_user_roles.allow_role_management value is true; they can create and manage Hive servers and Hive members.
  • Root workspace admins can enable or disable Hive access from /{rootWorkspaceId}/platform/roles without opening the Hive satellite app.
  • Pending Hive requests appear in the same platform roles panel. Approving a request writes both the dedicated Hive Postgres hive_members row and the Supabase public.hive_members row that the Hive satellite uses for its local server gate and that apps/web uses for embedded Hive routes. Do not update only one store, or users can authenticate through Tuturuuu and then loop back to the restricted page or fail an embedded Hive preload.
  • V1 server policy is intentionally broad: every enabled Hive member can join every enabled Hive server.
  • Hive servers are global research worlds. Workspace selection inside the Hive editor is only an AI context and billing control; it must not filter server lists, snapshots, realtime membership, or world data.
  • apps/web remains the login authority and verifies platform roles through internal APIs. Hive itself uses the app-session JWT as the local identity cookie. Hive product data belongs in the dedicated Docker-managed Hive Postgres database and is accessed through HIVE_DATABASE_URL.

​
Data Model

Hive stores product state in the dedicated Hive Postgres database:
  • hive_servers
  • hive_world_states
  • hive_world_events
  • hive_crdt_updates
  • hive_npcs
  • hive_npc_needs
  • hive_npc_wallets
  • hive_npc_memories
  • hive_npc_runs
  • hive_ledger_entries
  • hive_inventory_items
  • hive_warehouses
  • hive_trade_offers
  • hive_crop_instances
  • hive_simulation_ticks
  • hive_workflows
  • hive_workflow_runs
  • hive_research_sessions
  • hive_research_session_events
  • hive_members
  • hive_access_requests

​
Database Migrations

Hive Postgres is forward-migrated by the hive-db-migrate Docker Compose job before web, Hive, Hive realtime, or Hive cron processes are allowed to start. The deployment watcher also runs that job explicitly with docker compose run --rm --no-build hive-db-migrate on every blue/green deployment so an already-completed migration container cannot silently satisfy a new deploy. After the explicit run and after Hive services start, the watcher removes the one-shot migrator by Docker Compose project and service labels, including stopped containers named like tuturuuu-hive-db-migrate-*, so the migration job does not stay around consuming host resources or making the cluster look unhealthy. The migration runner records successful work in hive_schema_migrations with a timestamp version, filename, checksum, applied_at, and applied_by. The current apps/hive/db/001_schema.sql file is the immutable baseline; future changes belong in apps/hive/db/migrations/YYYYMMDDHHMMSS_description.sql. Deployment fails when a pending migration checksum disagrees with history, when its timestamp is not newer than the last recorded migration version, or when its timestamp is not newer than the last recorded applied_at time at deployment start. The runner rejects reset-style SQL such as DROP DATABASE, DROP SCHEMA, DROP TABLE, TRUNCATE, ALTER TABLE ... DROP COLUMN, and mutation of hive_schema_migrations. A destructive Hive DB operation requires an explicit DevOps-admin override by setting HIVE_DB_OPERATOR_ROLE=devops-admin, HIVE_DB_ALLOW_DESTRUCTIVE_RESET=1, and HIVE_DB_DEVOPS_ADMIN_APPROVED=1; do not set those values in normal deploy environments. When the migration runner finds an older Hive DB that already has runtime tables but no hive_schema_migrations history, it performs a forward-only compatibility pass before recording the baseline. That pass creates the research-session table when needed and adds missing nullable research_session_id columns to legacy event, NPC run, and simulation tick tables so the immutable baseline can replay without failing on partial indexes. Shared editor state is a Yjs CRDT document per Hive server. Terrain blocks, objects, public NPC projections, farm tiles, and visual warehouse/crop projections live in keyed CRDT maps. Money, item ownership, trade settlement, warehouse transfers, LLM spend, and bankrupt elimination stay relational and transactional in Postgres so currency and inventory cannot be duplicated by CRDT merge behavior. revision is now a compatibility display value backed by the monotonic op_seq audit counter. It is not a write precondition for normal CRDT world edits. Authoritative economy writes must use SQL transactions, idempotency keys where available, and ledger rows. The one-shot Hive backfill path copies legacy Supabase Hive rows into Hive Postgres. After backfill, /api/v1/hive/* routes should write Hive Postgres only, while apps/web internal APIs use the forwarded app-session cookie to resolve the caller and platform-admin status. In Docker production, Hive satellite API rewrites must target the web service through INTERNAL_WEB_API_ORIGIN=http://web-proxy:7803. If that value is empty, the Hive Next.js rewrite can fall back to the public web origin and turn every editor save into a browser-to-Hive-to-public-Web round trip. Hive Docker production builds run the Next.js build through scripts/run-hive-docker-next-build.js under the real node:24 builder stage. The builder still copies Bun from the dependency stage for workspace package builds, but the final Hive next build --turbopack step must be launched with Node and /tmp/web.env instead of bun --env-file so production E2E image bakes do not depend on Bun’s Next.js process shim. Hive graph workflows are server-scoped product data. Platform admins author shared workflow definitions in hive_workflows; enabled Hive members can run enabled, unarchived workflows manually, and every run writes a row in hive_workflow_runs with the input, output, step trace, status, and error message. Workflow definitions are JSON graphs with typed nodes and edges. V1 manual execution disallows cycles, caps graphs at 80 nodes / 120 edges, and uses restricted {{steps.nodeId.output.path}} or {{input.path}} references only. Do not add arbitrary JavaScript evaluation to workflow config. Workflow world_event nodes can also include a worldPatch object with blocks, objects, removeBlockIds, removeObjectIds, or clear: true; the engine applies that patch to the latest server snapshot and persists the result through the same audited world-event path as manual editor saves. Workflow agent_interaction nodes run configured NPC pairs through the same LLM-backed interaction path as Agent Studio pair queues, with deterministic fallback behavior when provider access is unavailable. Mind imports use /api/v1/hive/servers/:serverId/mind-simulations to create NPC agents from a Mind board, create source graph interaction pairs, and save a Hive workflow that stamps the Mind source context before running those pairs. That import route is an admin operation because it creates shared Hive server state. Research sessions are the shared audit spine for multi-agent experiments. A running hive_research_sessions row can be attached to NPC runs, workflow runs, world events, and simulation ticks through nullable research_session_id columns. When a run payload omits researchSessionId, the backend attaches the active running session for that server when one exists. Session events in hive_research_session_events record operational actions such as session creation/update and pair queue start/complete markers. Session exports are available from /api/v1/hive/servers/:serverId/research-sessions/:sessionId/export as JSON or JSONL and should preserve enough identifiers to replay research timelines outside the app. Shared realtime payloads and Hive CRDT helpers live in @tuturuuu/realtime/hive. Keep protocol schemas there when both apps/hive, apps/hive-realtime, or apps/web need the same message or document contract.

​
AI Credit Context

Hive uses the same AI credit and model contracts as the main dashboard. The editor top bar owns the workspace picker, personal/workspace credit source toggle, credit meter, and model picker. The selected workspace is the credit context only; it does not scope Hive servers. Manual NPC runs and manual NPC-to-NPC interactions send creditSource, creditWsId, and model through the Hive internal API. The web route verifies that the signed-in Hive user can access the selected workspace, resolves the requested model against the workspace plan, preflights AI credits, runs the LLM, and deducts credits only after successful model usage. A failed post-generation credit deduction is a request failure: the provider output is not persisted or returned to the caller. If model access is not configured, the route can still persist a deterministic NPC decision for inspectable simulation history. Autonomous NPC interactions use server settings instead of the current browser selection. defaultCreditSource, defaultCreditWsId, and defaultModel define the billing/model context for scheduled simulation work. If the billing workspace is missing or unauthorized, scheduled LLM autonomy is skipped and the normal simulation tick continues. hive_npc_runs stores grouped interaction metadata for manual pair queues, one-shot manual runs, autonomous runs, and workflow-triggered decisions: interaction_id, source/target NPCs, trigger, status, model, provider, token counts, credit source/workspace, deducted credits, errors, and optional research_session_id. Timeline surfaces should group or filter from this persisted run history plus world events, workflow runs, simulation ticks, and session events rather than recomputing transcripts from transient client state.

​
Editor Surface

apps/hive is a hidden-locale Next.js satellite app. The editor uses a full-bleed React Three Fiber viewport, compact top status chips, a bottom tool dock with build/settings controls, an Agent Studio rail, a research timeline drawer, and selected-detail overlays. The 3D world remains mounted while users open agent setup, workflow authoring, timeline observability, AI context, or operations controls. The editor is built on the shared @tuturuuu/satellite workspace shell. Hive uses that shell for collapsible left/right rails, top research overlays, and the bottom tool dock so satellite apps can share layout mechanics while keeping Hive-specific tool density and viewport behavior. Collapsed editor slots must remove hit targets as well as opacity. Hidden Hive toolbars use the satellite shell’s collapsed visibility and pointer-event gating so invisible dock buttons cannot still receive hover, focus, or tooltip events. Hive keeps one editable CRDT world per server. Admins manage that world through server controls: creating a server creates its world, deleting a server deletes the world through database cascade, and clear/reseed actions persist typed audit events plus CRDT updates against the current server document. Manual editor changes persist through the web gateway world-event API. That API stores the authoritative world_data and the matching CRDT state in the same Hive Postgres transaction, then the Hive client only broadcasts the already applied event through hive-realtime. Do not add a second client-side sync.update persistence write after the gateway event succeeds; duplicate writes can churn op_seq, slow visible save completion, and let older world snapshots overwrite newer local edits. Realtime and snapshot consumers must also ignore equal or older revisions so delayed broadcasts cannot revert an optimistic edit that already advanced locally. Keep full-world snapshots in hive_world_states only. hive_world_events should store event metadata and the compact event payload, not another copy of world_data, because normal editor saves can otherwise rewrite and insert the entire voxel world twice on every operation. The 3D editor treats the voxel grid as the source of truth. Perspective comes from the camera and controls, not from rotating the editable world group. World edits should commit only after click/drag threshold handling so orbit, pan, zoom, placement, erasing, moving, and rotating do not conflict with each other. The bottom dock uses explicit persistent panel toggles instead of hover-only expansion. Build catalog, editor settings, and live operations each have a visible icon control. Minimal tile gaps are the default terrain presentation; gapless rendering is an explicit settings toggle. The Settings dock tab owns the continuous 24-hour time slider, auto-time speed, season, weather, camera presets, and simulation/server toggles. Do not restore the older five fixed visible time buttons as the primary time control. Live operations in the dock must use existing Hive snapshot state rather than a new route: world counts, crops, warehouses, server currency, events, online users, realtime status, revision, and the last sync notice. Agent Studio owns multi-agent setup and ordered pair queues: multi-select NPCs, batch role/memory /autonomy edits, round-robin pairs, all-to-all pairs, custom target pairs, run prompt, turn count, and current AI context. NPC Lab remains the selected-agent detail editor only. When no NPC is selected, it should show a selection prompt instead of silently mutating the first NPC in the server. The editor uses a single Research Studio panel state instead of separate full-screen World / Workflow graph / Timeline destinations. Workflow graph is a focused overlay on top of the persistent world viewport. Timeline is a drawer that reads /api/v1/hive/servers/:serverId/timeline, filters by research session and run metadata, and expands rows into input/output context, status, model/provider, credits, and export identifiers. Workflow mode is still a 2D React Flow graph builder for manual Hive automations, but it must reuse the same AI context, run trace, and research timeline contracts as NPC pair queues. Embedded apps/web Hive routes should load @xyflow/react/dist/style.css from the Hive route segment layout rather than the root web layout, so React Flow styles are available for workflow mode without adding that CSS to unrelated dashboard routes. Admins can drag nodes from the palette, use starter templates, edit JSON config in the inspector, save shared workflows, and run them against the selected server. Members see the same graph read-only and can manually run saved workflows. Workflow runs apply live effects through the same gateway-backed Hive actions used elsewhere: world events, simulation ticks, NPC decision records, farming, warehouses, and trades. Effects are audited through the workflow run trace, research session timeline, and existing Hive event/economy tables; v1 has no schedule, webhook trigger, retry queue, credential vault, or rollback approval layer. Starter workflow templates should demonstrate a real server-side use case, not just create trace rows. The farm cycle template plants a relational crop, then uses a world_event.worldPatch step to stamp a visible crop plot into the Hive world. The cleanup template removes that starter plot by id and records the maintenance event. Keep manual and autonomous interaction rows grouped by interaction_id whenever a deeper transcript view is added. Pair queue runs must execute pairs in request order and return partial failures without dropping successful earlier pairs. NPC Lab is a draft editor for the selected NPC only. Identity, brain/model, behavior/autonomy, memory/prompt flags, system prompt, and interaction controls belong in the lab tabs. Save/Reset should protect large text and settings edits from accidental persistence, while manual run buttons can launch one-shot decisions or targeted NPC-to-NPC interactions using the current AI credit context. The chat composer is opt-in from the editor chrome button, and the mini-map is a collapsible viewport overlay. If all Hive servers are deleted, the editor must clear local world, NPC, revision, selection, presence, and awareness state so it does not keep rendering the last server snapshot. Time of day still maps to authored scene backdrops and lerped lighting, fog, background, and cloud tint. Weather and season controls layer visual atmosphere over that time base without changing the durable CRDT world snapshot. Realtime multiplayer awareness is ephemeral. Avatar badges, terrain cursors, selection rings, active tool state, camera focus, and in-world user markers are sent as TTL-based awareness updates and must not be persisted into durable world snapshots. Offline world edits are queued as CRDT updates and replayed on reconnect. The client uses token refresh, exponential backoff, state-vector resync, throttled cursor/position updates, and local actor echo suppression to keep the research surface responsive during reconnects and slow-client conditions. Client data access must go through @tuturuuu/internal-api helpers and TanStack Query. Do not add raw client fetch() calls in the satellite app.

​
Testing

Hive has app-local Playwright coverage in apps/hive/e2e. The suite assumes the local web app on https://tuturuuu.localhost and Hive app on https://hive.tuturuuu.localhost are already running through Portless; it does not auto-start dev servers. Root bun test:e2e intentionally runs the self-contained Dockerized web E2E suite instead; after starting the Portless services for Hive, run Hive coverage with: 
bun --filter @tuturuuu/hive test:e2e
The authenticated setup uses the web app’s development session endpoint for the seeded local@tuturuuu.com account before opening Hive. Override WEB_BASE_URL or HIVE_BASE_URL when bypassing Portless or using direct fallback ports.

​
Economy And Farming

Each Hive server has a total currency pool, NPC wallets, inventories, warehouses, trade offers, crops, and ledger-backed transfers. NPCs have hunger, energy, morale, upkeep, and optional LLM spend budgets. Crop rules cover soil/water/fertilizer state, growth stages, harvest yields, and day-cycle simulation. Manual tools can plant, water, harvest, deposit, withdraw, and settle trades. Autonomous ticks can advance crops, choose NPC jobs, apply upkeep, record LLM run costs, credit earnings, and eliminate NPCs whose wallets cannot cover required costs. Cron-backed Hive simulation is intentionally disabled by default. Enable global Hive cron and per-server autonomous simulation through Hive settings only after budget limits, tick interval, and max LLM spend have been reviewed.

​
LLM Providers

Ollama is optional and disabled by default. Docker can start the hive-ollama profile, and Hive settings can enable the local model id exactly as gemma4. The app loads the model through Ollama’s generate API, generates through /api/generate, and unloads by sending keep_alive: 0. Every Mira-powered LLM path must be gated by an exact @tuturuuu.com email check. Subdomains such as @xwf.tuturuuu.com are not Tuturuuu-internal for Mira access.