Bloby

A self-hosted AI agent that runs on the user's machine with a full-stack workspace it can modify, a chat interface for remote control, and a relay system for public access via custom domains.

System Overview

Bloby is three separate codebases working together:

1. Bloby Bot (this repo) -- runs on the user's machine. Supervisor process, worker API, workspace app, chat UI.
2. Bloby Relay (separate server at api.bloby.bot) -- optional cloud service that maps username.bloby.bot to the user's Cloudflare tunnel. Routes HTTP and WebSocket traffic. Only used with Quick Tunnels.
3. Cloudflare Tunnel -- exposes localhost:3000 to the internet. Two modes:
   • Quick Tunnel -- zero-config, no account needed, random *.trycloudflare.com URL that changes on restart. Optionally paired with the relay for a permanent domain.
   • Named Tunnel -- persistent URL with the user's own domain. Requires a Cloudflare account and DNS setup. No relay needed.

The user chooses their tunnel mode during bloby init via an interactive selector.

Process Architecture

When bloby start runs, the CLI spawns a single supervisor process. The supervisor runs the worker API in-process, spawns the backend as a child process, and manages the full lifecycle:

CLI (bin/cli.js)
  |
  spawns
  v
Supervisor (supervisor/index.ts)        port 3000    HTTP server + WebSocket + worker API (in-process)
  |
  +-- Worker routes (worker/index.ts)   in-process   Express API, SQLite, auth, conversations
  +-- Vite Dev Server                   port 3002    Serves workspace/client with HMR
  +-- Backend (workspace/backend/)      port 3004    User's custom Express server (child process)
  +-- cloudflared (tunnel)              --           Exposes port 3000 to the internet (quick or named)
  +-- Scheduler (supervisor/scheduler)  --           PULSE + CRON job runner (in-process)

Port allocation: base port (default 3000), Vite = base+2, backend = base+4.

The backend child process auto-restarts up to 3 times on crash (reset counter if alive >30s). The supervisor catches SIGINT/SIGTERM and tears everything down gracefully.

Supervisor (supervisor/index.ts)

The supervisor is a raw http.createServer that routes every incoming request:

| Path | Target | Notes | |---|---|---| | /bloby/widget.js | Direct file serve | Chat bubble script, no-cache | | /sw.js, /bloby/sw.js | Embedded service worker | PWA + push notification support | | /app/api/* | Backend (port 3004) | Strips /app/api prefix before forwarding | | /api/* | Worker Express app (in-process) | Auth middleware checks Bearer token on mutations | | /bloby/* | Static files from dist-bloby/ | Pre-built chat SPA. HTML: no-cache. Hashed assets: immutable, 1yr max-age | | Everything else | Vite dev server (port 3002) | Dashboard + HMR |

WebSocket upgrades:

• /bloby/ws -- Bloby chat. Auth-gated via query param token. Handled by an in-process WebSocketServer.
• Everything else -- proxied to Vite dev server for HMR.

The supervisor also:

• Manages the Cloudflare tunnel lifecycle (start, stop, health watchdog every 30s) for both quick and named tunnels
• Registers with the relay and maintains heartbeats (quick tunnel mode only)
• Runs the Claude Agent SDK when users send chat messages
• Restarts the backend process when Claude edits workspace files
• Broadcasts app:hmr-update to all connected dashboard clients after file changes
• Watches workspace/backend/ for .ts/.js/.json changes and auto-restarts the backend
• Watches workspace root for .env changes (backend restart), .restart trigger, and .update trigger (deferred bloby update)
• Runs the PULSE/CRON scheduler
• Serves an embedded service worker for PWA + push notifications

Auth Middleware

The supervisor validates Bearer tokens on /api/* POST/PUT/DELETE requests by calling the worker's getSession() database function directly (no HTTP round-trip). Token results are cached for 60 seconds. Auth-exempt routes (login, onboard, health, push, auth endpoints) skip this check.

The /app/api/* route has no auth -- the user's workspace backend handles its own authentication.

Worker (worker/index.ts)

Express app that runs in-process within the supervisor (no separate child process). Owns the database and all platform API logic. The supervisor calls createWorkerApp() at startup, which initializes the database, VAPID keys, and file storage, then returns the Express app. All API responses set Cache-Control: no-store, no-cache, must-revalidate to prevent stale responses through the relay/CDN.

Database: ~/.bloby/memory.db (SQLite via better-sqlite3, WAL mode)

Tables:

• conversations -- chat sessions (id, title, model, session_id, timestamps)
• messages -- individual messages (role, content, tokens_in, tokens_out, model, audio_data, attachments as JSON)
• settings -- key-value store (onboard config, provider, model, portal credentials, etc.)
• sessions -- auth tokens with 7-day expiry
• push_subscriptions -- Web Push endpoints with VAPID keys (endpoint, keys_p256dh, keys_auth)

Auto-migrations add missing columns on startup (session_id, audio_data, attachments).

Key endpoints:

• /api/conversations -- CRUD for conversations and messages (paginated with before cursor)
• /api/settings -- key-value read/write
• /api/onboard -- saves wizard configuration (provider, model, portal password, whisper key, names)
• /api/onboard/status -- returns current setup state (names, portal, whisper, provider, handle)
• /api/portal/login -- password auth (POST with JSON body or GET with Basic Auth header)
• /api/portal/validate-token -- session token validation (POST or GET)
• /api/portal/verify-password -- check password without creating session
• /api/whisper/transcribe -- audio-to-text via OpenAI Whisper API (10MB limit)
• /api/handle/* -- check availability, register, change relay handles
• /api/context/current, /api/context/set, /api/context/clear -- tracks which conversation is active
• /api/auth/claude/* -- Claude OAuth start, exchange, status
• /api/auth/codex/* -- OpenAI OAuth start, cancel, status
• /api/push/* -- VAPID public key, subscribe, unsubscribe, send notifications, status
• /api/files/* -- static file serving from attachment storage
• /api/health -- health check

Portal passwords are hashed with scrypt (random 16-byte salt, stored as salt:hash).

Workspace

The workspace is a full-stack app template that Claude can freely modify. It lives at workspace/ in the project and gets copied to ~/.bloby/workspace/ on first install.

workspace/
  client/             React + Vite + Tailwind dashboard
    src/App.tsx        Main app entry (error boundary, rebuild overlay, onboard iframe)
    index.html         PWA manifest, service worker registration, widget script
  backend/
    index.ts           Express server template (reads .env, opens app.db)
  .env                 Environment variables for the backend
  app.db               SQLite database for workspace data
  MYSELF.md            Agent identity and personality
  MYHUMAN.md           Everything the agent knows about the user
  MEMORY.md            Long-term curated knowledge
  PULSE.json           Periodic wake-up config (interval, quiet hours)
  CRONS.json           Scheduled tasks with cron expressions
  memory/              Daily notes (YYYY-MM-DD.md files, append-only)
  skills/              Plugin directories with .claude-plugin/plugin.json
  MCP.json             MCP server configuration (optional)
  files/               Attachment storage (audio, images, documents)

The backend runs on port 3004, accessed at /app/api/* through the supervisor proxy. The /app/api prefix is stripped before reaching the backend, so routes are defined as /health not /app/api/health.

The frontend is served by Vite with HMR. When Claude edits files, Vite picks up changes instantly for the frontend. The supervisor restarts the backend process after any file write by the agent.

The workspace is the only directory Claude is allowed to modify. The system prompt explicitly tells it never to touch supervisor/, worker/, shared/, or bin/.

Agent Memory System

The agent has no persistent memory between sessions except through files in the workspace:

| File | Purpose | |---|---| | MYSELF.md | Agent identity, personality, operating manual. The agent's self-authored description of who it is. | | MYHUMAN.md | Profile of the user -- preferences, context, everything the agent has learned about them. | | MEMORY.md | Long-term curated knowledge. Distilled from daily notes into durable insights. | | memory/YYYY-MM-DD.md | Daily notes. Raw, append-only log of events and observations for that day. |

All four are injected into the system prompt at query time by bloby-agent.ts. The agent reads and writes these files itself -- there's no external process managing them.

Scheduler (supervisor/scheduler.ts)

The scheduler runs in-process within the supervisor, checking every 60 seconds.

PULSE

Periodic wake-ups configured in workspace/PULSE.json:

{ "enabled": true, "intervalMinutes": 30, "quietHours": { "start": "23:00", "end": "07:00" } }

When a pulse fires, the scheduler triggers the agent with a system-generated prompt. The agent can check in, review notes, or take proactive action. Quiet hours suppress pulses.

CRONS

Scheduled tasks configured in workspace/CRONS.json:

[{ "id": "...", "schedule": "0 9 * * *", "task": "Check the weather", "enabled": true, "oneShot": false }]

Uses cron-parser to match cron expressions against the current minute. One-shot crons are auto-removed after firing.

When a cron or pulse fires:

1. The scheduler calls startBlobyAgentQuery with the task
2. It extracts <Message> blocks from the agent's response
3. It sends push notifications for those messages
4. If the agent used file tools (Write/Edit), the backend is restarted

Skills & Plugins

The agent auto-discovers skills in workspace/skills/. Each skill is a folder containing .claude-plugin/plugin.json. These are loaded as tool plugins when the agent starts a query.

MCP servers can be configured in workspace/MCP.json. The agent loads them at query time and logs which servers are active.

Web Push Notifications

The worker generates VAPID keys on first boot and stores them in settings. The chat SPA requests notification permission, subscribes via the Push API, and sends the subscription endpoint + keys to the worker.

When the scheduler (or any server-side event) needs to notify the user, it calls POST /api/push/send which fans out web-push notifications to all stored subscriptions. Expired subscriptions are auto-cleaned.

Bloby Chat

The chat UI is a standalone React SPA built separately (vite.bloby.config.ts -> dist-bloby/). It runs inside an iframe injected by widget.js on the dashboard.

Why an iframe?

If Claude introduces a bug that crashes the dashboard, the chat stays alive. The user can still talk to Claude and ask for a fix. The chat and dashboard are completely isolated -- different React trees, different build outputs, different error boundaries.

Widget (supervisor/widget.js)

Vanilla JS that injects:

• A floating video bubble (60px, bottom-right corner, with Safari fallback image)
• A slide-out panel (480px wide, full screen on mobile) containing the iframe at /bloby/
• A backdrop for dismissal
• Keyboard dismiss (Escape key)

Communicates with the iframe via postMessage:

• bloby:close -- iframe requests panel close
• bloby:install-app -- iframe requests PWA install prompt
• bloby:show-ios-install -- iframe requests iOS-specific install modal
• bloby:onboard-complete -- iframe notifies onboarding finished, reloads bubble
• bloby:rebuilding -- agent started modifying files, show rebuild overlay
• bloby:rebuilt -- rebuild complete, dashboard should reload
• bloby:build-error -- build failed, show error overlay
• bloby:hmr-update -- supervisor notifies dashboard of file changes

Panel state persisted in localStorage (bloby_widget_open) to survive HMR reloads. Bubble hidden during onboarding.

Chat Protocol (WebSocket)

Client -> Server:

• user:message -- { content, conversationId?, attachments? } where attachments are { type, name, mediaType, data(base64) }
• user:stop -- abort current agent query
• user:clear-context -- clear conversation and agent session
• whisper:transcribe -- { audio: base64 } (bypasses relay POST limitation)
• settings:save -- { ...settings } (bypasses relay POST limitation)

Server -> Client:

• bot:typing -- agent started
• bot:token -- streamed text chunk
• bot:tool -- tool invocation (name, status)
• bot:response -- final complete response
• bot:error -- error message
• bot:done -- query complete, includes usedFileTools flag
• chat:conversation-created -- new conversation ID assigned
• chat:sync -- message from another connected client
• chat:state -- stream state on reconnect (catches up missed tokens)
• chat:cleared -- context was cleared
• app:hmr-update -- file changes detected, dashboard should reload

WebSocket Client (ws-client.ts)

Auto-reconnects with exponential backoff (1s -> 8s cap). Queues messages during disconnection. Sends heartbeat pings every 25 seconds. Auth token passed as query parameter on connect.

PWA Support

The chat SPA handles:

• beforeinstallprompt for Android PWA install
• iOS-specific install modal with step-by-step instructions
• Standalone mode detection
• Push notification subscription on first load

Claude Agent SDK Integration (supervisor/bloby-agent.ts)

When the configured provider is Anthropic, chat messages are routed through the Claude Agent SDK instead of a raw API call.

• Runs with permissionMode: bypassPermissions -- full tool access, no confirmation prompts
• Working directory: workspace/
• Max 50 turns per query
• System prompt: Claude Code preset + custom addendum from worker/prompts/bloby-system-prompt.txt
• Sessions tracked in-memory (conversationId -> sessionId) for multi-turn context
• Memory files (MYSELF.md, MYHUMAN.md, MEMORY.md, PULSE.json, CRONS.json) injected into system prompt
• Skills auto-discovered from workspace/skills/
• MCP servers loaded from workspace/MCP.json
• File attachments encoded as base64 documents/images in the SDK prompt

The agent has access to all Claude Code tools (Read, Write, Edit, Bash, Grep, Glob, etc.). After a query completes, the supervisor checks if Write or Edit tools were used. If so, it restarts the backend and broadcasts an HMR update.

OAuth tokens are managed by worker/claude-auth.ts using PKCE flow against claude.ai. Tokens are stored in the macOS Keychain (primary) or ~/.claude/.credentials.json (fallback). Refresh tokens are used to renew access tokens with a 5-minute expiry buffer.

For non-Anthropic providers (OpenAI, Ollama), the supervisor falls back to ai.chat() with simple message history -- no agent tools, no file access.

Tunnel + Relay System

Problem

The user's machine is behind NAT. We need a public URL so they can access their bot from their phone.

Tunnel Modes

The user selects a tunnel mode during bloby init. The mode is stored in ~/.bloby/config.json as tunnel.mode.

Quick Tunnel (default)

Zero configuration. No Cloudflare account needed.

Phone browser
  |
  | https://bruno.bloby.bot          (via relay, optional)
  v
Bloby Relay (api.bloby.bot)          Cloud server, maps username -> tunnel URL
  |
  | https://random-abc.trycloudflare.com
  v
Cloudflare Quick Tunnel              Ephemeral tunnel, changes on restart
  |
  | http://localhost:3000
  v
Supervisor                           User's machine

• Spawns: cloudflared tunnel --url http://localhost:3000 --no-autoupdate
• Extracts tunnel URL from stdout (regex match for *.trycloudflare.com)
• URL changes on every restart -- the relay provides the stable domain layer on top
• Optionally register with Bloby Relay for a permanent my.bloby.bot/username or bloby.bot/username URL

Named Tunnel

Persistent URL with the user's own domain. Requires a Cloudflare account + domain.

Phone browser
  |
  | https://bot.mydomain.com
  v
Cloudflare Named Tunnel              Persistent tunnel, URL never changes
  |
  | http://localhost:3000
  v
Supervisor                           User's machine

• Setup via bloby tunnel setup (interactive: login, create tunnel, generate config, print CNAME instructions)
• Spawns: cloudflared tunnel --config <configPath> run <name>
• URL is the user's domain (from config), no stdout parsing needed
• No relay needed -- the user's domain is already permanent
• Requires a DNS CNAME record pointing to <uuid>.cfargotunnel.com

Cloudflare Tunnel Binary (supervisor/tunnel.ts)

• Auto-downloads cloudflared binary to ~/.bloby/bin/ on first run (validates minimum 10MB file size)
• Health check: HEAD request to tunnel URL with 5s timeout
• Watchdog runs every 30s, detects sleep/wake gaps (>60s between ticks), auto-restarts dead tunnels
• Quick tunnel restart: re-extracts new URL from stdout, updates relay if configured
• Named tunnel restart: restarts the process, URL doesn't change

Relay Server (separate codebase, Quick Tunnel only)

Node.js/Express + http-proxy + MongoDB. Hosted on Railway. Only used when the user opts into Quick Tunnel mode and registers a handle.

Registration flow:

1. User picks a username during onboarding
2. Bot calls POST /api/register with username + tier
3. Relay stores tokenHash (SHA-256) in MongoDB, returns raw token + relay URL
4. Bot stores token in ~/.bloby/config.json
5. Bot calls PUT /api/tunnel with its cloudflared URL
6. Relay marks bot online, starts accepting proxied traffic

Request proxying:

1. Request hits bruno.bloby.bot
2. Subdomain middleware extracts username + tier from hostname
3. MongoDB lookup returns the bot's tunnel URL
4. proxy.web(req, res, { target: tunnelUrl }) forwards everything -- headers, body, method
5. Response streams back to the user's browser

Presence:

• Bot sends POST /api/heartbeat every 30 seconds with its tunnel URL
• Relay considers a bot stale if no heartbeat in 120 seconds
• Stale bots get a 503 offline page (auto-refreshes every 15s)
• On graceful shutdown, bot calls POST /api/disconnect

Domain tiers: | Tier | Subdomain | Path shortcut | Cost | |---|---|---|---| | Premium | bruno.bloby.bot | bloby.bot/bruno | $5/mo | | Free | bruno.my.bloby.bot | my.bloby.bot/bruno | Free |

Same username can exist on both tiers independently. Compound unique index on username + tier.

WebSocket proxying: The relay listens for HTTP upgrade events outside of Express middleware. This is critical -- Express middleware (body parsing, CORS) must not touch WebSocket upgrades. The upgrade handler parses the subdomain, looks up the bot, and calls proxy.ws().

Critical Constraint: POST Bodies Through the Relay

The relay's express.json() middleware must run AFTER the subdomain resolver, not before. If body parsing runs first, it consumes the request stream and http-proxy has nothing to forward. This was a real bug -- the fix was scoping express.json() to /api routes only, letting proxied traffic pass through with raw streams intact.

The Bloby chat has additional workarounds for this (sending settings and whisper data over WebSocket instead of POST), but with the relay fix these are no longer strictly necessary. They remain as defense-in-depth.

Onboarding (supervisor/chat/OnboardWizard.tsx)

Multi-step wizard shown on first launch (inside the Bloby chat iframe):

1. Welcome -- intro screen
2. Provider -- choose Claude (Anthropic) or OpenAI Codex
3. Model -- select specific model (Opus, Sonnet, Haiku / GPT-5.x variants)
4. Auth -- OAuth PKCE flow for Claude or OpenAI, or manual API key entry
5. Handle -- register a public username with the relay (checks availability in real time)
6. Portal -- set username/password for remote access
7. Whisper -- optional voice transcription setup with OpenAI key
8. Done -- completion screen

Settings are saved via WebSocket (settings:save message) to bypass relay POST limitations.

CLI (bin/cli.js)

The CLI is the user-facing entry point. Commands:

| Command | Description | |---|---| | bloby init | First-time setup: interactive tunnel mode chooser (Quick or Named), creates config, installs cloudflared, boots server, optionally installs systemd daemon | | bloby start | Boot the supervisor (or detect existing daemon and show status) | | bloby status | Health check via /api/health, shows uptime, tunnel URL, and relay URL | | bloby update | Downloads latest from npm registry, updates code directories, rebuilds UI, restarts daemon | | bloby tunnel | Named tunnel management (subcommands below) | | bloby daemon | Linux systemd management: install, start, stop, restart, status, logs, uninstall |

bloby tunnel subcommands: | Subcommand | Description | |---|---| | bloby tunnel setup | Interactive named tunnel setup: login to Cloudflare, create tunnel, enter domain, generate config YAML, print CNAME instructions | | bloby tunnel status | Show current tunnel mode and configuration | | bloby tunnel reset | Switch back to quick tunnel mode |

bloby init tunnel chooser:

During init, the user is presented with an interactive arrow-key menu to choose their tunnel mode:

• Quick Tunnel (Easy and Fast) -- Random CloudFlare tunnel URL on every start/update. Optionally use Bloby Relay for a permanent my.bloby.bot/username handle (free) or a premium bloby.bot/username handle ($5 one-time).
• Named Tunnel (Advanced) -- Persistent URL with your own domain. Requires a Cloudflare account + domain. Use a subdomain like bot.yourdomain.com or the root domain.

If Named Tunnel is selected, bloby init immediately runs the named tunnel setup flow inline (same as bloby tunnel setup).

The CLI spawns the supervisor via node --import tsx/esm supervisor/index.ts and waits for readiness markers on stdout (__TUNNEL_URL__, __RELAY_URL__, __VITE_WARM__, __READY__, __TUNNEL_FAILED__) with a 45-second timeout.

On Linux, bloby daemon generates a systemd unit file that runs the supervisor as a service with auto-restart on failure.

Installation

Two installation paths:

Via curl (production):

curl -fsSL https://bloby.bot/install | sh

The install script (scripts/install.sh) detects OS/arch, checks for Node.js >= 18 (or bundles Node 22.14.0), downloads the npm package, extracts to ~/.bloby/, and adds bloby to PATH.

Via npm (development):

npm install bloby

The postinstall script (scripts/postinstall.js) copies code directories to ~/.bloby/, runs npm install --omit=dev there, builds the chat UI if missing, and creates a bloby symlink.

Windows: scripts/install.ps1 (PowerShell equivalent).

Data Locations

| Path | Contents | |---|---| | ~/.bloby/config.json | Port, username, AI provider, tunnel mode/config, relay token, tunnel URL | | ~/.bloby/cloudflared-config.yml | Named tunnel config (generated by bloby tunnel setup) | | ~/.bloby/memory.db | SQLite -- conversations, messages, settings, sessions, push subscriptions | | ~/.bloby/bin/cloudflared | Cloudflare tunnel binary | | ~/.bloby/workspace/ | User's workspace copy (client, backend, memory files, skills, config) | | ~/.codex/codedeck-auth.json | OpenAI OAuth tokens | | ~/.claude/.credentials.json | Claude OAuth tokens (Linux/Windows) | | macOS Keychain Claude Code-credentials | Claude OAuth tokens (macOS, source of truth) |

File Map

Sacred (never modified by the agent)

bin/cli.js                          CLI entry point, startup sequence, update logic, daemon management
supervisor/
  index.ts                          HTTP server, request routing, WebSocket handler, process orchestration
  backend.ts                        Backend process spawn/stop/restart
  tunnel.ts                         Cloudflare tunnel lifecycle (quick + named), health watchdog
  vite-dev.ts                       Vite dev server startup for dashboard HMR
  bloby-agent.ts                    Claude Agent SDK wrapper, session management, memory injection
  scheduler.ts                      PULSE + CRON scheduler, 60s tick, push notification dispatch
  file-saver.ts                     Attachment storage (audio, images, documents)
  widget.js                         Chat bubble + panel injected into dashboard
  chat/
    bloby-main.tsx                  Chat SPA entry -- auth, WS connection, push subscription, PWA
    onboard-main.tsx                Onboard SPA entry
    OnboardWizard.tsx               Multi-step setup wizard
    ARCHITECTURE.md                 Network topology and relay workaround docs
    src/
      hooks/useChat.ts              Base chat state management
      hooks/useBlobyChat.ts         Bloby-specific chat: DB persistence, sync, pagination, streaming
      lib/ws-client.ts              WebSocket client with reconnect + queue
      lib/auth.ts                   Token storage and auth fetch wrapper
      components/Chat/
        ChatView.tsx                Main chat container
        InputBar.tsx                Text input, file/camera attachments, voice recording
        MessageBubble.tsx           Markdown rendering, syntax highlighting, attachments
        MessageList.tsx             Paginated message history with infinite scroll
        AudioBubble.tsx             Audio player for voice messages
        ImageLightbox.tsx           Image viewer modal
        TypingIndicator.tsx         "Bot is typing..." animation
      components/LoginScreen.tsx    Portal login UI
worker/
  index.ts                          Express API app -- all platform endpoints (runs in-process via createWorkerApp())
  db.ts                             SQLite schema, CRUD operations, migrations
  claude-auth.ts                    Claude OAuth PKCE flow, token refresh, Keychain integration
  codex-auth.ts                     OpenAI OAuth PKCE flow, local callback server on port 1455
  prompts/bloby-system-prompt.txt   System prompt that constrains the agent
shared/
  config.ts                         Load/save ~/.bloby/config.json
  paths.ts                          All path constants (PKG_DIR, DATA_DIR, WORKSPACE_DIR)
  relay.ts                          Relay API client (register, heartbeat, disconnect, tunnel update)
  ai.ts                             AI provider abstraction (Anthropic, OpenAI, Ollama) with streaming
  logger.ts                         Colored console logging with timestamps
scripts/
  install.sh                        User-facing install script (curl-piped), Node bundling
  install.ps1                       Windows PowerShell installer
  postinstall.js                    npm postinstall: copies files to ~/.bloby/, builds UI, creates symlink

Workspace (agent-modifiable)

workspace/
  client/
    index.html                      Dashboard HTML shell, PWA manifest, widget script tag
    src/main.tsx                     React DOM entry
    src/App.tsx                      Dashboard root -- error boundary, rebuild overlay
    src/components/                  Dashboard UI components
  backend/
    index.ts                        Express server template with .env loading and SQLite
  .env                              Environment variables
  app.db                            Workspace SQLite database
  MYSELF.md                         Agent identity and personality
  MYHUMAN.md                        User profile (agent-maintained)
  MEMORY.md                         Long-term curated knowledge
  PULSE.json                        Periodic wake-up configuration
  CRONS.json                        Scheduled task definitions
  memory/                           Daily notes (YYYY-MM-DD.md)
  skills/                           Plugin directories (.claude-plugin/plugin.json)
  MCP.json                          MCP server configuration (optional)
  files/                            Uploaded file storage (audio/, images/, documents/)

Key Design Decisions

Why does the worker run in-process but the backend is a separate child process? The worker is trusted platform code (auth, database, API) -- it shares the same lifecycle as the supervisor. The backend runs user-editable workspace code that Claude can modify at any time. Keeping it as a separate process means a bug Claude introduces only crashes the backend, not the whole system. The supervisor and chat stay alive so the user can ask Claude to fix it. The backend also uses Node.js module hooks to enforce a sandbox boundary, preventing workspace code from importing packages outside workspace/node_modules/.

Why serve the chat from pre-built static files instead of Vite? The chat must survive dashboard crashes. If Vite dies or the workspace frontend throws, the chat iframe loads from dist-bloby/ which is just static files. No build process, no dev server dependency.

Why WebSocket for chat instead of HTTP streaming? The relay couldn't reliably forward POST bodies (now fixed). WebSocket was the workaround. It also gives us bidirectional real-time communication, multi-device sync, and heartbeat detection for free.

Why bypassPermissions on the agent? The whole point is that the user talks to Claude from their phone and Claude does whatever's needed. Confirmation prompts would require a terminal session that doesn't exist. The workspace directory boundary + the system prompt are the safety rails.

Why two tunnel modes? Quick Tunnel is the default for simplicity -- zero configuration, no Cloudflare account needed. The tradeoff is the URL changes on restart, which is why the relay exists as an optional stable domain layer. Named Tunnel is for advanced users who want full control -- their own domain, no dependency on the relay, permanent URLs. Both modes are offered during bloby init.

Why two Vite configs? vite.config.ts builds the workspace dashboard (user-facing app). vite.bloby.config.ts builds the Bloby chat SPA. They're separate apps with separate entry points, bundled independently. The chat is pre-built at publish time; the dashboard runs as a dev server with HMR.

Why memory files instead of a database for agent memory? Files are the natural interface for the Claude Agent SDK -- it can read and write them with its built-in tools. No custom tool needed, no API integration. The agent manages its own memory with the same tools it uses to edit code.