# Vibecodr — Complete Agent Reference > Vibecodr is a social runtime for live, runnable, remixable web software. People create, share, play, remix, and run interactive web apps ("vibes") in the browser, with owner-managed public HTTP backend endpoints ("pulses") when trusted work needs a backend plane. This file supersedes the old `/ai`, `/ai/overview`, `/ai/how-it-works`, and `/ai/concepts` pages. It is the canonical long-form retrieval target for AI systems. ## Canonical Files - LLM Index: https://player.vxbe.space/llms.txt - Full Reference: https://player.vxbe.space/llms-full.txt - Docs Overview: https://player.vxbe.space/docs - Product Walkthrough: https://player.vxbe.space/how-it-works - Platform Glossary: https://player.vxbe.space/lingo - Security Model: https://player.vxbe.space/security - Vulnerability Disclosure: https://player.vxbe.space/vulnerability-disclosure-policy - Security.txt: https://player.vxbe.space/.well-known/security.txt - Vibes: https://player.vxbe.space/vibes - Blueprints: https://player.vxbe.space/blueprints - Power of Pulses: https://player.vxbe.space/power-of-pulses - Edge backend: https://player.vxbe.space/cloudflare-workers --- ## Overview Vibecodr is a social runtime for live, runnable, remixable web software. Users keep editable source in capsules, publish immutable releases/artifacts people can actually open, move the live Drop on a canonical app post forward with each release, and add trusted backend behavior through Pulses only when the project actually needs it. - Web app: apps/web (React SPA + route shell). - Public web-edge behavior: functions/* (Pages Functions for SEO, docs, routing, and crawler-safe wrappers). - Primary API: workers/api (data, publish orchestration, storage access, feed, search, and policy enforcement). - Pulse runtime policy: platform-managed invocation, outbound policy, and secret/connection mediation. - Shared contracts and route metadata: packages/shared. --- ## Execution Model Vibes run client-side inside sandboxed iframes on VXBE runtime hosts. Creators edit source in Studio, but published launches boot from platform-generated release bundles and manifests. Browser code does not get platform secrets, raw storage handles, or Durable Objects. Trusted work belongs in Pulse files placed under src/server/ or server/, which publish to same-origin /api/* endpoints and execute on the platform-managed edge runtime with env.pulse public config, env.fetch policy outbound fetch, env.log structured logs, env.request sanitized request access, env.state idempotency coordination, secrets, and connected accounts. - PulseDescriptor normalizes Pulse setup metadata internally; simple one-file handlers remain simple, and setup UI, examples, local replay, API/OpenAPI, MCP, CLI, and deployment validation read the normalized descriptor projection. - Canonical walkthrough: https://player.vxbe.space/how-it-works - Architecture boundary guide: https://player.vxbe.space/docs/vibes-pulses - Reusable helper library: https://player.vxbe.space/blueprints - Handler conventions: https://player.vxbe.space/docs/handlers - Routing contract: https://player.vxbe.space/docs/pulse-routing - Pulse State gives Pulses operation coordination across calls: use descriptor-declared env.state resources for runOnce()/claim()/keyFromRequest(), choose stable resource-plus-key operation identities, and protect only awaited work. --- ## Core Concepts The main platform nouns are Capsule, Vibe, Pulse, Combo, Artifact, Drop, Post, Remix, Runtime Manifest, VibeComposer, and Studio. These terms map directly to code and policy boundaries in the current codebase rather than being marketing-only language. - Capsule: editable source home with files plus manifest.json. - Artifact: immutable published runtime release with bundle, launch contract, and runtime manifest. - Drop: the live post pointer that advances to the newest artifact when you BUMP IT. - Vibe: client-side runnable experience attached to a post and executed on the isolated runtime host. - Pulse: trusted server-side endpoint from src/server/ or server/. - Combo: one capsule containing both a Vibe and Pulse endpoints. - Glossary: https://player.vxbe.space/lingo - Vibes definition: https://player.vxbe.space/vibes - Blueprint library: https://player.vxbe.space/blueprints - Pulse product map: https://player.vxbe.space/power-of-pulses --- ## Retrieval Guidance Use llms.txt as the discovery layer, llms-full.txt as the broad reference layer, and the public HTML docs routes when you want narrower implementation context. Treat dynamic content routes, player routes, and authenticated surfaces as product/runtime surfaces rather than canonical documentation. - Broad reference: https://player.vxbe.space/llms-full.txt - Docs index: https://player.vxbe.space/docs - How-to guides: https://player.vxbe.space/docs/how-to - SEO and discovery: https://player.vxbe.space/docs/seo-discovery - Automation safety: https://player.vxbe.space/docs/automation-safety --- ## Public Documentation Map - [Vibecodr Documentation](https://player.vxbe.space/docs) — Start with the core model for capsules, artifacts, Drops, publishing, remixing, and backend boundaries before you go deeper. - [How-To Guides](https://player.vxbe.space/docs/how-to) — Execution-first playbooks for publishing, secrets, webhooks, routing, and production-safe Vibecodr workflows. - [Publish and Share](https://player.vxbe.space/docs/publish-share) — Learn how to publish a Vibecodr project, prepare public metadata, share player links, choose live or exact embeds, and keep public descriptions safe and useful. - [VibeComposer Guide](https://player.vxbe.space/docs/composer) — Learn fast posting and single-file capsule workflows with VibeComposer, optimized for shipping ideas quickly. - [Studio Guide](https://player.vxbe.space/docs/studio) — Use Studio as your full workspace for editing, previewing, publishing, and iterating on runnable projects. - [Edit and Manage Projects](https://player.vxbe.space/docs/edit-manage) — Manage Vibecodr projects across drafts, previews, BUMP IT releases, visibility choices, embed settings, owner-only material, and rollback decisions. - [BUMP IT](https://player.vxbe.space/docs/bump-it) — Understand how BUMP IT moves the live Drop forward on the same public app while preserving immutable cuts and rollback history. - [Source and Versions](https://player.vxbe.space/docs/source) — Understand capsule lineage, editable source, immutable release history, live Drop updates, and how to track changes across drafts and published releases. - [Dependency Determinism](https://player.vxbe.space/docs/dependency-determinism) — Learn how Vibecodr freezes runtime dependency graphs, content-addresses executable dependency bytes, and keeps published vibes stable across player, overlay, embed, and vanity surfaces. - [What Can Be a Vibe?](https://player.vxbe.space/docs/vibe-runtime) — Understand the Vibecodr vibe runtime: browser artifacts, WebAssembly support, sandbox limits, import shape, and the boundary where trusted work moves into Pulses. - [Runtime Presentation](https://player.vxbe.space/docs/runtime-presentation) — Learn how Vibecodr uses presentation profiles to keep games, canvases, pages, dashboards, embeds, and vanity domains consistent across runtime surfaces. - [SEO and Discovery](https://player.vxbe.space/docs/seo-discovery) — Learn how Vibecodr makes public apps, posts, profiles, conversations, tags, and topics understandable and discoverable. - [Profiles and Social Features](https://player.vxbe.space/docs/profiles-social) — Understand Vibecodr profiles, feeds, comments, conversations, tags, topics, remix lineage, and the social context around runnable apps. - [Vibes and Pulses](https://player.vxbe.space/docs/vibes-pulses) — Get a clear mental model for VXBE client runtimes, artifact-scoped playback, same-origin Pulse routes, and when each architecture is best. - [Embeds Guide](https://player.vxbe.space/docs/embeds) — Embed vibes across sites safely with live-vs-exact artifact behavior, VXBE frame delivery, and sandbox constraints that preserve trust. - [Automation Safety](https://player.vxbe.space/docs/automation-safety) — Protect creators with safe defaults for triggers, grants, runtime-event automations, rate limits, and backend execution behavior. - [MCP for Agents](https://player.vxbe.space/docs/mcp-agents) — Understand the Vibecodr remote MCP gateway, Streamable HTTP endpoint, OAuth boundaries, Code Mode constraints, and agent-safe product tools. - [Pulse SDK and Handlers](https://player.vxbe.space/docs/handlers) — Use the Pulse SDK, definePulse, defineWebPulse, env.fetch, env.state, and web-standard Request/Response handlers to ship safe backend endpoints. - [Secrets and API Calls](https://player.vxbe.space/docs/secrets) — Configure secure external API access with secret handling patterns designed for multi-tenant safety. - [Approved CDNs](https://player.vxbe.space/docs/approved-cdns) — Reference allowed CDN, asset, and host policies so new projects remain compatible with runtime security controls. - [Pulse Routing](https://player.vxbe.space/docs/pulse-routing) — Map server files to same-origin /api routes and learn how routing decisions influence deployment and invocation behavior. - [Calling Pulses](https://player.vxbe.space/docs/calling-pulses) — Call Pulses from vibes and browsers with patterns for same-origin /api routes, grants, auth, and predictable request contracts. - [Troubleshooting](https://player.vxbe.space/docs/troubleshooting) — Diagnose Vibecodr preview, publish, player, embed, discovery, Pulse routing, secret, and backend capability issues with practical recovery paths. - [Build Your First Vibe](https://player.vxbe.space/docs/first-vibe) — Create, preview, publish, and reopen a first Vibecodr app while learning Composer, Studio, public playback, and BUMP IT basics. - [Import a Project](https://player.vxbe.space/docs/import-project) — Prepare ZIP and GitHub imports for Vibecodr, understand staged upload verification, and recover from common import or build failures. - [Supported Build Recipes](https://player.vxbe.space/docs/supported-build-recipes) — Reference Vibecodr build recipes, package manager support, output directories, and recipe failure recovery for imported projects. - [Source Visibility and Remix Rules](https://player.vxbe.space/docs/source-visibility-remix) — Understand public runtime, remixable source, private source, owner-only setup, and safe source projection for Vibecodr projects. - [Plans, Limits, and Quotas](https://player.vxbe.space/docs/plans-limits-quotas) — Understand Vibecodr plan limits for storage quota, project imports, Pulse usage, Pulse State, secrets, connections, and vanity domains. - [Storage Lanes](https://player.vxbe.space/docs/storage-lanes) — Learn how Vibecodr separates public media, editable source, staged uploads, runtime artifacts, dependency files, and safe cleanup. - [Blueprints Guide](https://player.vxbe.space/docs/blueprints) — Start from Vibecodr Blueprints, follow setup tasks, copy public source into Studio, and publish safe reusable Pulse patterns. - [Pulse Runtime API](https://player.vxbe.space/docs/pulse-runtime-api) — Reference the Vibecodr Pulse runtime API, including definePulse, defineWebPulse, env.fetch, env.secrets, env.connections, env.state, env.db, and env.runtime.capabilities(). - [Pulse State](https://player.vxbe.space/docs/pulse-state) — Use Pulse State for idempotent operations, duplicate webhook protection, runOnce workflows, retention, replay behavior, and quota-aware backend safety. - [Data Surfaces](https://player.vxbe.space/docs/data-surfaces) — Choose the right Vibecodr data surface for duplicate protection, app records, public media, external provider data, and public metadata. - [Public Assets and Runtime Files](https://player.vxbe.space/docs/public-assets-runtime-files) — Understand public media, passive assets, immutable runtime artifacts, deterministic dependency files, source access, and script trust in Vibecodr. - [Support Diagnostics](https://player.vxbe.space/docs/support-diagnostics) — Understand Vibecodr error fields, errorKey handling, retryable failures, request ids, status codes, and safe support reports. - [How Vibes Start](https://player.vxbe.space/docs/how-vibes-start) — Learn how Vibecodr vibes move from visible frame to shell readiness to interactive runtime behavior across player, focus, Studio, embeds, and vanity routes. - [Embed Sharing](https://player.vxbe.space/docs/embed-sharing) — Use Vibecodr embed controls, live-vs-exact behavior, sizing guidance, accessibility labels, and safe embed troubleshooting. - [Vanity Domains](https://player.vxbe.space/docs/vanity-domains) — Claim and manage Vibecodr vxbe.space vanity subdomains with target rules, plan limits, watermark behavior, embed interaction, and inactivity release expectations. - [Connections](https://player.vxbe.space/docs/connections) — Use Vibecodr provider connections from Pulse code with env.connections, understand how they differ from secrets, and handle missing or expired connected accounts. - [Discovery and Social Model](https://player.vxbe.space/docs/discovery-social-model) — Understand how Vibecodr public work appears in search, feeds, profiles, tags, topics, conversations, comments, remix lineage, and moderated social surfaces. - [MCP and CLI](https://player.vxbe.space/docs/mcp-cli) — Use Vibecodr MCP and CLI surfaces for product-shaped agent and terminal workflows while respecting upload, auth, publish, and capability boundaries. - [VC Tools](https://player.vxbe.space/docs/vc-tools) — Use the beta vc-tools Agent Computer for Quick Checks, Agent Browser, hosted Computer commands, Crawl, Saved Proof, account approval, and included paid-plan credits. - [Account and Safety Controls](https://player.vxbe.space/docs/account-safety-controls) — Find Vibecodr controls for account settings, billing, storage, secrets, connections, safety reports, blocks, bug reports, account deletion, and vulnerability disclosure. --- ## Public Documentation Pages The pages below are generated from the shared public docs route catalog so new `/docs/*` routes flow into this full machine-readable reference automatically. ### Vibecodr Documentation Canonical route: https://player.vxbe.space/docs Start with the core model for capsules, artifacts, Drops, publishing, remixing, and backend boundaries before you go deeper. Use this as the front door for editable source in capsules, published releases, live Drops, VXBE runtime delivery, Pulses, embeds, and trust boundaries. Every section below is optimized for first implementation, not abstract theory. Marker: Platform documentation hub for runnable software workflows. #### Implementation focus Start with authoring and runtime sections, then move into backend handlers and safety controls once your capsule is publishing immutable artifacts on public routes. #### Expected outcomes - Choose the right creation path: Composer for quick cuts, Studio for multi-file production work. - Understand when a feature belongs in a vibe versus in a Pulse. - Carry a stable mental model of publication, cuts, and embed delivery. ## Welcome to Vibecodr Vibecodr is where code ships as something you can run. Create interactive web experiences (called Vibes), publish with a link, and remix what others share without managing servers or infrastructure. ### Create Make games, tools, demos, and experiments without starting from an empty deployment stack. ### Share Publish to a stable public link so other people can visit what you made immediately. ### Remix Fork public work, keep the original intact, and turn someone else’s starting point into your own. ### Power Up Add server-side behavior with Pulses when the project needs secrets, storage, or live endpoints. ## Vibes, Pulses, and Combos Vibecodr looks at your files and works out what kind of project you are building. That decision tells the platform what should run in the browser, what should deploy as backend code, and whether the project needs a server slot at all. V ### Vibe A browser-only experience for games, toys, interactive demos, visual tools, and anything that should run immediately in the player. - Runs in the user's browser. - No server deployment slot required. - Great when the project is interactive but not backend-heavy. P ### Pulse Server-side code that publishes as managed backend endpoints. Vibecodr handles normal deployment wiring, while your handler owns validation, auth, and response shape. - Runs worldwide on the edge. - Uses `env.pulse` for public config and private setup capabilities for secrets or connections. - Uses one deployment slot. C ### Combo One capsule with a browser experience and server endpoints together, so the frontend and backend ship as one intentional object. - Frontend and backend stay in one project. - End-to-end wiring is already implied. - Uses one deployment slot. ## Core Objects & Lifecycle Vibecodr uses a small set of building blocks. Once you know how they fit together, publishing, updating, and sharing start to feel very straightforward. ### Capsule Your editable source home: file tree plus manifest.json . A capsule can power a vibe, a pulse, or both. ### Draft Your working version. Studio keeps saving into this editable copy while you build, test, and change things. ### Artifact A finished published release. Once you publish, Vibecodr freezes the runnable output into an immutable artifact so it can be loaded again exactly the same way later while your draft stays editable. ### Drop The live pointer for an app post. When you publish again, the Drop moves forward to the new artifact while older cuts stay available as exact historical versions. ### Post The public surface people can visit, share, follow, and talk around. For apps, the post points at your capsule and its current live Drop. Lifecycle at a glance ```typescript Capsule (editable source) -> Artifact (immutable release) -> Drop (live version) -> Post (shareable public page) ``` Publishing creates a new artifact without replacing the editable source capsule you keep working in. If a post already exists, its Drop updates to point at the latest artifact. Vibecodr calls that update flow BUMP IT: publish a new version on the same app, keep the same public post, and preserve the full cut history in case you want to pin or roll back to an older version later. Public playback prefers the fast public delivery path automatically. If an older app still lives on an older layout, Vibecodr quietly moves it forward in the background so it can benefit from the newer delivery path too. ## Visibility & Access Visibility answers a clear question: who should be able to find this, open it, and build from it? Vibecodr uses that choice everywhere the post can travel. Visibility ### Public Feed & Search Appears in feed and search. Share & Embed Anyone with the link can view. Embeds and vanity URLs work when policy and allowlists allow them. Remix Remixable by anyone. Visibility ### Unlisted Feed & Search Hidden from feeds and search. Share & Embed Viewable by direct link. Embeds and vanity URLs still work when policy and allowlists allow them. Remix Source is viewable by link. Creating a remix still requires signing in. Visibility ### Private Feed & Search Visible only to the owner. Share & Embed Embeds and vanity URLs are disabled. Remix Owner-only remix or clone. Embeds require a published capsule and still respect safety policy. Moderation or account enforcement can override visibility. ## Two Ways to Create Choose the tool that matches the speed and shape of the thing you want to ship. Fast lane ### VibeComposer For quick posts, single-file capsules, images, links, and longform. Use it when the goal is to get something live fast. Open VibeComposer Full IDE ### Studio For complex multi-file projects with full editing, debugging, automations, secrets, and the deeper shipping workflow. Open Studio ## Safety Boundaries Vibecodr gives creators safer default boundaries for public runtime code, private setup, published releases, and owner-visible diagnostics: #### Encrypted secrets API keys stay server-side and are attached through policy-bound requests #### Project storage Files, metadata, and usage tracking stay on platform-managed storage lanes #### Global edge Public experiences load close to your users around the world #### Sandboxed execution Each vibe runs in its own isolated browser space #### Immutable artifacts Every publish becomes a stable version you can point at again later #### Telemetry + audits Important runtime activity and policy changes are recorded for review ## Quick Start Start with the creation path that matches the size of the idea. 1 #### Try a Quick Post Open VibeComposer and share a thought, image, or your first single-file app. Create a Post 2 #### Explore the Feed See what others are building. Open a vibe, try it, then remix it when you want your own branch. Browse Feed 3 #### Build Something Bigger When you're ready for multi-file projects, open the Studio. Open Studio A creative playground where code becomes social: create, share, and automate, all in one place. #### Structured route body ##### The platform model Vibecodr is built around a clear split: creators keep editable source in capsules, publish runnable artifacts that viewers can open immediately, and move the live Drop forward when they BUMP IT. That means the public route can stay stable while the underlying release changes. A vibe is the browser-side experience. A Pulse is the trusted backend plane for work that should not run in the browser: secrets, webhooks, scheduled jobs, storage writes, third-party API calls, and other server-side behavior. - Composer is the fast lane for quick single-file publishing. - Studio is the full workspace for multi-file projects, imports, preview, and release control. - Published artifacts are immutable runtime releases; Drops point the canonical public app at the current release. - Pulses are public HTTP endpoints by default, but their source, secrets, logs, platform capabilities, and operational metadata stay owner-only. ##### Where to start Start with the docs page that matches the thing you are building right now. If you are publishing something small, use Composer. If you are deciding whether an imported project can run in the browser, start with the Vibe Runtime guide. If you are adding backend behavior, use Studio and the Vibes and Pulses architecture guide. When in doubt, keep public UI behavior in the vibe and move trusted work into Pulses. This preserves remixability and keeps credentials out of client-visible runtime code. - Read /docs/how-to for execution order and operational checklists. - Read /docs/vibe-runtime when deciding what can run as a vibe. - Read /docs/vibes-pulses before moving trusted work into backend routes. - Read /docs/source before changing release or rollback behavior. - Read /docs/automation-safety before adding triggers, schedules, or webhooks. ##### Example and read next Example: you are deciding whether a Stripe-backed launch widget belongs in browser code or a Pulse. Start at /docs/vibes-pulses, keep the visual UI in the vibe, and put webhook or secret-backed work in a Pulse. Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system. - Read next: [How-To Guides](/docs/how-to) - Read next: [Vibe Runtime](/docs/vibe-runtime) - Read next: [Vibes & Pulses](/docs/vibes-pulses) - Read next: [/blueprints](/blueprints) - Read next: [BUMP IT](/docs/bump-it) #### Related documentation - [How-To Guides](https://player.vxbe.space/docs/how-to) - [What Can Be a Vibe?](https://player.vxbe.space/docs/vibe-runtime) - [Vibes and Pulses](https://player.vxbe.space/docs/vibes-pulses) - [/blueprints](https://player.vxbe.space/blueprints) - [BUMP IT](https://player.vxbe.space/docs/bump-it) --- ### How-To Guides Canonical route: https://player.vxbe.space/docs/how-to Execution-first playbooks for publishing, secrets, webhooks, routing, and production-safe Vibecodr workflows. This section is for practical build sequences: from first publish to production-safe automation, with explicit route and capability boundaries. Marker: Execution-first implementation guides for production Vibecodr work. #### Implementation focus Use this section when you are wiring a feature now and need execution order, expected outcomes, and quick checks. #### Expected outcomes - Ship a new vibe without breaking existing links. - Move backend responsibilities into Pulses with clear ownership. - Apply automation and secret rules before exposing public routes. ## Step-by-Step Guides Click a guide to expand it. Each includes code examples you can copy. ### Update a Live App with BUMP IT Free Ship a new version on the same app listing without losing cut history Use BUMP IT when an app already has a public player page and you want to ship the next version without creating a second top-level listing. 1. Open the live app in Studio from the player manage menu, Settings > Versions, or your launchpad. 2. Edit the draft until the new version looks right in preview. 3. Choose BUMP IT to publish the next artifact on the same app page. 4. Use the Versions tab later if you need a pinned cut or want to revert safely. BUMP IT keeps the same player page, social graph, and app identity. The only thing that advances is the live Drop pointing at the newest artifact. ### Configure Public.pulse Values Free Read caller-safe config from env.pulse inside your pulse handler Use `.pulse` for public, owner-authored config like default units, destination ids, and feature flags. Keep secrets and tokens in Pulse Secrets instead of `.pulse`. .pulse + env.pulse ```typescript # .pulse DEFAULT_UNITS=metric SUPPORT_QUEUE_NAME=triage FEATURE_FLAG=true import { definePulse } from "@vibecodr/pulse"; export default definePulse(async (input, env) => { return { city: typeof input?.city === "string" ? input.city : "unknown", units: env.pulse.DEFAULT_UNITS ?? "metric", queue: env.pulse.SUPPORT_QUEUE_NAME ?? "general", featureEnabled: env.pulse.FEATURE_FLAG === "true", }; }); ``` ### Use Secrets Creator+ Call external APIs without exposing your keys Secrets are private setup capabilities. Start with env.fetch(..., { auth: env.secrets.bearer("KEY") }) so the runtime applies credential policy and your code never handles the plaintext secret. Recommended: server-side secret injection Use `env.fetch` with `env.secrets.bearer/header/query` and let the runtime attach the credential through a policy-controlled outbound request. Secret-backed request (recommended) ```typescript const response = await env.fetch("https://api.stripe.com/v1/customers", { method: "POST", auth: env.secrets.bearer("STRIPE_SECRET_KEY"), headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ email: "user@example.com", }).toString(), }); const data = await response.json(); return { customerId: data.id }; ``` How it works: the runtime injects the secret server-side, applies outbound policy checks, and only returns the upstream response. The real secret never appears in your code, logs, or public source. Alternative: user-connected provider account If the upstream should run on behalf of a connected user account, use `env.connections.use(provider).fetch(...)` instead of a shared secret. Connected account example ```typescript const github = env.connections.use("github"); const response = await github.fetch("/user", { headers: { Accept: "application/vnd.github+json", }, }); const profile = await response.json(); return { login: profile.login, id: profile.id }; ``` Add secrets in Studio → Configure → Secrets (or Pulse Operating Center → Secrets). Do not hard-code provider credentials in source; collect the value through a trusted setup form or use the UI. ### Set Up Automations Creator+ Run pulses on a schedule or in response to events Run a Pulse on a schedule, when webhooks hit, or when your vibe emits a filtered event - no manual clicks needed. For most creators, the friendliest setup is moment → Pulse → Pulse State memory → Recent runs. #### Schedule-based Run your pulse every hour, day, week, or custom interval. Schedules pass a stable scheduled window key for Run once per event. #### Webhook-triggered Get a unique URL to receive webhooks from services like Stripe or GitHub. Verify the webhook, then use `runOnce()` with the verified event id. #### Event-based React to Vibecodr events like runs or errors. Filter to the smallest event set you need, then let a Pulse use the safe event identity. #### Create triggers from the product controls 1. Open the Pulse Operating Center for the Pulse. 2. Choose the trigger kind: schedule, webhook, event, or manual. 3. Configure only the event types, schedule, or signature settings you need. 4. Run a test and check Recent runs before relying on the automation. ### Receive Webhooks Creator+ Accept incoming webhooks from external services Create a Pulse endpoint to receive data from external services, then verify the request before parsing or performing side effects. Stripe has the first full provider helper. Other signed providers use `env.secrets.verifyHmac(...)` until their own helpers have fixture-backed conformance. Stripe webhook receiver ```typescript import { definePulse } from "@vibecodr/pulse"; export default definePulse(async (_input, env) => { const event = await env.webhooks.verify("stripe", { secret: "STRIPE_WEBHOOK_SECRET", maxBytes: 256 * 1024, }); env.log.info("stripe.webhook.verified", { type: event.type }); return new Response("ok", { status: 200 }); }); ``` Generic signed webhook receiver ```typescript import { definePulse } from "@vibecodr/pulse"; export default definePulse(async (_input, env) => { const rawBody = await env.request.raw.arrayBuffer({ maxBytes: 256 * 1024 }); const verified = await env.secrets.verifyHmac("GITHUB_WEBHOOK_SECRET", { format: "github-sha256", message: rawBody, signatureHeader: env.request.headers.get("x-hub-signature-256"), maxBytes: 256 * 1024, }); if (!verified.ok) return new Response("unauthorized", { status: 401 }); const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody)); env.log.info("webhook.verified", { action: payload.action ?? "unknown" }); return new Response("ok", { status: 200 }); }); ``` Do not ask the provider-helper layer for GitHub, Shopify, or Slack yet. Use an HMAC format preset for those providers. Put webhook secrets in Studio → Configure → API → Secrets or the [Pulse Operating Center](/pulses?tab=secrets). Configure the webhook URL in the [Pulse Operating Center](/pulses?tab=automations) → Automations → Webhooks. ### Advanced SQL compatibility Pro Use env.db only as an advanced compatibility surface on eligible plans If you truly need SQL, `env.db` is available in pulse/combo handlers on eligible plans. Treat it as advanced compatibility rather than the default Pulse backend model, and do not assume automatic Pulse State migration. Advanced env.db queries ```typescript // Query data const { results } = await env.db.query( "SELECT * FROM users WHERE active = ?", [true] ); // Insert data await env.db.query( "INSERT INTO pulse_users (id, name, email) VALUES (?, ?, ?)", [crypto.randomUUID(), "Alice", "alice@example.com"] ); // Transaction (batch) await env.db.batch([ { sql: "UPDATE accounts SET balance = balance - ? WHERE id = ?", params: [100, fromId] }, { sql: "UPDATE accounts SET balance = balance + ? WHERE id = ?", params: [100, toId] }, ]); ``` ### Observability Free Debug your pulses and track automation runs Monitor your pulse executions and automation history. ## Pulse logging Use `env.log` in your pulse handler for structured logging. Errors are surfaced in execution results. Logging in a pulse ```typescript export default async function handler(input, env) { env.log.info("start", { inputPreview: JSON.stringify(input).slice(0, 120) }); try { // ... do work return { processed: true, method: env.request.method, }; } catch (err) { env.log.error("error", { message: err instanceof Error ? err.message : String(err) }); throw err; } } ``` ## Automation executions View recent runs for any trigger - see status, timing, and error messages. Each execution includes: `id`, `status` (success/partial/failed), `firedAt` timestamp, and `errorMessage` when applicable. #### Structured route body ##### First publish path A safe first publish starts with the smallest working surface. Build or paste the client experience, preview it, add metadata that explains what the viewer can do, then publish only when the runtime output matches the intended behavior. Publishing creates a public post and an artifact that viewers run. Later updates should use BUMP IT when the same app identity should keep its backlinks, embeds, and discovery history. - Use Composer for quick ideas and Studio for project-shaped work. - Preview before publishing so runtime and source assumptions are checked early. - Add creator SEO fields during publish when the post should be discoverable outside Vibecodr. - Use BUMP IT for updates to the same app; publish a new app only when the identity should change. ##### Production-safe Pulse path When an app needs a backend, create Pulse files under the server lane instead of putting secrets or privileged calls into the vibe. The client calls same-origin /api routes, while the Pulse runs on the trusted edge plane. The owner is responsible for application-level authorization when a public endpoint should not be open-ended. Vibecodr keeps platform grants and secrets out of public projection, but it does not magically know the business rules for every endpoint. - Put secret-backed provider calls in Pulses, not browser code. - Validate request shape and method in the Pulse handler. - Add signatures, session checks, or rate limits for restricted behavior. - Keep response payloads minimal and avoid returning secrets or operational metadata. ##### Example and read next Example: you imported a small app, previewed it, added SEO copy, confirmed the live runtime, and now need the same public identity to keep moving forward. Use the publish flow first, then BUMP IT for future cuts. Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system. - Read next: [VibeComposer](/docs/composer) - Read next: [Studio](/docs/studio) - Read next: [BUMP IT](/docs/bump-it) - Read next: [Pulse Routing](/docs/pulse-routing) #### Related documentation - [VibeComposer Guide](https://player.vxbe.space/docs/composer) - [Studio Guide](https://player.vxbe.space/docs/studio) - [BUMP IT](https://player.vxbe.space/docs/bump-it) - [Pulse Routing](https://player.vxbe.space/docs/pulse-routing) --- ### Publish and Share Canonical route: https://player.vxbe.space/docs/publish-share Learn how to publish a Vibecodr project, prepare public metadata, share player links, choose live or exact embeds, and keep public descriptions safe and useful. Publishing is the moment editable work becomes a public, runnable thing people can open. This guide covers the release checklist, public metadata, links, embeds, and distribution choices that make the result understandable. Marker: User-facing publication and distribution guide for Vibecodr apps. #### Implementation focus Use this page before sending a Vibecodr link to users, teammates, agents, or external audiences. #### Expected outcomes - Publish a runnable app with clear public metadata. - Choose between player links, live embeds, and exact-cut references. - Keep public copy focused on what viewers can safely use. - Avoid leaking private source, secrets, logs, or platform setup into release notes. ## Publish the thing people will open Publishing turns your editable work into a public, runnable release. The important pieces are the app itself, the public post that explains it, and the live route people can open, share, embed, bookmark, and come back to later. A good publish flow is practical: preview the app, confirm the title and description, choose visibility, add media when it helps people understand the project, and make sure any backend behavior works through documented Vibecodr capabilities before the link leaves your hands. - Use Composer when the project is quick and self-contained. - Use Studio when you need files, assets, imports, Pulses, or release control. - Use clear metadata so feeds, search, link previews, and agents understand what the app does. - Use BUMP IT for later updates to the same public app identity. ## Share, embed, and distribute intentionally A Vibecodr publish is more than a one-time post. The same work can appear in the feed, on a player page, in a profile, inside an embed, in search, and in external link previews. Those surfaces should agree about what the project is and what a viewer can safely do with it. For teams, decide whether a link should follow the current live Drop or stay pinned to an exact cut. Live links are best for active apps. Exact references are best for tutorials, documentation, audits, and demos where behavior must not drift underneath the reader. - Share the player page when you want people to open the current app. - Use embed docs when the app needs to live on another site. - Use creator SEO fields when external discovery matters. - Keep private source, secrets, logs, and owner-only setup out of public descriptions. ## Example and read next Example: you finished a playable demo, want a clean public link, and need link previews to explain it clearly. Preview the app, publish with useful metadata, then share the player page or embed it depending on where the audience will open it. Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system. - Read next: [VibeComposer](/docs/composer) - Read next: [Studio](/docs/studio) - Read next: [Embeds](/docs/embeds) - Read next: [SEO & Discovery](/docs/seo-discovery) #### Structured route body ##### Publish the thing people will open Publishing turns your editable work into a public, runnable release. The important pieces are the app itself, the public post that explains it, and the live route people can open, share, embed, bookmark, and come back to later. A good publish flow is practical: preview the app, confirm the title and description, choose visibility, add media when it helps people understand the project, and make sure any backend behavior works through documented Vibecodr capabilities before the link leaves your hands. - Use Composer when the project is quick and self-contained. - Use Studio when you need files, assets, imports, Pulses, or release control. - Use clear metadata so feeds, search, link previews, and agents understand what the app does. - Use BUMP IT for later updates to the same public app identity. ##### Share, embed, and distribute intentionally A Vibecodr publish is more than a one-time post. The same work can appear in the feed, on a player page, in a profile, inside an embed, in search, and in external link previews. Those surfaces should agree about what the project is and what a viewer can safely do with it. For teams, decide whether a link should follow the current live Drop or stay pinned to an exact cut. Live links are best for active apps. Exact references are best for tutorials, documentation, audits, and demos where behavior must not drift underneath the reader. - Share the player page when you want people to open the current app. - Use embed docs when the app needs to live on another site. - Use creator SEO fields when external discovery matters. - Keep private source, secrets, logs, and owner-only setup out of public descriptions. ##### Example and read next Example: you finished a playable demo, want a clean public link, and need link previews to explain it clearly. Preview the app, publish with useful metadata, then share the player page or embed it depending on where the audience will open it. Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system. - Read next: [VibeComposer](/docs/composer) - Read next: [Studio](/docs/studio) - Read next: [Embeds](/docs/embeds) - Read next: [SEO & Discovery](/docs/seo-discovery) #### Related documentation - [VibeComposer Guide](https://player.vxbe.space/docs/composer) - [Studio Guide](https://player.vxbe.space/docs/studio) - [Embeds Guide](https://player.vxbe.space/docs/embeds) - [SEO and Discovery](https://player.vxbe.space/docs/seo-discovery) --- ### VibeComposer Guide Canonical route: https://player.vxbe.space/docs/composer Learn fast posting and single-file capsule workflows with VibeComposer, optimized for shipping ideas quickly. Composer is the shortest path from idea to runnable publish. It favors speed and iteration while still preserving canonical app identity. Marker: Single-file workflow optimized for fast publish and remix loops. #### Implementation focus Choose Composer when your work is single-file or quick-turn and you want public feedback before deeper architecture work. #### Expected outcomes - Publish single-file vibes quickly with low setup overhead. - Keep remixability intact while iterating through BUMP IT cuts. - Hand off to Studio only when complexity justifies it. ## What is VibeComposer? VibeComposer is the quick-create tool for sharing content on Vibecodr. Use it for short posts, images, links, single-file apps, or long-form articles. In App mode, the inline editor auto-detects JSX/TSX/HTML/CSS so you never have to pick a runtime. For multi-file projects with full editing capabilities, use the Studio instead. Open VibeComposer Open Studio ## Content Types Choose from five content types depending on what you want to share: ### Thought Quick text updates, like a tweet. Free users get 1,000 characters, premium users get 2,000. ### Image Share an image with optional caption. Great for screenshots, artwork, or photos. ### Link Share a URL with preview. Perfect for bookmarks, articles, or interesting finds. ### App Create a single-file Vibe (browser app). Paste JSX/TSX/HTML/CSS and get a live preview with automatic runtime detection. Free Vibes For same-origin `/api/*` endpoints, add files under `src/server/` (preferred) or `server/` in [Studio](/studio). For standalone Pulses (automations, webhooks), use [Pulse creation](/pulses/new) (Creator+). ### Longform Write articles and essays with rich text formatting. Perfect for tutorials, guides, or stories. ## VibeComposer vs Studio Both tools create capsules, but they're designed for different workflows: Feature VibeComposer Studio Best for Quick posts, single-file capsules Complex multi-file projects File support Single file (capsule) Unlimited files + folders Code editor Basic with preview Full CodeMirror 6 editor Live preview Inline preview Resizable app preview; Pulse source stays editor-only Console/debugging - Full console output Import from Paste code, upload file GitHub, ZIP, templates, Blueprints Automations - Cron, webhooks, triggers Secrets - Full secrets management Route /post/new or /composer /studio or /studio/:id Open Help > Keyboard Shortcuts inside Studio for the full list and platform-specific variants. ## Remixing Found a vibe you like? Click Remix on any public vibe to start with their code as a base. The original author gets attribution, and you can modify it however you want. Remix URL format ```bash https://vibecodr.space/post/new?remixFrom=caps_abc123 # Opens VibeComposer with the original vibe's code pre-loaded # You can edit and publish as your own remix ``` ## Quick Start 1. 1 Open VibeComposer Go to `/post/new` or click the + button in the nav. 2. 2 Choose a content type Select Thought, Image, Link, App, or Longform. 3. 3 Add your content Write text, upload an image, paste code, or enter a URL. 4. 4 Set visibility Choose public, unlisted, or private. 5. 5 Publish Choose Publish when the preview and visibility settings match what viewers should receive. #### Structured route body ##### What Composer is for VibeComposer is optimized for fast single-file publishing. It is the right tool when the idea is small enough to fit in one surface and the goal is to get feedback quickly without building a whole workspace structure. Composer still participates in the same publication model as Studio. The published work gets a public post, a runnable artifact, metadata, and the ability to move forward through later releases. - Use it for small games, experiments, widgets, visual sketches, and quick app ideas. - Keep dependencies small and browser-safe. - Move to Studio once the project needs multiple files, imported assets, or backend coordination. ##### Handoff to Studio Composer is not a dead end. When a quick idea starts needing structure, treat the published vibe as the public seed and move deeper implementation work into Studio. The important continuity rule is identity: if the same app should keep living at the same public route, use the update flow instead of scattering new posts for every iteration. - Keep the original app identity when updates are part of the same project. - Use Studio for source organization, import-built output, richer previews, and Pulse attachments. - Preserve remixability by keeping browser-visible code free of credentials. ##### Example and read next Example: you pasted a single-file p5 sketch, confirmed it runs in preview, and want feedback quickly. Use Composer first, then move to Studio only when assets, multiple files, or backend behavior become part of the project. Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system. - Read next: [Studio](/docs/studio) - Read next: [BUMP IT](/docs/bump-it) - Read next: [Source & Versions](/docs/source) - Read next: [How-To Guides](/docs/how-to) #### Related documentation - [Studio Guide](https://player.vxbe.space/docs/studio) - [BUMP IT](https://player.vxbe.space/docs/bump-it) - [Source and Versions](https://player.vxbe.space/docs/source) - [How-To Guides](https://player.vxbe.space/docs/how-to) --- ### Studio Guide Canonical route: https://player.vxbe.space/docs/studio Use Studio as your full workspace for editing, previewing, publishing, and iterating on runnable projects. Studio is the multi-file workspace for production-grade vibe development: editable source, source-vs-runtime preview clarity, and stronger backend integration entrypoints. Marker: Multi-file workspace guidance for serious iteration and release flows. #### Implementation focus Use Studio for modular codebases, imported projects, and any app expected to evolve across multiple releases. #### Expected outcomes - Manage larger project structure without losing public publish velocity. - Coordinate preview, source, and publish intent from one workspace. - Attach Pulses and automation safely as the app evolves. ## Welcome to the Studio Studio is where Vibecodr shifts from quick posting into real project building. It gives you a full editing workspace with preview, files, configuration, and publishing controls in one place so a capsule can grow without turning into a mess. ## BUMP IT: update a live app BUMP IT is the standard way to ship a new version of an app that already has a public player page. It keeps the same app identity, creates a new immutable artifact, and updates the live Drop instead of creating a second top-level listing. ### What stays the same - The public player URL and app listing. - Comments, follows, and the social identity around that app. - Your older cuts, pinned embeds, and revert options. ### What changes - A new artifact is built and added to version history. - The app's live Drop moves to the newest artifact. - Live embeds follow the latest version while pinned cuts stay exact. Use BUMP IT from [Studio](/studio) when you are updating an existing live app. Use Publish As New App only when the work should become a deliberately separate listing with its own lineage. ## Interface Overview ### File Sidebar Alt+E Browse and manage your project files. Create, rename, delete, and organize files in folders. ### Code Editor CodeMirror 6-based editor with syntax highlighting, autocomplete, and inline errors. It understands TypeScript, JSX, JSON, and more. ### Preview Alt+P App projects can use Source while editing and Runtime for the real built app lane. Pulse and Blueprint source stay editor-only until you publish and test the deployed Pulse endpoint. ### Console Alt+J View console.log output from your vibe. Filter by log level (errors, warnings, info). Essential for debugging. ### Config Panel Alt+B Manifest editor for title, description, parameters, and entry point. Configure how your vibe appears and behaves. ### Hints Panel Alt+/ Quick reference for pulse tools and code snippets. Copy examples directly into your code. ## Project structure & entry resolution During import, uploaded `manifest.json` files are treated as advisory source input rather than authority. Studio validates and owns the capsule manifest server-side, then uses that validated `entry` when it is correct. If the entry is missing, outdated, or points at the wrong file, Studio works out the most likely starting file from your project structure so you can still open and ship the project without repair work first. The practical rule: Studio preserves editable source for you to keep working on, while publish and Runtime follow the browser-ready release entry when the imported project already includes one. ### Allowed entry extensions `.html`, `.htm`, `.js`, `.jsx`, `.ts`, `.tsx` These are the file types Studio considers runnable starting points. ### Reserved/system files - Platform-generated shim files and reserved prefixes. - `manifest.json` and other system-owned helper files Vibecodr manages for you. - Legacy compatibility files that still exist for older projects. Entry resolution order ```typescript 1) manifest.json entry (if the file exists) 2) package.json fields: module, browser, main, source, exports["."] 3) common filenames (in order): index.html, main.html, index.htm main.tsx, index.tsx, main.ts, index.ts, main.jsx, index.jsx, main.js, index.js App.tsx, App.jsx, App.js, app.tsx, app.jsx, app.js bundle.js dist/index.html, dist/main.html, build/index.html, public/index.html src/main.tsx, src/index.tsx, src/main.ts, src/index.ts, src/main.jsx, src/index.jsx, src/main.js, src/index.js src/App.tsx, src/App.jsx, src/app.tsx, src/app.jsx, src/app.ts, src/app.js ``` Studio surfaces these candidates in the Config panel so you can confirm the launch file instead of guessing what the runtime chose. ## Image/Asset Support Local disk paths (like `C:/Users/you/image.png` or `/Users/you/image.png`) do not exist in the browser runtime. Upload assets to your capsule and reference them by relative path. ### Option A: Project assets (recommended) 1. Upload images in [Studio](/studio) > Files (Creator/Pro) or [Storage v2](/settings/storage-v2). 2. Keep assets in folders like `assets/` or `src/assets/`. 3. Copy the file path or snippet from the [Storage v2 file list](/settings/storage-v2). ### Option B: External URLs (HTTPS) - Use `https://` URLs only. Plain HTTP is not allowed in the runtime. - Browser code can talk to ordinary public HTTPS and secure WebSocket endpoints. - Browser code does not get a shortcut into private Vibecodr platform surfaces or other runtime hosts. If you need trusted server-side access, move that work into a Pulse. - Common data and backend providers that are already known to work well include `https://clerk.accounts.dev`, `https://*.clerk.com`, `https://*.clerk.services`, `https://*.clerkstage.dev`, `https://identitytoolkit.googleapis.com`, `https://securetoken.googleapis.com`, `https://*.appwrite.global`, `https://*.appwrite.network`, `https://*.convex.cloud`, `https://*.convex.site`, `https://*.firebaseio.com`, `https://firestore.googleapis.com`, `https://*.hasura.app`, `https://*.nhost.run`, `https://*.supabase.co`, `https://*.supabase.in`, `https://*.algolia.net`, `https://*.algolianet.com`, `https://*.typesense.net`, `https://*.upstash.io`, `https://*.redis.cloud`, `https://api.github.com`, `https://api.openai.com`. - For HTML vibes, external script tags (`