SEOS - Personal AI Operating System

SEOS is a private single-user chief-of-staff system. It combines a Next.js dashboard, Telegram bot, Supabase memory/tasks, Groq/Gemini AI calls, Gmail/search tools, and proactive scheduled routines.

Current Architecture

Telegram Bot -> Next.js API routes -> Supabase Postgres
Dashboard    -> Next.js API routes -> Groq/Gemini/Gmail/Search
GitHub/Vercel cron -> /api/proactive actions -> Telegram + Supabase

The live backend is the Next.js App Router under frontend/src/app/api. The old separate Railway/Express backend has been removed from the deployment path.

Setup

1. Create a Supabase project.
2. Run supabase/schema.sql, then every file in supabase/migrations in timestamp order.
3. Configure the environment variables below in Vercel or your local .env.local.
4. Install and run the app:

cd frontend
npm install
npm run dev

Open http://localhost:3000. Sign in with DASHBOARD_PASSWORD. Local development can fall back to CRON_SECRET, but production dashboard sessions must use a dedicated dashboard password.

For local generated scoped secrets, run:

node scripts\bootstrap-local-secrets.mjs
node scripts\update-vercel-env.js --check
node scripts\update-vercel-env.js --doctor
node scripts\seos-production-unblock.mjs

The bootstrap script writes only to ignored local env files and does not print secret values. --check verifies local required values exist. --doctor verifies required production env names with VERCEL_TOKEN, or with the authenticated Vercel CLI when the token is absent. Updating values still requires VERCEL_TOKEN; the doctor never prints secret values.

For a single operator-facing production unblock report, run:

.\Run-SEOS-Production-Unblock.bat

It generates/verifies the no-secret Agent Ops SQL bundle, checks Vercel deploy access, probes production readiness, and prints the remaining provider/runtime steps without exposing secret values. The report separates local blocking inputs from external provider actions, so the missing Supabase Agent Ops table apply is visible even when local Vercel/Git checks pass.

When provider credentials are ready, package the verified local release from a normal authenticated shell:

.\Run-SEOS-Release-Package.bat
$env:SEOS_RELEASE_CONFIRM="YES"
node scripts\seos-release-package.mjs --execute --push

The release packager is dry-run by default. It runs git whitespace checks, secret scan, tests, lint, build, and the production unblock quick check before it will stage or commit anything.

scripts/update-vercel-env.js updates env values without redeploying by default. Use --redeploy only after the latest pushed commit is the deployment you intend to refresh.

If production Agent Ops endpoints report missing agent_runtimes, agent_jobs, agent_approvals, or agent_job_events, generate the no-secret unblock bundle and apply it only to the SEOS Supabase project. The bundle covers the full runtime set: agent_events, agent_runtimes, runtime_heartbeats, workspace_allowlists, agent_jobs, agent_job_events, and agent_approvals; the final hardening migration enables RLS on those public tables with no public policies and revokes anon/authenticated access.

node scripts\print-agent-ops-migration-bundle.mjs --check
node scripts\print-agent-ops-migration-bundle.mjs --out .\seos-agent-ops-unblock.sql
node scripts\apply-agent-ops-migration.mjs --check --ensure-bundle

supabase/schema.sql is the older base bootstrap schema. Treat timestamped migrations plus this bundle as the Agent Ops source of truth.

If SUPABASE_ACCESS_TOKEN is available for the SEOS production Supabase project, the guarded applier can call Supabase's Management API migration endpoint:

node scripts\apply-agent-ops-migration.mjs --apply

It refuses any project ref except dubfhntybrhopjcvskna. If the Management API token lacks migration access, use node scripts\apply-agent-ops-migration.mjs --manual and paste the generated bundle into that exact project's SQL editor. If the ChatGPT/Codex Supabase connector lists projects but not dubfhntybrhopjcvskna, the connector is attached to the wrong Supabase account/org for SEOS; do not apply the bundle to another project. For the shortest Windows manual path, run Open-SEOS-Agent-Ops-Migration.bat; it validates the bundle, copies the no-secret SQL to your clipboard, and opens the correct Supabase SQL editor URL only if production still reports Agent Ops as missing. After you run the SQL in Supabase, return to the same window and it will run the cloud/full/smoke readiness checks.

Required Environment

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
CRON_SECRET=
DASHBOARD_PASSWORD=
SEOS_API_SECRET=
SEOS_READONLY_SECRET=
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
TELEGRAM_WEBHOOK_SECRET=
GROQ_API_KEYS=
GEMINI_API_KEYS=

Optional:

TAVILY_API_KEY=
GMAIL_CLIENT_ID=
GMAIL_CLIENT_SECRET=
GMAIL_REFRESH_TOKEN=
GMAIL_REDIRECT_URI=

Telegram Webhook

After deploy, authenticate to the dashboard/API and call:

POST /api/telegram/webhook?action=setWebhook

Telegram POST /api/telegram/webhook remains public because Telegram must reach it, but messages are only processed for TELEGRAM_CHAT_ID.

Proactive Jobs

Supported actions:

POST /api/proactive/morning-brief
POST /api/proactive/evening-checkin
POST /api/proactive/reminder-check
POST /api/proactive/accountability
POST /api/proactive/weekly-review
POST /api/proactive/self-audit
GET  /api/proactive?action=tick

Cron calls must send:

Authorization: Bearer <CRON_SECRET>

Agent Capability Layer

SEOS exposes model actions through a central capability registry shared by Telegram and web chat. This keeps the agent powerful but controlled: it can research, inspect Gmail, create tasks/reminders, save knowledge, log journal entries/expenses, and read current tasks, reminders, and memory.

Agent Runtime Layer

SEOS now includes an Agent Ops control plane for OpenClaw/Codex runtime work. The cloud app stores jobs, approvals, runtime heartbeats, workspace allowlists, and job events; the local laptop worker polls SEOS with SEOS_BRIDGE_SECRET so Vercel never needs inbound access to the machine.

Local bridge:

set SEOS_BASE_URL=https://seo-os-agent.vercel.app
set SEOS_BRIDGE_SECRET=<same value configured in Vercel>
set SEOS_BRIDGE_RUNTIME_SECRETS={"laptop-openclaw":"<runtime-scoped secret>"}
set SEOS_WORKER_DRY_RUN=true
set SEOS_WORKSPACE_ALLOWLIST=C:\Users\suven\Desktop\OneDriveBackupFiles\Documents\ALL WORK\AI AGENT SYSTEM
node scripts/agent-bridge-worker.mjs

Runtime setup and OpenClaw config templates are in docs/agent-runtime.md and openclaw/seos-openclaw.config.example.jsonc.

Useful Telegram operator commands:

/capabilities        Show the registered tool layer
/status or /agent    Show provider/config/runtime health
/brief               Daily operating brief
/tasks               Open tasks
/reminders           Upcoming reminders
/memory [query]      Search saved memory
/chronicle [query]   Search local Chronicle/Obsidian via the bridge
/context [project]   Fetch Chronicle project context via the bridge
/read [url]          Read and save a link
/research [topic]    Research and save a topic
/agents              Runtime health and pending approvals
/jobs                OpenClaw/Codex job queue
/codex [repo]: task  Queue a coding job for Codex/OpenClaw
/approve [id]        Approve a pending runtime action
/reject [id]         Reject a pending runtime action

Runtime tool and command events are stored in agent_events after applying the latest migration.

Chronicle Local Memory Harness

Chronicle is the cross-agent memory sidecar for SEOS. It creates an Obsidian-compatible Markdown vault, indexes it with embedded PGLite, distills timeline events into compiled truth, and exposes memory tools over MCP for Codex, Cursor, Windsurf, Claude Code, OpenClaw, and other compliant agents.

Live Obsidian vault:

C:\Users\suven\OneDrive\Documents\Obsidian Vault

cd chronicle
npm install
npm run build
npm run dev -- init
npm run mcp

One-click local operations:

Open-SEOS-Mission-Control.bat
Check-Chronicle.bat
Open-Chronicle-Command-Center.bat
View-Chronicle-Memory.bat
Run-Chronicle-AutoLearn-Now.bat
Install-Chronicle-AutoLearn.bat
Sync-SEOS-Context-Awareness.bat

Codex is wired with MCP plus auto-capture hooks. A Windows scheduled task named Chronicle Auto Learn imports recent Codex sessions and updates the vault every 30 minutes. The command center shows health, learned facts, timeline events, learning status, search, manual logging, Codex import, workspace snapshot, and auto-learn controls in one place.

Chronicle also indexes the shared global agent skills directory:

C:\Users\suven\.agents\skills

It stores compact registry notes in the Obsidian vault and keeps the real SKILL.md files as the source of truth. Future agents should search the registry, then open only the relevant skill files for the current task.

cd chronicle
npm run dev -- sync-skills
npm run dev -- search-skills "React frontend accessibility browser QA"

Open-SEOS-Mission-Control.bat is the top-level local operating dashboard. It checks the deployed SEOS app, Agent Ops, Chronicle, Obsidian, OpenClaw, the bridge worker, scheduled tasks, relevant local processes, and git state in one live view. It also includes a Knowledge Hub for searching Chronicle, Obsidian, global agent skills, and the SEOS Supabase knowledge/memory tables when local Supabase credentials are available.

SEOS also generates a portable context-awareness packet for agents and web chat:

AGENT_CONTEXT.md
docs/context-awareness.md
frontend/src/lib/context/awarenessPacket.js

Regenerate it with Sync-SEOS-Context-Awareness.bat or the Mission Control Sync Context button after major setup, deployment, runtime, or memory changes. The packet is intentionally secret-free and is imported into the web chat prompt before every model call.

Docs: docs/mission-control.md, docs/chronicle.md, and chronicle/README.md.

Checks

cd frontend
npm test
npm run lint
npm run build
npm audit --omit=dev
node --check ../scripts/agent-bridge-worker.mjs

Main Directories

frontend/src/app       Dashboard pages and API routes
frontend/src/lib       Services, handlers, API client, auth helpers
frontend/src/components Shared UI
supabase/schema.sql    Base database schema
supabase/migrations    Incremental database fixes/features
.github/workflows      Scheduled job callers