FlowOS
_{Autonomous research in the browser — Jarvis, sandboxed execution, real web data.}

---

FlowOS is an open-source AI workspace where Jarvis chats with you, decides when to run deep web research, and executes a sandboxed research agent inside E2B. Results land in the chat as structured reports — with optional live desktop streaming when you use the desktop template.

If you want a Manus-class loop (search → open results → read pages → synthesize), the agent uses Python + BeautifulSoup over HTTP inside the sandbox — fast boots, no browser gymnastics for the default terminal path.

---

Highlights

Capability	Detail
Jarvis	Gemini-powered intent: chit-chat vs. kick off a research run
Research agent	Plan → wide parallel search → fetch or Playwright Chromium (JS sites, session profile, screenshot + Gemini vision) → Python in sandbox → synthesis
Sandboxes	E2B terminal (default) or custom desktop template + stream
Persistence	Supabase for runs, Jarvis messages, vault hooks
Projects	Saved instructions + reference context, injected into Jarvis and each research run (Manus-style workspace)
UI	Dashboard chat, runs history, HTML export for reports

Gemini usage: Jarvis uses one gemini-2.0-flash call per chat turn (not tied to app credits). A research run charges one credit only after the run row is stored; it then uses Gemini for an upfront plan, about one decision call per agent step (with limited retries if JSON parsing fails), optional think / vision (screenshot + analyze), and sometimes a final report pass. Research POST returns 503 if GEMINI_API_KEY is missing so credits are not spent on a doomed run.

Web search: Each search / wide_search step calls hosted SERP APIs first when SERPAPI_API_KEY, BRAVE_SEARCH_API_KEY, or GOOGLE_CSE_* is set (keys never enter E2B), then HTML scraping (Google → Bing → DuckDuckGo) inside the sandbox if results are thin, then fetches up to two result pages for text. For production reliability on Vercel, configure at least one SERP provider.

---

Architecture

flowchart LR
  subgraph client [Browser]
    Chat[Chat UI]
    Runs[Runs / Results]
  end
  subgraph next [Next.js]
    API_Jarvis["/api/jarvis"]
    API_Sandbox["/api/sandbox"]
  end
  subgraph cloud [External]
    Gemini[Google Gemini]
    E2B[E2B Sandboxes]
    SB[(Supabase)]
  end
  Chat --> API_Jarvis
  Chat --> API_Sandbox
  API_Jarvis --> Gemini
  API_Jarvis --> SB
  API_Sandbox --> E2B
  API_Sandbox --> SB
  E2B --> Gemini

Loading

---

Quick start

Requirements: Node 20+, npm, accounts for Supabase, Google AI Studio (Gemini), E2B.

git clone https://github.com/alexbieber/Flow-OS.git
cd Flow-OS
npm install
# macOS/Linux:
cp .env.example .env.local
# Windows PowerShell:
Copy-Item .env.example .env.local
npm run dev

Open http://localhost:3000.

Environment variables

Create .env.local (never commit secrets):

Variable	Purpose
GEMINI_API_KEY	Google Generative AI (Jarvis + agent)
SERPAPI_API_KEY	(Optional) SerpAPI for reliable web search from the server
BRAVE_SEARCH_API_KEY	(Optional) Brave Search API
GOOGLE_CSE_API_KEY + GOOGLE_CSE_CX	(Optional) Google Programmable Search (JSON API)
E2B_API_KEY	E2B sandbox create / commands
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key
SUPABASE_SERVICE_ROLE_KEY	Server-side Supabase (API routes)

Supabase SQL bootstrap (required order)

Run these files in the Supabase SQL editor, in order:

1. supabase/schema.sql
2. supabase/sql/jarvis_messages_session_id.sql
3. supabase/sql/user_credits.sql
4. supabase/sql/flowos_projects.sql
5. supabase/sql/manus_parity_foundation.sql

Feature dependencies:

• Projects requires flowos_projects.
• Credits (/api/credits, research spending) requires user_credits.
• Session chat (/api/jarvis, /api/sessions) requires jarvis_messages.session_id.
• Runs / Vault / base messages come from schema.sql.
• Connectors/Schedules/Trust/Skills/Collab APIs require manus_parity_foundation.sql.

Manus parity surfaces

Surface	Route	Notes
Connectors	/connectors	Connect Google Drive, Gmail, Slack, Notion, MCP stubs
Skills	/skills	Reusable prompt packs → open in chat
Schedules	/schedules	Create recurring tasks, Run now triggers research
Trust	/trust	Policy + audit event log
Benchmarks	/benchmarks	Quality gates on your completed runs
Artifacts	POST /api/artifacts	Slides, data-viz brief, email draft from a report

OAuth connectors (Google Drive / Gmail)

1. Create OAuth credentials in Google Cloud Console (Web application).
2. Add redirect URI: https://<your-domain>/api/connectors/oauth/callback (and http://localhost:3000/... for local dev).
3. Set GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, and NEXT_PUBLIC_APP_URL in .env.local.
4. Connect at /connectors — live file/subject snippets are injected into research runs.

Scheduled tasks (cron)

• Vercel Cron calls GET /api/cron/schedules hourly (vercel.json).
• Set CRON_SECRET in Vercel env; the route requires Authorization: Bearer <CRON_SECRET>.
• Due tasks (enabled + next_run_at <= now) enqueue research runs automatically.
• Local test: curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/schedules

Collaboration

• On Projects, expand Share & collaborate to invite by email (existing FlowOS account) or user UUID.
• Collaborators see shared projects in the list and can Open in chat with full project context injected into runs.

Slack connector

1. Create a Slack app with OAuth redirect: /api/connectors/oauth/callback.
2. Bot scopes: channels:read, channels:history, groups:read.
3. Set SLACK_CLIENT_ID and SLACK_CLIENT_SECRET in .env.local.

Schedule email notifications

When a scheduled research run finishes, FlowOS emails the account owner (if RESEND_API_KEY and their Supabase auth email are set). Configure NOTIFY_FROM_EMAIL for your sending domain.

---

E2B template (optional desktop)

For noVNC / Chrome workflows, build the template from the repo root:

• Workflow: .github/workflows/build-template.yml (manual dispatch)
• Dockerfile: e2b.Dockerfile
• Set E2B_ACCESS_TOKEN (or E2B_API_KEY, depending on CLI version) in GitHub Actions secrets

Wire the built template ID in sandbox code when using the desktop SDK path.

---

Scripts

Command	Description
npm run dev	Next.js dev (Turbopack)
npm run build	Production build
npm run start	Start production server
npm run lint	ESLint
npm run typecheck	TypeScript check (tsc --noEmit)

---

Stabilization checklist

Before opening a PR, run:

npm run lint
npm run typecheck
npm run build

Manual happy-path verification:

1. Sign in from /login (Google or email link) and confirm redirect back to the intended route.
2. Create a project in /projects, then edit and delete it.
3. Click Open in chat from a project and confirm chat URL includes ?project=....
4. Refresh and confirm project list + sessions load without 401 loops.
5. Run one research task from chat and verify credits/session endpoints remain healthy.

---

Project layout

src/app/           # App Router — dashboard, chat, API routes
lib/research/      # Research agent loop + prompts
lib/sandbox/       # E2B terminal (and related helpers)
lib/ai/            # Gemini helpers
supabase/          # SQL schema & migrations

---

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for guidelines.

---

License

MIT — see LICENSE. Free for commercial and personal use; attribution appreciated.

---

Built with Next.js, React, Supabase, Gemini, and E2B.