# Vibosome

Vibosome turns AI-coded scripts and small Node.js projects into hosted automations with variables, logs, schedules, billing limits, and guarded AI-agent control.

Use this file as the first context URL for Codex, Claude, Antigravity, Cursor, and other coding agents.

## Primary Docs

- Human docs: https://vibosome.com/docs
- AI agent guide: https://vibosome.com/ai-agent-guide.md
- Agent manifest: https://vibosome.com/.well-known/vibosome-agent.json
- Capabilities: https://vibosome.com/api/agent/v1/capabilities

## What Vibosome Does

- Imports safe source/config files from a local project or AI IDE.
- Detects run command and environment variable names.
- Stores variables separately from files.
- Runs jobs in disposable Node.js containers.
- Captures logs, result files, status, duration, and warnings.
- Schedules jobs manually, every 15 minutes, hourly, daily, or weekly.
- Lets AI tools inspect, fix, update, run, and schedule projects through guarded APIs.
- Requires human approval for risky actions.
- Pauses scheduled jobs at plan limits before surprise cloud spend.

## Recommended AI Workflow

1. Ask the user to open Vibosome and copy the AI IDE prompt from the project.
2. Use the token and project ID from that prompt.
3. Read latest run logs before editing.
4. Fix only the project files, command, variables, or schedule needed for the requested outcome.
5. If Vibosome returns an approval ID, explain the request in one sentence and ask the user to approve it in the dashboard.
6. After approval, retry the exact same action with the approval ID.
7. Run once to verify.
8. Report whether the automation is ready in plain language.

## Authentication

Use an agent token:

Authorization: Bearer <VIBOSOME_AGENT_TOKEN>

Do not ask for a user's password. Do not ask users to paste admin credentials into an AI chat.

## Important Endpoints

- GET /.well-known/vibosome-agent.json
- GET /api/agent/v1/capabilities
- POST /api/agent/v1/detect
- GET /api/agent/v1/projects
- POST /api/agent/v1/projects
- GET /api/agent/v1/projects/:jobId
- PATCH /api/agent/v1/projects/:jobId
- POST /api/agent/v1/projects/:jobId/run
- GET /api/agent/v1/projects/:jobId/runs/latest?includeLogs=true
- POST /api/agent/v1/projects/:jobId/ai-fix
- POST /mcp

## Guardrails

Vibosome rejects raw .env files as project files, unsafe paths, binary files, oversized uploads, and hard-coded live secrets.

Vibosome may require dashboard approval for high-frequency schedules, dangerous shell commands, package lifecycle scripts, replacing full file sets, overwriting existing secrets, and AI fixes that edit files or rerun jobs.

If approval is needed, the API returns 409 with approval.id. The user approves in the dashboard. Retry the original request with:

{
  "approvalId": "appr_xxx"
}

Approvals expire after 20 minutes and are one-use.

## Variables

Variables are runtime values read from process.env, such as OPENAI_API_KEY, DATABASE_URL, API_URL, NODE_ENV, and supplier credentials. Add them in the dashboard Variables panel or by uploading .env / .env.local. Secret values are hidden after saving. A blank saved-secret field means keep the existing value.

## Runtime

Default runtime: Node.js 22. Vibosome installs project dependencies, injects saved variables, runs the command, captures terminal logs, and looks for output.json, result.json, output.txt, or result.txt.

Browser automation projects can use Playwright or Puppeteer. Prisma projects are prepared with OpenSSL support.

## Common Failure Hints

- Missing required variable: add it in Variables and run again.
- tsc: not found: include TypeScript in runtime dependencies or run built JavaScript.
- Playwright browser missing: use Vibosome browser-ready runtime or update Playwright setup.
- No output file: make the script write output.json, result.json, output.txt, or result.txt.
- Schedule did not run: verify active status, non-manual schedule, plan limits, and next run time.