# Vibosome AI Agent Guide This guide is for Codex, Claude, Antigravity, Cursor, and other coding agents controlling Vibosome for a user. Vibosome hosts AI-coded scripts as scheduled automations. The user should be able to say, "make this run every morning" or "fix the failed run" without managing EC2, SSH, cron, `.env`, or Docker. ## Human Promise The human should not need to understand API endpoints. Preferred workflow: 1. Human opens Vibosome. 2. Human imports a project or opens an existing project. 3. Human clicks **Copy AI IDE prompt**. 4. Human pastes the prompt into the AI tool. 5. AI uses Vibosome APIs to inspect, fix, run, and schedule. 6. Human approves only risky changes. ## Base URL Production: ```text https://vibosome.com ``` Local development: ```text http://localhost:8787 ``` ## Authentication Use the agent token from the copied Vibosome prompt: ```http Authorization: Bearer ``` Never ask the user for a Vibosome password. Never ask the user to paste admin credentials into an AI chat. ## First API Calls Read capabilities: ```http GET /api/agent/v1/capabilities ``` List projects: ```http GET /api/agent/v1/projects ``` Inspect a project: ```http GET /api/agent/v1/projects/:jobId ``` Read latest logs: ```http GET /api/agent/v1/projects/:jobId/runs/latest?includeLogs=true ``` Run once: ```http POST /api/agent/v1/projects/:jobId/run ``` ## Create Project Use this when the project is open in the AI IDE and has not yet been imported. ```http POST /api/agent/v1/projects Content-Type: application/json Authorization: Bearer ``` ```json { "name": "Supplier feed sync", "command": "npm run harvest", "schedule": { "mode": "manual", "time": "06:00", "timezone": "Etc/GMT-3" }, "activate": false, "envValues": { "NODE_ENV": "production" }, "files": [ { "path": "package.json", "content": "{\"scripts\":{\"harvest\":\"node agent.js\"}}" }, { "path": "agent.js", "content": "console.log(process.env.NODE_ENV)" } ] } ``` Do not upload `.env`, `.env.local`, `.git`, `node_modules`, `dist`, `.next`, binary files, or secrets hard-coded into files. ## Update Project Use this to change command, schedule, variables, status, or selected files. ```http PATCH /api/agent/v1/projects/:jobId Content-Type: application/json Authorization: Bearer ``` Example schedule update: ```json { "schedule": { "mode": "daily", "time": "06:00", "timezone": "Etc/GMT-3" }, "status": "active" } ``` Example variable update: ```json { "envValues": { "NODE_ENV": "production", "API_URL": "https://example.com/feed.json" } } ``` If overwriting an existing secret, Vibosome may require approval. ## MCP Vibosome exposes an HTTP JSON-RPC MCP bridge: ```http POST /mcp Authorization: Bearer ``` Supported methods: - `initialize` - `tools/list` - `tools/call` Tools: - `vibosome_detect_project` - `vibosome_create_project` - `vibosome_update_project` - `vibosome_run_now` - `vibosome_latest_run` - `vibosome_ai_fix` ## Approval Flow Some actions require human approval: - high-frequency `15min` schedules - dangerous shell commands - `curl | bash` style commands - package lifecycle scripts such as `postinstall` - replacing an existing file set - overwriting existing secret values - AI fixes that edit files or rerun jobs If approval is needed, Vibosome returns HTTP 409 with: ```json { "error": "Approval required", "approval": { "id": "appr_xxx", "status": "pending" } } ``` Tell the user: ```text Vibosome needs approval for appr_xxx: . Open Vibosome > Approvals, approve it if it looks right, then tell me "approved, continue". ``` After approval, retry the exact same original request with: ```json { "approvalId": "appr_xxx" } ``` Approvals expire after 20 minutes and are one-use. If expired, rerun the guarded request to create a new approval ID. ## Variables Variables are runtime values read by code from `process.env`. Examples: ```env OPENAI_API_KEY=sk-... DATABASE_URL=postgres://... NODE_ENV=production SUPPLIER_FEED_URL=https://example.com/feed.xml ``` Rules: - Do not store raw `.env` files as project files. - Add values through `envValues` or tell the user to use the dashboard Variables panel. - Secret values are masked after saving. - If the dashboard shows a blank saved-secret field, blank means "keep existing secret". - Do not print secret values in logs or explanations. ## Schedule Modes Supported modes: - `manual` - `15min` - `hourly` - `daily` - `weekly` Timezone values are GMT offsets such as: - `UTC` - `Etc/GMT-3` for GMT+03:00 - `Etc/GMT+5` for GMT-05:00 Always run once manually before activating a schedule. ## Runtime Default runtime: Node.js 22. Vibosome: - writes project files into a disposable workspace - installs dependencies from package files - injects saved variables into the process environment - runs the configured command - captures terminal logs - captures result files Recognized result files: - `output.json` - `result.json` - `output.txt` - `result.txt` Browser automation: - Playwright and Puppeteer Chromium support are prepared by the runtime. - Avoid downloading browsers inside every run when possible. Prisma: - OpenSSL support is prepared. - If Prisma warns, inspect logs but do not assume failure unless exit code or output indicates failure. ## Common Troubleshooting ### Missing variable Symptom: run says `Missing required values`. Fix: add the exact key in Variables or update `envValues`, save, then run again. ### `tsc: not found` Cause: TypeScript compiler is not available at runtime. Fix options: - move `typescript` to runtime dependencies - change command to run built JavaScript - include a build step that uses installed dependencies ### Playwright browser missing Cause: code launches Playwright but browser binary is unavailable. Fix options: - use Vibosome browser-ready runtime - update Playwright setup - avoid browser code paths when the job does not need them ### No output file Cause: script did not write a recognized result file. Fix: make the script write `output.json`, `result.json`, `output.txt`, or `result.txt` on success and on handled partial failure. ### Schedule did not run Check: - project status is active - schedule mode is not manual - next run time is saved - plan limits are not reached - previous run is not still active ### Success with warnings Exit code 0 means the process completed. Warnings may still indicate partial scrape failure, missing optional browser dependency, or missing result file. Explain the difference to the user and fix if the business output is incomplete. ## Final Report Format When finished, tell the user: - what changed - whether the latest verification run passed - what still needs human input, if anything - next scheduled run time if active Keep the explanation plain. Do not dump raw logs unless asked.