SENTRA / BOT Operational signal: persistent agents · memory · routines · computers · human authority Sentra Bot The autonomous intelligence layer of Sentra Artificial Intelligence.                      PERCEIVE → REASON → VERIFY → HUMAN AUTHORITY → ACT

---

01 / ORIGIN SIGNAL

Sentra Bot is the operating layer for persistent, composable AI teammates you actually own — agents that can hold memory, execute routines, use computers, and work against your own models, your own data, and your own machines.

The repository is not a single chatbot and not a thin model wrapper. It contains the full runtime surface: API, web, desktop, and mobile clients, background worker, job orchestration, memory, computer providers, connectors, artifacts, realtime infrastructure, and a role-template catalog. Clinical write access is out of scope.

The objective is precise: make autonomous intelligence useful without making authority invisible.

LAYER I · INTELLIGENCE Agent runtime, typed orchestration, routines, memory, search, connections, artifacts, and model access.

LAYER II · COMPUTERS Owned or remote execution surfaces: Docker, E2B, Daytona, Box, desktop, and deterministic fake providers for tests.

LAYER III · AUTHORITY Authentication, membership, secrets, auditability, explicit boundaries, and human review before consequential action.

Persistent does not mean unbounded. Autonomous does not mean unaudited.

---

02 / DOCTRINE

Important

Autonomy is a capability. Authority is a boundary. Sentra Bot may perceive, reason, prepare, and execute inside an approved scope; consequential authority remains explicit.

THE HUMAN HOLDS THE KEY Machines propose; a human reviews, verifies, and acts. Nothing signs itself. In clinical paths, final authority is deliberately non-delegable.	READ-ONLY UNTIL PROVEN Clinical integrations begin strictly read-only. No write reaches a patient record until the read path has been verified end to end.
BRING YOUR OWN MODEL & COMPUTER Models and computer providers remain replaceable. Run locally, use a remote sandbox, or point clients at a central deployment without binding the system to one vendor.	SEPARABLE BY DESIGN Reasoning, memory, orchestration, computers, realtime, security, and persistence are independent surfaces that can be inspected or replaced without rewriting the whole system.
DURABLE STATE OVER EPHEMERAL COMPUTE A sandbox is where work runs, not where truth lives. Workspace state checkpoints back to durable storage; remote computers are runtime cache.	NO MAGIC WITHOUT VERIFICATION The system should expose where work runs, where state lives, what boundary applies, and which human or policy controls the next action.

---

03 / SYSTEM TOPOLOGY

LIVE TOPOLOGY // CONTROL & EXECUTION PLANE

%%{init: {"flowchart": {"htmlLabels": false, "padding": 20}, "themeVariables": {"fontFamily": "monospace", "fontSize": "11px"}}}%%
flowchart TB
  HUMAN["HUMAN / OPERATOR"]
  CLIENT["WEB / ELECTRON CLIENT"]
  API["API · :3100 · HONO + ORPC"]
  DB["POSTGRESQL 16"]
  JOBS["GRAPHILE JOB QUEUE"]
  WORKER["BACKGROUND WORKER"]
  SUP["SANDBOX SUPERVISOR · :7091"]
  COMPUTER["BOT COMPUTER"]
  DATA["DURABLE DATA_DIR"]

  HUMAN -->|intent / review| CLIENT
  CLIENT -->|/api · /rpc · /health| API
  API -->|Prisma / SQL| DB
  API -->|publish work| JOBS
  JOBS --> WORKER
  WORKER -->|sandbox API| SUP
  SUP -->|spawn / manage| COMPUTER
  COMPUTER -->|checkpoint workspace| DATA
  DATA -->|restore state| COMPUTER
  DB -. LISTEN / NOTIFY .-> API

  classDef authority fill:#0D1117,stroke:#F59E0B,color:#ffffff,stroke-width:2px;
  classDef agent fill:#0D1117,stroke:#8B5CF6,color:#ffffff,stroke-width:2px;
  classDef control fill:#0D1117,stroke:#14B8A6,color:#ffffff,stroke-width:2px;
  classDef core fill:#0D1117,stroke:#5B8CFF,color:#ffffff,stroke-width:2px;
  classDef shared fill:#0D1117,stroke:#64748B,color:#ffffff,stroke-width:1.5px;
  classDef surface fill:#0D1117,stroke:#22D3EE,color:#ffffff,stroke-width:1.5px;

  class HUMAN authority;
  class WORKER,COMPUTER agent;
  class SUP,JOBS control;
  class API core;
  class DB,DATA shared;
  class CLIENT surface;

Loading

Runtime flow

1. Client calls the API over typed RPC under /rpc/*.
2. API enforces authentication and workspace membership.
3. State persists to Postgres through Prisma.
4. Thread events fan out through Postgres LISTEN/NOTIFY, with in-memory fanout available in tests.
5. Background work is published to the configured job driver and consumed by the worker.
6. Bot computers execute inside the configured sandbox provider.
7. Workspace state checkpoints back to durable DATA_DIR.

Cloud sandboxes are runtime cache. Durable state is the source of truth.

---

04 / THE ENGINE ROOM

APPLICATIONS apps/api — HTTP API, auth, typed orchestration apps/web — React + Vite client apps/desktop — Electron shell for Sentra Bot apps/mobile — Expo client (same API contracts) apps/worker — routines, wakeups, jobs, run continuation apps/site — marketing site (npm package name cora) apps/docs — public Mintlify documentation	CORE PACKAGES adapter-kit — ports and interfaces adapters — concrete execution + provider adapters contracts — shared typed RPC contracts core — pure domain logic db — Prisma schema, migrations, repositories memory — per-bot markdown memory bot-templates — 66 Chief-of-Staff role packages
SHARED SURFACES auth — Better Auth sessions + signup policy chat-ui — cross-platform markdown rendering ui-tokens — design tokens / theme primitives ui-web — shared React UI components testkit — topology, canary, computer E2E, performance	INFRASTRUCTURE infra/compose — Docker Compose topologies, Caddy, deployment assets infra/sandboxes — bot computer images + supervisor infra/updater — Compose updater sidecar scripts — backup / restore utilities

REPOSITORY MAP // CANONICAL LAYOUT

sentrabot/
├── apps/
│   ├── api/          # HTTP API + auth + orchestration (Hono, port 3100)
│   ├── web/          # React + Vite client (port 5173)
│   ├── desktop/      # Electron shell hosting the web client
│   ├── mobile/       # Expo client
│   ├── worker/       # Background worker: routines, wakeups, jobs
│   ├── site/         # Marketing site
│   └── docs/         # Public Mintlify docs
├── packages/
│   ├── adapter-kit/  # Shared ports & interfaces
│   ├── adapters/     # Sandboxes, executors, realtime, connectors, secrets
│   ├── auth/         # Better Auth wiring
│   ├── bot-templates/# Role catalog (66 packages)
│   ├── chat-ui/      # Cross-platform markdown rendering
│   ├── contracts/    # Shared typed RPC / service contracts
│   ├── core/         # Pure domain logic
│   ├── db/           # Prisma schema + migrations + repositories
│   ├── memory/       # Per-bot markdown memory
│   ├── testkit/      # Test and performance harnesses
│   ├── ui-tokens/    # Design tokens / theme primitives
│   └── ui-web/       # Shared React UI components
├── infra/
│   ├── compose/      # Compose topologies + Dockerfile + Caddy + DEPLOY.md
│   ├── sandboxes/    # Computer, desktop, supervisor images
│   └── updater/      # Product-update sidecar
├── docs/             # Architecture, operator docs, requirements package
└── scripts/          # backup.sh / restore.sh

apps/api · PORT 3100 Hono + @orpc/server. Owns auth routes, typed RPC, trusted-origin CORS, health reporting, and wiring across database, realtime, jobs, sandboxes, secrets, memory, artifacts, runtime, and auth.	apps/web · PORT 5173 React + Vite SPA. Talks to the API over RPC; Compose proxies /api and /rpc to the API container.
apps/desktop Electron shell with productName: "Sentra Bot". It is a client of the same API — not a second backend — and supports the trusted-host desktop sandbox path.	apps/worker Long-running process that consumes the job queue, executes bot runs, reconciles scheduled routines, handles wakeups, and shares the same packages as the API.

---

05 / DATA & MEMORY PLANE

PRISMA · POSTGRESQL 16 · GRAPHILE · LISTEN/NOTIFY · DURABLE BOT STATE

DATABASE ORM: Prisma Schema: packages/db/prisma/schema.prisma Migrations: packages/db/prisma/migrations/ Core models include user, session, workspace, membership, bot, thread, message, run, event, routine, computer, lease, artifact, secret, model credential, connection, memory document, usage record, and deployment settings.	MEMORY & DURABLE STATE Per-bot markdown memory lives behind the memory package. Computer workspaces checkpoint back to DATA_DIR, keeping persistent state independent from ephemeral cloud sandboxes.
JOBS WAKEUP_DRIVER=graphile uses a Postgres-backed Graphile Worker queue. WAKEUP_DRIVER=memory swaps in an in-memory queue for tests and development.	REALTIME Thread events fan out through Postgres LISTEN/NOTIFY via PostgresRealtimeFanout, with an in-memory implementation when no pool exists.

Database backends

Backend	Connection posture	Use
Local Compose Postgres 16	127.0.0.1:5433, named volume pgdata	Local / self-hosted
Supabase	pooled DATABASE_URL on 6543; direct DIRECT_URL on 5432	Central deployment

Caution

Prisma migrations run against DIRECT_URL. A pooled PgBouncer connection is not the migration surface.

---

06 / COMPUTER & DEPLOYMENT MATRIX

LOCAL DEV docker-compose.yml Postgres, supervisor, computer image, data-init, API, worker, and web. Postgres is published on loopback only. The supervisor — not the API — owns the Docker socket.

SINGLE-VM PROD docker-compose.prod.yml Postgres + API + worker + web + Caddy. Hardened container posture with no-new-privileges, dropped capabilities, limits, internal network, and health checks.

CENTRAL + SUPABASE docker-compose.supabase.yml API + worker + web + Caddy, without a local Postgres container. End users need only the web URL or desktop client pointed at the central origin.

Bot computer providers

Provider	Where bots run	Notes
docker	Local Compose supervisor	Default local self-hosted path
e2b	Remote E2B cloud desktop	Recommended public / multi-user path; workspace checkpointed durably
daytona	Daytona sandboxes	Remote computer contract
box	Box by ASCII managed desktop	Shared desktop, noEnv, 2h TTL refresh
desktop	API / worker host	Trusted owned host only
fake	No real computer	Tests only

EDGE & HOST POSTURE

Caddy

/health, /api/*, and /rpc/* route to api:3100; everything else routes to web:5173. zstd + gzip are enabled. CADDYFILE_PATH and Caddyfile.cloudflare.example support a Cloudflare allowlist front for Full (strict) TLS.

Host hardening

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh

The script disables SSH passwords/root login, rate-limits SSH, configures UFW allowlists, fail2ban, unattended upgrades, AppArmor, and audit rules. docker-daemon.json enables live-restore and bounded logs.

Backup / restore

./scripts/backup.sh
./scripts/restore.sh backups/<stamp>

Production uses backup-prod.sh with a systemd timer, seven-day rotation, and mode 0600.

---

07 / CONFIGURATION SURFACE

Warning

Copy .env.example to .env. Never commit .env. It is gitignored and excluded from the Docker build context.

Variable	Purpose
DATABASE_URL	App DB connection; Supabase uses pooled / transaction port 6543.
DIRECT_URL	Direct DB URL on 5432 for Prisma migrations.
BETTER_AUTH_SECRET	Auth secret, minimum 32 characters.
BETTER_AUTH_URL / WEB_ORIGIN / API_URL	Public origins for auth, cookies, and CORS.
ENCRYPTION_KEY	Encryption for stored credentials.
DATA_DIR	Durable bot homes, browser profiles, artifacts, workspace state.
SIGNUPS_ENABLED / SIGNUP_ALLOWLIST	Registration control.
SANDBOX_PROVIDER	docker / e2b / daytona / box / desktop / fake.
SANDBOX_SUPERVISOR_URL / SANDBOX_SUPERVISOR_TOKEN	Supervisor endpoint and shared credential.
SANDBOX_IDLE_MS / SANDBOX_COMMAND_TIMEOUT_MS	Sandbox idle and command timing.
AGENT_RUNTIME	pi for production; scripted for tests.
WAKEUP_DRIVER	graphile for production; memory for tests.
OPENROUTER_API_KEY / PI_DEFAULT_PROVIDER / PI_DEFAULT_MODEL	Model provider configuration and defaults.
E2B_API_KEY / DAYTONA_API_KEY / DAYTONA_API_URL / DAYTONA_TARGET / BOX_API_KEY / BOX_API_URL	Computer-provider credentials.
COMPOSIO_API_KEY	Optional plugins / connectors.
EXPO_PUBLIC_API_URL / SENTRABOT_WEB_URL	Mobile production origin and Electron web-URL override.
SMTP_URL / VAPID_*	Optional email and push.
OTEL_EXPORTER_OTLP_ENDPOINT / LOG_LEVEL	Observability.

---

08 / RUN PROTOCOL

FULL LOCAL TOPOLOGY cp .env.example .env # set BETTER_AUTH_SECRET, ENCRYPTION_KEY, OPENROUTER_API_KEY pnpm install pnpm sandbox:build docker compose --env-file .env \ -f infra/compose/docker-compose.yml \ up --build # open http://127.0.0.1:5173 The first registered user becomes the deployment owner.	SOURCE DEVELOPMENT cp .env.example .env pnpm install pnpm sandbox:build pnpm dev # turbo: api + worker + web (+ supervisor) # open http://127.0.0.1:5173
PRODUCTION docker compose --env-file .env \ -f infra/compose/docker-compose.prod.yml \ up -d --build curl --fail https://app.example.com/health	CENTRAL BACKEND Set pooled DATABASE_URL and direct DIRECT_URL. Deploy Prisma migrations. Start docker-compose.supabase.yml. pnpm --filter @sentrabot/db exec prisma migrate deploy docker compose --env-file .env \ -f infra/compose/docker-compose.supabase.yml \ up -d --build

Database migrations

pnpm db:generate
pnpm db:migrate

# production alternative
pnpm --filter @sentrabot/db exec prisma migrate deploy

---

09 / VERIFICATION GATE

pnpm check                 # type-check all packages
pnpm lint                  # biome
pnpm test                  # vitest unit tests
pnpm test:integration      # integration harness
pnpm test:e2e
pnpm test:topology
pnpm test:canary
pnpm test:computer
pnpm perf:desktop
pnpm perf:compare

CI in .github/workflows/ci.yml runs check, lint, and test on pull requests and pushes. Playwright and nightly verification cover browser and longer-path checks.

PROMOTION LOGIC // BUILD → VERIFY → OPERATE

%%{init: {"flowchart": {"htmlLabels": false, "padding": 20}, "themeVariables": {"fontFamily": "monospace", "fontSize": "12px"}}}%%
flowchart TB
  BUILD["BUILD"]
  CHECK["TYPECHECK / LINT"]
  TEST["UNIT / INTEGRATION"]
  E2E["E2E / TOPOLOGY / CANARY"]
  OPERATE["OPERATE"]
  STOP["STOP / REPAIR"]

  BUILD --> CHECK
  CHECK --> TEST
  TEST --> E2E
  E2E -->|verified| OPERATE
  CHECK -. fail .-> STOP
  TEST -. fail .-> STOP
  E2E -. fail .-> STOP
  STOP --> BUILD

  classDef authority fill:#0D1117,stroke:#F59E0B,color:#ffffff,stroke-width:2px;
  classDef agent fill:#0D1117,stroke:#8B5CF6,color:#ffffff,stroke-width:2px;
  classDef control fill:#0D1117,stroke:#14B8A6,color:#ffffff,stroke-width:2px;
  classDef core fill:#0D1117,stroke:#5B8CFF,color:#ffffff,stroke-width:2px;
  classDef surface fill:#0D1117,stroke:#22D3EE,color:#ffffff,stroke-width:1.5px;

  class OPERATE authority;
  class TEST agent;
  class CHECK,E2E control;
  class BUILD core;
  class STOP surface;

Loading

---

10 / CLINICAL BOUNDARY

Caution

Sentra Bot is not a hospital information system and has no clinical write path.

This repository does not ship an electronic medical record (RME) adapter. Healthcare role templates in packages/bot-templates are operating-layer prompts and policies, not access to a patient record.

The product doctrine for any future clinical integration remains:

MANUAL LOGIN
    ↓
ONE PATIENT
    ↓
READ-ONLY RECONNAISSANCE
    ↓
STRUCTURED JSON
    ↓
MANUAL VERIFICATION
    ↓
NO WRITE

• Clinical credentials are never requested, stored, or committed in this baseline.
• Do not document a shipped RME bridge until the adapter exists in code and is verified end to end.

Clinical autonomy does not begin by granting write access. It begins by proving a read path — and that path is not in this repository yet.

---

11 / SENTRA OPERATING STANDARD

No autonomy without a boundary.
No persistent agent without durable state.
No computer execution without an explicit provider.
No clinical write before the read path is proven.
No secret in source control.
No consequential action without human authority.

WHO HOLDS AUTHORITY? The relevant human operator or reviewer. In clinical paths, the human boundary is terminal.	WHERE DOES STATE LIVE? Postgres and durable DATA_DIR — not an ephemeral cloud computer.
WHERE DOES WORK RUN? Inside the configured computer provider: Docker, E2B, Daytona, Box, desktop, or a fake test surface.	HOW IS IT VERIFIED? Typed contracts, deterministic tests, topology checks, canaries, runtime health, and explicit human review where consequences require it.

---

12 / PACKAGE NAMESPACE & LICENSE

The product is Sentra Bot.

Internal packages use the @sentrabot/* namespace. Historical @rakazo/* identifiers from the upstream codebase do not exist in this repository.

Engineering requirements (ISO/IEC/IEEE 29148) live in docs/requirements/. Runtime topology lives in docs/architecture.md.

License: Apache 2.0 — see LICENSE and NOTICE.

Operational contracts and security boundaries live in:

• SECURITY.md
• AGENTS.md
• .env.example
• infrastructure deployment documentation under infra/compose/

Never commit secrets.

---

13 / CREDIT

Rakazo Upstream open-source agent platform.

Sentra Bot is built on the shoulders of Rakazo — the upstream platform from which the repository inherits packaging, adapter architecture, and the persistent-bot engine. We thank the Rakazo authors and community. Everything Sentra-specific — Sentra Bot branding, the clinical read-only direction, and the central Supabase deployment path — is layered on top of that foundation.

---

14 / INSTRUMENTATION

ACTUAL REPOSITORY SURFACE · SENTRA BOT

RUNTIME & APPLICATIONS Node.js 22 · Hono · @orpc/server · React · Vite · Electron · background worker	DATA & REALTIME PostgreSQL 16 · Supabase · Prisma · Graphile Worker · LISTEN/NOTIFY · durable DATA_DIR
AGENT & MEMORY Pi runtime · scripted test runtime · per-bot markdown memory · routines · wakeups · artifacts · connectors	COMPUTER PROVIDERS Docker · E2B · Daytona · Box · desktop host · fake test provider · supervisor API
SECURITY & AUTHORITY Better Auth · membership enforcement · encryption key · secret store · read-only clinical boundary · host hardening · human authority	QUALITY & OPERATIONS Biome · Vitest · Playwright · integration harness · topology tests · canary tests · computer E2E · performance checks · GitHub Actions

---

Sentra Bot · Intelligence for Autonomy.
Part of the Sentra Artificial Intelligence ecosystem.
_{// persistent intelligence. explicit authority.}