Codex — LumiBase Agent Setup
Codex is a lightweight open-source terminal agent that reads and writes files, runs commands, and browses the web in a sandbox. Made by OpenAI.
Tags: Terminal · Standalone · Cloud · Extension · Open Source
Quick setup (recommended)
bash
codex "Read docs/en/agent-setup/prompt.md and follow all setup instructions."
Manual setup
Step 1 — Install Codex
bash
npm install -g @openai/codex
Authenticate:
bash
export OPENAI_API_KEY=<your-key>
Step 2 — Navigate to the project
bash
cd /path/to/lumibase
Step 3 — Load LumiBase context
bash
codex "Read docs/en/README.md and docs/en/data-model.md to understand the LumiBase codebase structure and conventions."
Step 4 — Create a context file (optional)
Codex respects AGENTS.md or codex.md in the project root. Create one:
bash
cat > AGENTS.md << 'EOF'
# LumiBase agent context
You are working on LumiBase, an Edge-native Headless CMS.
Stack: Hono.js API (apps/cms), React+Vite Studio (apps/studio), PostgreSQL+Drizzle (packages/database), Cloudflare Workers + Docker dual-runtime.
Rules:
- IDs: NanoID or UUIDv7. Never auto-increment serial.
- Multi-tenancy: site_id on every domain table, scoped in every query.
- Runtime: use @lumibase/runtime abstractions, never direct CF KV/R2 bindings.
- AI safety: dangerous skills (schema:write, delete*) must gate through ai_approvals.
- Cache: tag-based invalidation only.
Key docs:
- docs/en/data-model.md
- docs/en/api/hono-api-spec.md
- docs/en/features/ai-copilot.md
- docs/en/features/flows-automation.md
EOF
Step 5 — Add MCP server (optional)
bash
codex mcp add lumibase --url http://localhost:1989/mcp
Set auth via environment:
bash
export LUMIBASE_TOKEN=<your-access-token>
export LUMIBASE_SITE_ID=<your-site-id>
Example Codex sessions
bash
# Add a new API route
codex "Read docs/en/api/hono-api-spec.md. Add a GET /api/v1/stats endpoint that returns site-level counts for collections, items, users, and files. Scope by site_id."
# Extend the Flows engine
codex "Read docs/en/features/flows-automation.md. Add a 'webhook-verify' operation that validates an HMAC-SHA256 signature on incoming webhook payloads."
# Fix a bug with context
codex "apps/cms/src/services/flow-service.ts has a bug where failed flow_runs are not saving the error message. Read the file and fix it."
Sandbox mode
Codex runs in a sandboxed environment. For LumiBase development:
bash
# Codex can read/write files and run commands — useful for:
codex "Run pnpm typecheck in packages/database and fix any TypeScript errors."
codex "Generate Drizzle migration SQL for adding a tags column to the flows table."
Troubleshooting
Codex doesn't understand monorepo structure: Point it at docs/en/README.md first, which maps all packages and apps.
Commands fail in sandbox: Some pnpm workspace commands need the workspace root. Tell Codex: "Run this from the project root, not from a subdirectory."