Moving an app to your own server

How to move an app from the Vibecode dashboard to your own server: what to change in the code, how to switch the address, what changes after the move and how to move back.

When to move

Move the app when its code has to run on your server instead of a Vibecode server. Only the address the app opens at changes. Everything else stays with the platform:

the app card in the Applications section, the authorization key and access to the app,
Bitrix24 placements and catalog cards — they start leading to the new address,
the Vibecode API: the app calls /v1/* exactly as before.

Catalog cards of a moved app get the “Outside the platform” and “Server security not verified” marks: the platform does not check an external server.

Moving may be turned off for your Bitrix24 account. In that case the dashboard has no “External server” tab, and a move request is refused with EXTERNAL_URL_DISABLED. Moving back to Vibecode does not depend on this setting.

Before the move: the source code

Take the code off the Vibecode server before the move. The first step of the “External server” tab shows one of two options:

A saved version exists — the “Open sources” button leads to the App sources section; download the latest version there. How the storage works: Source code storage.
No saved version — copy the prompt for an AI agent. It starts with downloading the code from the Vibecode server and then describes the changes from the next section.

What to change in the code

On a Vibecode server, the Gateway signs the user in: it adds the X-Vibe-Authorization header with a session token to the request. Outside the platform there is no Gateway, so the app signs the user in itself:

The placement opens the app at your address with a one-time code parameter.
Your server exchanges the code for a session token: POST /v1/oauth/token with the body { app_key, code, redirect_uri }. app_key is the app's authorization key, and redirect_uri is exactly the address you enter during the move.
The vibe_session_* token stays on the server and never reaches the browser.
The app reads user data via GET /v1/me with the Authorization: Bearer header and that token.
The app page must allow embedding in a Bitrix24 frame: you set the X-Frame-Options and CSP frame-ancestors headers yourself.

The exchange format, the response and the second way to get a session: Self-hosted app.

Put the app's authorization key into your server's environment. The platform does not store the raw key: if you do not have it, click “Re-issue key” on the app card — the new key is shown once. The old key stops working immediately, and the app has to be re-authorized in your Bitrix24 account.

How to move

The app owner or a Bitrix24 account administrator can move the app.

Open the Applications section and the app card.
In the “Server” row, click “Replace”.
Open the “External server” tab. The “My Vibecode server” and “New Vibecode server” tabs next to it switch the server within the platform.
Go through the tab's steps: “1. Code”, “2. What to change in the code”, “3. Address”, “4. What changes”.
In the address field, enter the app's address on your server. The address starts with https:// and contains no user name or password, and its domain has an A record with an IPv4 address. All of the domain's addresses in DNS are public, not in a private network. An address on a Vibecode server does not qualify: a Black Hole subdomain of any Bitrix24 account, a Vibecode named address, or a verified custom domain of a server in your Bitrix24 account.
Click “Move”.

The “Enter your own address” button in the catalog publishing wizard changes only the app address and does not unlink the Vibecode server. Only the “External server” tab unlinks the server.

What changes

Menu items, placements and catalog cards lead to the new address and get the “Outside the platform” mark.
The Vibecode server is unlinked from the app but is neither deleted nor stopped. It is billed while it runs. Delete it in the Black Hole Servers section once the code has moved and runs at the new address.
The “Server” row on the card shows “External server” and the address, with the “Move back to Vibecode” button next to it.
Access configured on the server moves to the app card:
- whole-account access and owner-only access stay as they were,
- the list of people carries over for those who could be matched to Vibecode accounts. Only the first 200 people on the list are matched. People who could not be matched, including people beyond 200 and people from another Bitrix24 account, lose access — the dashboard shows how many (the ACCESS_USERS_NOT_MOVED warning); grant them access again,
- departments carry over when the server grants access by department or by a list of people. Department permissions that were on the card but are not on the server are removed from the card. A department that the server opened together with its subdepartments is open on the card to its own members only: members of subdepartments lose access. Departments beyond 200, entries with an invalid department number, and departments of a server that is not tied to the app's Bitrix24 account do not carry over. In these cases the dashboard shows the ACCESS_DEPARTMENTS_NOT_MOVED warning — check the department list and grant the missing access again,
- if the app's previous server had been deleted, only the owner has access after the move. When access on the card was wider before the move, the dashboard shows the ACCESS_CARD_AXIS_RESET warning.

The dashboard shows the access warnings right after the move. They are not refusals: the app has already moved. How to set access up again: Access policy.

How to move back to Vibecode

Open the Applications section and the app card.
Click “Move back to Vibecode”.
Pick a server on the “My Vibecode server” tab or create one on the “New Vibecode server” tab.
Click “Move back” in the dialog.

The app address leads to the Vibecode server again, and your own address is no longer used. Deploy the code to a new server yourself: moving back changes the link, not the code and data. Moving back works even when moving to your own server is turned off for the Bitrix24 account.

If the key in the chosen Vibecode server's environment is no longer valid, the dashboard warns you. This happens when the authorization key was re-issued while the app ran on your server, and also when the key is disabled or expired, or the app it belongs to was deleted. Re-issue the authorization key and add the key shown to the server's environment manually.

Limitations

You can change the placements of a moved app while moving to your own server is turned on for the Bitrix24 account. When it is turned off, a placement change is refused with 400 APPLICATION_NO_SERVER — you can change the set of placements after moving back to Vibecode.
You cannot create a new server from the card of a moved app — such a request is refused with APPLICATION_HOSTED_EXTERNALLY. The way back to a Vibecode server is “Move back to Vibecode”.
The app catalog in the messenger shows the card of the previous Vibecode server, and it leads to that server's address, not to the new one.

Refusal codes

HTTP	Code	Meaning and what to do
HTTP403	Code`EXTERNAL_URL_DISABLED`	Meaning and what to doMoving to your own server is turned off for the Bitrix24 account. Moving back to Vibecode is available.
HTTP403	Code`FORBIDDEN`	Meaning and what to doOnly the app owner or a Bitrix24 account administrator can move the app.
HTTP409	Code`APPLICATION_NO_AUTH_KEY`	Meaning and what to doThe app has no authorization key — issue one and try again.
HTTP400	Code`APP_URL_UNSAFE`	Meaning and what to doThe address does not start with `https://`, contains a user name or password, its domain has no A record with an IPv4 address, or one of the domain's addresses is in a private network. A domain with only IPv6 addresses fails the check. Enter a public address.
HTTP400	Code`APP_URL_NOT_EXTERNAL`	Meaning and what to doThe address points to a Vibecode server: a Black Hole subdomain of any Bitrix24 account, or a verified custom domain of a server that is linked to the app or belongs to the app's Bitrix24 account. Enter your server's address.
HTTP422	Code`APP_HOST_NOT_ALLOWED_HERE`	Meaning and what to doThe address is a Vibecode named address (`<name>.<domain>`), not an `app-…` address. A named address points to a Vibecode server — enter your server's address.
HTTP409	Code`APP_URL_CONFLICT`	Meaning and what to doThe app address changed at the same time. Reload the page and try again.
HTTP409	Code`APPLICATION_OP_IN_PROGRESS`	Meaning and what to doAnother operation is running on the app or its server. Try again in a minute.

The ACCESS_USERS_NOT_MOVED, ACCESS_DEPARTMENTS_NOT_MOVED and ACCESS_CARD_AXIS_RESET warnings are not refusals; they are described under “What changes”. All other codes: Error codes.