Bitrix24 Vibecode Tutorial: Build Your First App with Claude Code or Cursor

What Vibecode Actually Builds - and What It Does Not

Vibecode is Bitrix24's official platform for building apps without traditional development: an AI agent reads your plain-language description, writes the code, spins up a cloud server, and deploys a working tool in one to two minutes - but it operates on top of Bitrix24 via REST API, not inside the core, so deep kernel changes or direct database access are not possible in the cloud version.

Launched on 15 March 2026, Alaio Vibecode describes itself as "the official platform for building Bitrix24 applications," with a single API key opening access to account data, AI models, servers, and the bot platform. According to the official helpdesk article (25 September 2026), "it works best for quick internal apps, idea testing, and tools that solve immediate team needs" and "does not replace development for every task."

What you can realistically build in one session:

• A CRM widget that pulls aggregated contact data across multiple entities into a deal card
• A notification bot that listens for portal events (new deal, status change) and sends a message to a specific chat
• A daily digest bot that summarises CRM data for a manager each morning
• A document summariser embedded in the portal's left menu - upload a PDF, receive a plain-text extract
• A customer form with a price calculator

What Vibecode cannot do in the cloud:

For tasks that require core-level changes, migrating to self-hosted Bitrix24 is the path to consider. Standard automation needs - robots, triggers, workflow rules - are still handled by Bitrix24's built-in tools, not Vibecode.

Step 0: Access Requirements Before You Start

To use Vibecode you need a Bitrix24 account on any Vibe+ plan; a free 15-day Vibe+ demo can be activated if you want to test before committing, and new accounts receive a 10-credit welcome bonus.

Since 1 September 2026, every Bitrix24 plan comes in two versions: Essentials and Vibe+. Vibecode, unlimited REST API, unlimited Market apps, extended AI, and the MCP server are all included in Vibe+. Details are on the official pricing page and the helpdesk article from 14 September 2026.

Self-hosted Bitrix24 can also be connected to the platform - the official quickstart asks you to connect it first.

Vibe credits: 1 credit = $1. Credits are charged only for Black Hole server runtime (24 to 202 credits per month while running, depending on server size; roughly ten times cheaper in sleep mode), paid AI models, and AI web search (from 0.02 credits per request). Building apps through the agent, API calls to Bitrix24, and the free built-in models are not charged. If credits reach zero, servers stop but apps are saved; after 33 days at zero balance servers are deleted.

The AI coding tools themselves - Claude Code, Codex, Cursor, and Antigravity - have their own separate subscriptions.

Step 1: Create Your API Key

Creating an API key takes about 30 seconds: sign in at vibecode.bitrix24.com with your Bitrix24 account, go to Access > API Keys, click Create Key, choose permissions and expiry, then copy the key - it is shown only once.

Two key types are available:

For a first experiment, a personal key is enough.

When creating the key:

1. Set the access mode - "Read only" or "Read and write." A read-only key cannot create or modify data, which is intentional for analytics dashboards.
2. In the Permissions block, tick only the sections the app needs. A CRM dashboard needs CRM access; it does not need Tasks, Chat, or Drive.
3. Set an expiry (30 to 365 days, or none).
4. Click Create, then copy the key immediately - the full value is displayed once.

After creation, Vibecode shows the key and a ready-made prompt for your AI agent. The prompt contains the key, a link to the docs, and basic instructions for creating an app or bot.

Security principle: give each app its own key with the minimum permissions it needs. If a key is compromised, revoke it in one click from the API Keys section - revocation is immediate. As noted in the official Vibecode trust page, every change is logged and client data stays in your Bitrix24 account.

Step 2: Write the Task for the AI Agent

A well-written task prompt acts as a mini-spec: state what the app does, where it appears, and which data it reads or writes - weak prompts cause the agent to fill gaps with its own assumptions and produce output that misses the mark.

Vibecode works with Claude Code, Codex, Cursor, and Antigravity. The MCP package @bitrix24/mcp-vibecode-api (50+ tools, stdio or HTTP mode) provides configs for Claude Code, Claude Desktop, Cursor and Codex CLI. Tasks can be described in English and other languages.

Task prompt structure

Weak prompt: "Build an app for CRM."

Strong prompt: "Create a widget in the Bitrix24 deal card that shows the three most recent tasks linked to that deal, with their statuses, sorted by date. Use API key [paste key]. Embed it in the deal card placement."

A useful technique: describe the task in free form, then ask the agent to reformulate it as a spec and confirm it with you before starting to code. This typically cuts the number of back-and-forth iterations.

If the agent misunderstands something, do not start over. Correct in the same chat session: "sort tasks by date descending," "add a refresh button." The agent retains context within the session.

The Superpowers skill

Before starting any Vibecode project, install the Superpowers skill in the agent. It contains two key modules: test-driven development (the agent writes tests before implementation) and a systematic debug module (the agent knows where to look for logs before changing code). Based on practice, agents without Superpowers produce more "visually plausible but broken" output. The skill is installed via a link command in the chat session.

Step 3: Generate, Preview, and Iterate

After you submit the prompt, the agent writes the code, creates a Black Hole server, and deploys the app in one to two minutes - then you open the result in the portal, describe any issues in plain text, and the agent revises and redeploys without you touching any code.

The flow from prompt to working app: the user describes the task, the AI agent writes the code and deploys it to a Black Hole server, and the server communicates with the Bitrix24 portal via REST API, appearing as a widget or bot inside the interface.

Black Hole servers are cloud servers invisible from the public internet. Apps are reachable only via https://app-{id}.vibecode.bitrix24.com. Servers sleep after inactivity (default 60 minutes; configurable to 15, 30, 60, or 240 minutes, or off). Billing is per minute; a sleeping server costs about ten times less than an active one.

The edit-deploy cycle typically takes a few minutes. Each iteration: describe what you see, describe what you expect, let the agent read the server logs and fix the code.

Multiple apps belonging to the same portal can share a single server.

Step 4: Install the App into Your Bitrix24 Account

A deployed app is immediately accessible to you through the placement or bot interface; to share it with the team or embed it inside Bitrix24, the app needs a vibe_app_ authorization key - no additional steps are needed for personal use.

Three scenarios:

1. For yourself only - the app is available as soon as it deploys. No additional installation needed.
2. For the whole portal - create the app with a vibe_app_ authorization key, which is meant for team use and embedding inside Bitrix24.
3. Marketplace publishing - not yet available. According to the official FAQ, this feature will be added in the future.

A partner can help define the task, build the app in Vibecode, test the scenario, and deliver a ready-to-use tool. ACP Group, a Bitrix24 Gold partner, offers this as a service - see how a Gold partner engagement works for context on when outside help makes sense.

Debugging Without Touching Code

The correct debugging approach is to open the app as an end user, take a screenshot of what you see, tell the agent "I see X, I expected Y," and let it read the server logs and fix the issue - editing code manually breaks the agent's context and wastes time.

Three real examples of bugs fixed entirely through chat:

The agent reads Black Hole server logs automatically. You do not need SSH access or log files. The key principle: errors are normal; trying to fix them manually is not the right response. Describe the problem precisely and give the agent the means to diagnose it.

For deployment-specific issues: if a build stalls after a tunnel interruption, do not restart immediately - the original build may still be running on the VM, and a second launch will return an EXEC_BUSY error (one operation per server at a time). For heavy CRM queries inside bot event handlers, offload the work to a background task and reply immediately with a "report is being prepared" message to avoid blocking the event queue.

Common Mistakes and Honest Platform Limits

The most frequent first-session mistakes are: a task description that is too vague, giving the key more permissions than the app needs, expecting Vibecode to modify core CRM forms, and leaving a server running after testing when sleep mode would reduce costs significantly.

Detailed breakdown:

• Too vague a task. "Automate the sales department" gives the agent nothing to act on. Start with one concrete action: read three tasks, send one message, generate one summary.
• Excess key permissions. Granting full access for a test project is a security risk and makes it harder to reason about what the app can do. Scope the key tightly.
• Expecting core changes. "Modify the standard deal form" is outside what cloud Vibecode can do. Core-level changes require a self-hosted installation - see what becomes possible with self-hosted Bitrix24.
• Ignoring REST API rate limits. Both the Vibecode platform and the Bitrix24 account limit how many requests an app can send per second - batch and cache requests, and ask the agent to read the server logs if the app slows down.
• Leaving servers awake after testing. An active server is billed per minute. Put it to sleep after testing sessions.
• Changing AI models mid-project. Switching models between sessions can cause inconsistency in how the agent interprets prior context. Start new tasks as separate sessions with the same model.

Platform limits to know:

The Vibecode API is a layer over Bitrix24 REST. It covers 1,400+ methods and 33 bot platform endpoints (as of October 2026, per the official home page), but not every REST method is exposed. For non-standard scenarios, a direct REST call can sometimes be faster. UIKit and Tailwind are not yet built into the platform's agent instructions - if you need them, specify them explicitly in the task. Hallucinations do not disappear with Superpowers, they become less frequent.

For AI-related data handling, see where Bitrix24 AI processes your data for compliance context, and Bitrix24 CoPilot for how the built-in AI assistant differs from Vibecode's coding agents.

Pre-Launch Checklist Before Colleagues Use the App

Before making a Vibecode app available to the team, verify that the API key scope matches actual app behaviour, the server sleep schedule is configured, at least one colleague has tested the full user journey, and the portal administrator knows which key the app uses.

• API key has only the permissions the app actively uses (verify in Access > API Keys > usage log)
• Key expiry is set and noted in a shared record (30-365 days)
• Access mode is Read Only if the app never writes data
• Server sleep timeout is configured (15, 30, or 60 minutes based on expected usage pattern)
• App has been tested by at least one user who was not involved in building it
• Any "client not found" or formatting issues have been reproduced and fixed
• A portal administrator knows the app exists and which key it uses
• A plan exists for what happens when the key expires (create new key, update in agent prompt)
• If the app processes sensitive data: confirmed that data is not cached on the Black Hole server beyond the response cycle
• For team apps: tested with a vibe_app_ (OAuth) key, not a personal vibe_api_ key

For broader automation needs that go beyond what a single Vibecode app covers, Bitrix24's built-in business process automation tools handle standard robots, triggers, and workflow sequences without requiring any development.