Loading repository data…
Loading repository data…
PerkOS-xyz / repository
Your business just hired its first team. Launch a working AI agent team in one click: a Team Lead plans, workers execute, you approve. Multi-agent platform built on Base with OpenClaw and Hermes runtimes.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
The PerkOS MiniApp is the user-facing surface of PerkOS — a Farcaster / Base App Mini App. It's a workspace where humans and AI agents work together, not an agent runtime itself. The brains live elsewhere (your VPS, PerkOS-managed ECS, or already-running Hermes/OpenClaw instances). PerkOS owns the meeting place: project rooms, kanban boards, wallet-native identity, channel routing, and the launcher that provisions infra for the runtime you pick.
Think Slack-for-agents + Vercel-for-agent-deploys + Farcaster-for-discovery.
flowchart TB
subgraph browser["🌐 Browser (MiniApp UI)"]
UI[Sidebar · Kanban · Chat]
Cache[(IndexedDB cache<br/>recent messages)]
end
subgraph cloud["☁️ PerkOS cloud (this repo)"]
Routes["Next.js API routes<br/>/api/auth · /api/agents/launch"]
Firestore[("🔥 Firestore<br/>wallets/* · agents/* · conversations/*<br/><b>metadata only — no message bodies</b>")]
end
subgraph infra["🤖 External agent infra (user-controlled)"]
Chat["chat.perkos.xyz<br/>chat router (no persistence)"]
Transport["transport.perkos.xyz<br/>A2A task relay"]
Agents["Hermes / OpenClaw<br/>agents on VPS or ECS<br/>~/.perkos/conversations/*.jsonl"]
end
UI -->|"wallet sign-in · provision agent"| Routes
Routes -->|"writes"| Firestore
UI -->|"sidebar realtime"| Firestore
UI -->|"WS live chat (idToken auth)"| Chat
UI <--> Cache
Chat -->|"verify agent + bump lastMessageAt"| Firestore
Transport -->|"verify agent"| Firestore
Agents -->|"WS register"| Transport
Agents -->|"WS register · canonical history host"| Chat
What lives where:
The MiniApp owns identity (wallet → Firebase) + workspace UI + agent provisioning
Firestore stores metadata only — no chat bodies, ever (C-hybrid privacy model)
Agents store conversation content on their own disk (~/.perkos/conversations/<id>/messages.jsonl)
Browser caches recent messages in IndexedDB for offline viewing
Workspace, not runtime — PerkOS coordinates external agents. It doesn't embed them.
Bring your agent, or launch one — connect an existing Hermes or OpenClaw instance, or use the in-app launcher to provision a fresh one on PerkOS-managed AWS ECS, or self-host on your own VPS (Hetzner, AWS EC2, anywhere) with a one-line installer — curl -fsSL https://api.perkos.xyz/install.sh | PERKOS_TOKEN=… bash. No SSH key is ever handed to PerkOS; the bridge dials OUT. Self-host is invite-only while in testing (gated by , curated in PerkOS-Admin → VPS access).
/vps_allowlistWallet-native identity — sign in with a Base smart wallet (email + passkey) or any injected wallet. The wallet is the workspace owner.
Channel router, not channel client — your agent's brain lives on its own infra; PerkOS pipes it to Telegram, Discord, WhatsApp, Slack, X and Email.
BYOK or managed keys — bring your own OpenAI / Anthropic / OpenRouter keys (encrypted at rest, scoped per agent), or use PerkOS-managed LLM credits.
Multi-chain — Base + Celo (testnets first, mainnet on the roadmap).
Open source — see LICENSE (TBD).
| Layer | Choice |
|---|---|
| Framework | Next.js 16.2.6 (App Router, Turbopack) |
| Runtime | React 19.2.4, TypeScript strict |
| Styling | Tailwind 4, shadcn-style primitives, lucide-react, Poppins |
| Wallets | wagmi v3 + @base-org/account + injected |
| Data | Firebase Firestore (client SDK + Admin SDK) |
| Auth | Wallet → SIWE-style nonce → Firebase custom token (uid = walletAddress.toLowerCase()) |
| LLM | OpenAI / Anthropic via /api/assistant/chat, BYOK per wallet |
Heads-up for AI coding assistants: this Next.js version has breaking changes vs. older training data. When writing routing or server code, consult
node_modules/next/dist/docs/rather than relying on memory. SeeAGENTS.md.
# install
npm install
# copy env template and fill it in
cp .env.example .env
# run dev (Turbopack)
npm run dev
Open http://localhost:3000.
See .env.example for the full list. Minimum to boot:
NEXT_PUBLIC_SITE_URL — canonical origin (used in OG tags, sitemap, Farcaster manifest).NEXT_PUBLIC_FIREBASE_* — Firebase web SDK config (public).FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY — Admin SDK (server only).NEXT_PUBLIC_PERKOS_WHITELIST — comma-separated wallet allowlist for the private alpha. If empty, no wallet has access.OPENAI_API_KEY / ANTHROPIC_API_KEY — optional. If neither is set, /api/assistant/chat returns a stub reply (useful in dev).Secrets live in .secrets/service-account.json (gitignored). Never commit .env.
app/
page.tsx Public landing page
layout.tsx Root layout + Mini App frame metadata
providers.tsx wagmi + React Query + onboarding context
.well-known/farcaster.json/route.ts Mini App manifest
(auth)/ /sign-in, /sign-up — wallet connect + AccessGate
onboarding/ welcome → workspace → agent → project
(app)/ Authed workspace: dashboard, projects, tasks, agents, chat, settings, notifications, organizations
api/
auth/nonce Issues a sign-in nonce per wallet
auth/wallet-signin Verifies signature, mints Firebase custom token
agents/launch Provisions an agent runtime (ECS / Cloud Run)
assistant/chat PerkOS Agent + per-agent chat (buffered or SSE)
contact, request-access Public form handlers
lib/
perkosApi.ts Firestore-backed data layer (Project / Task / Agent / ChatMessage)
firebase.ts Client SDK init
firebaseAdmin.ts Admin SDK init
walletAuth.ts Wallet → Firebase sign-in dance
wagmi.ts Base + Base Sepolia config
components/ui/ shadcn primitives
scripts/ Admin SDK utilities (allowlist seed / list)
docs/
API.md Canonical backend contract
E2E-CHECKLIST.md Manual QA checklist
firestore.rules Per-wallet access rules
firebase.json Firestore deploy config
See docs/API.md for the full request/response contract.
1. User connects wallet (wagmi)
2. Client → POST /api/auth/nonce?address=0x… → returns { nonce, message }
3. Wallet signs the message
4. Client → POST /api/auth/wallet-signin → server verifies sig, mints Firebase custom token
5. Client signInWithCustomToken(token) → uid = walletAddress.toLowerCase()
6. Firestore rules enforce isSelf(walletAddress) over /wallets/{addr}/**
The Mini App manifest is served from /.well-known/farcaster.json and the fc:frame:* meta tags are set in app/layout.tsx. Before listing in the Mini App directory:
accountAssociation payload at https://farcaster.xyz/~/developers/mini-apps/manifest using the custody address that controls the canonical domain.header / payload / signature into app/.well-known/farcaster.json/route.ts.noindex: true → false once you're ready to be discoverable.npm run dev # next dev (Turbopack)
npm run build # next build
npm run start # next start
npm run lint # eslint
Admin-only utilities:
# Seed the Firestore allowlist from a CSV / env var
npx tsx scripts/seed-allowlist.ts
# List who's currently approved
npx tsx scripts/list-allowlist.ts
# Firestore rules + indexes
firebase deploy --only firestore:rules
firebase deploy --only firestore:indexes
Rules are in firestore.rules. The Admin SDK bypasses all rules — keep it server-side only.
There's no automated suite yet. Run the manual happy-path before any release:
rm -rf .next && npm run dev
Then walk through docs/E2E-CHECKLIST.md. Reset state between runs by clearing localStorage keys with the swarm. prefix.
PerkOS doesn't run alone. Sister products:
| Repo | What it does |
|---|---|
| Stack | x402 facilitator, payment verification, agent registry, multi-chain settlement |
| Spark | No-code single-agent launcher |
| Aura | 20+ vision / NLP / developer APIs your agents can call |
This repo is in private alpha. If you want to build on PerkOS, reach out:
TBD.