Genie Knowledge Bundle
Bundle OKF 0.1 · 5 conceitos · paulbrie/genie
Open source Repository Open in the app JSON README (API)
About
# Genie Knowledge Bundle
A small [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
bundle that describes concepts from the Genie codebase in a human- and
agent-friendly form. Each `.md` file (other than `index.md` / `log.md`) is a
single concept with YAML frontmatter and a markdown body.
# Concepts
* [Recipes](recipes/) - how Genie checks, installs, and uninstalls a piece of software on a VPS over SSH.
* [Agents](agents/architecture.md) - user-defined AI agents that run in a Docker sandbox on a project's VPS.
* [Access Control Layers](security/access-control.md) - the four-layer defense-in-depth pattern that gates a feature to a role.
* [Claude Hardening](security/claude-hardening.md) - managed settings + the genie-UID egress allowlist firewall that bound what a bypass-permissions Claude session on a VM can read and reach.
* [Browser→VM Code Proxy](vps/code-server-proxy.md) - how "Open in VS Code" serves code-server on a VPS through the Manager ov
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- paulbrie
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-27T11:30:20Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-09-08 22:11:44
- Updated
- 2026-09-08 22:11:44
- Origin id
paulbrie/genie:knowledge/index.md
README
# Genie A development platform for managing projects, VPS droplets, and AI-assisted workflows. ## Architecture - **Manager** (`packages/manager`) — Node.js WebSocket server that orchestrates everything: project management, SSH tunnels to droplets, PTY terminal sessions, PostgreSQL via Drizzle ORM, AI assistant integration. - **Renderer** (`packages/renderer`) — Next.js web dashboard for project management, docs, tracker, terminal, admin panel, and DB explorer. - **Chrome Extension** (`packages/chrome-extension`) — Browser extension for remote VPS control, AI chat, file editing, Docker view, and terminal access. - **VPS Agent** (`packages/vps-agent`) — Agent that runs on droplets for AI-assisted operations. ## Local Development ```bash npm install npm run dev # Starts manager + renderer concurrently npm run dev:extension # Builds Chrome extension in watch mode ``` ## Building ```bash npm run build # Build all packages npm run build:manager # Build manager only npm run build:renderer # Build renderer only npm run build:extension # Build Chrome extension (production) npm run build:vps-agent # Build VPS agent ``` ## Deployment (Railway) The project is deployed on Railway with two services from this monorepo: ### Manager Service - **Build command**: `npm run build:manager && npm run build:vps-agent` - **Start command**: `node packages/manager/dist/index.js` - **Required env vars**: `DATABASE_URL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `MANAGER_URL`, `ANTHROPIC_API_KEY` ### Renderer Service - **Build command**: `npm run build:renderer` - **Start command**: `node packages/renderer/.next/standalone/packages/renderer/server.js` - **Note**: Uses `output: "standalone"` in next.config.ts for self-contained deployment ### railway.toml The `railway.toml` configures Nixpacks build dependencies: - **python3, gcc, gnumake** — Required for compiling `node-pty`, a native Node.js module used by the terminal feature. Without these, the terminal PTY functionality won't work in production (other features degrade gracefully). - **nodejs_22** — Required by Next.js 16, Tailwind CSS, and other dependencies. ### Environment Variables | Variable | Service | Description | |----------|---------|-------------| | `DATABASE_URL` | Manager | PostgreSQL connection string | | `GOOGLE_CLIENT_ID` | Manager | Google OAuth client ID | | `GOOGLE_CLIENT_SECRET` | Manager | Google OAuth client secret | | `MANAGER_URL` | Manager | Public URL (e.g. `https://api.genie.teleporthq.ai`) | | `FRONTEND_URL` | Manager | Frontend URL for OAuth redirects (e.g. `https://genie.teleporthq.ai`) | | `ANTHROPIC_API_KEY` | Manager | Anthropic API key for Claude integration | | `PORT` | Both | Set automatically by Railway |