# 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](/docs/source-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:

1. The placement opens the app at your address with a one-time `code` parameter.
2. 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.
3. The `vibe_session_*` token stays on the server and never reaches the browser.
4. The app reads user data via `GET /v1/me` with the `Authorization: Bearer` header and that token.
5. 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](/docs/infra/app-runtime#self-hosted-app-not-black-hole).

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 on your Bitrix24 account.

## How to move

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

1. Open the Applications section and the app card.
2. In the “Server” row, click “Replace”.
3. Open the “External server” tab. The “My Vibecode server” and “New Vibecode server” tabs next to it switch the server within the platform.
4. Go through the tab's steps: “1. Code”, “2. What to change in the code”, “3. Address”, “4. What changes”.
5. 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 resolves in DNS to a public address, not to a private network. An address on a Vibecode server does not qualify.
6. 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. People who could not be matched, including people from another Bitrix24 account, lose access — the dashboard shows how many (the `ACCESS_USERS_NOT_MOVED` warning); grant them access again,
  - department access does not carry over (`ACCESS_DEPARTMENTS_NOT_MOVED`) — set it up again,
  - if the app's previous server had been deleted, only the owner has access after the move (`ACCESS_CARD_AXIS_RESET`).

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](/docs/infra/access/access-policy).

## How to move back to Vibecode

1. Open the Applications section and the app card.
2. Click “Move back to Vibecode”.
3. Pick a server on the “My Vibecode server” tab or create one on the “New Vibecode server” tab.
4. 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 authorization key was re-issued while the app ran on your server, the dashboard warns that the key in the Vibecode server's environment is no longer valid. Re-issue the authorization key and add the key shown to the server's environment manually.

## Limitations

- Placements of a moved app do not change: 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 |
|------|------|------------------------|
| 403 | `EXTERNAL_URL_DISABLED` | Moving to your own server is turned off for the Bitrix24 account. Moving back to Vibecode is available. |
| 403 | `FORBIDDEN` | Only the app owner or a Bitrix24 account administrator can move the app. |
| 409 | `APPLICATION_NO_AUTH_KEY` | The app has no authorization key — issue one and try again. |
| 400 | `APP_URL_UNSAFE` | The address does not start with `https://`, contains a user name or password, or its domain does not resolve in DNS or resolves to a private network. Enter a public address. |
| 400 | `APP_URL_NOT_EXTERNAL` | The address points to a Vibecode server: a Black Hole subdomain or a verified domain of the server being unlinked. Enter your server's address. |
| 409 | `APP_URL_CONFLICT` | The app address changed at the same time. Reload the page and try again. |
| 409 | `APPLICATION_OP_IN_PROGRESS` | Another 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](/docs/errors).

## See also

- [Authorization in a Black Hole app](./app-runtime.md)
- [Source code storage](/docs/source-storage)
- [Access policy](/docs/infra/access/access-policy)
- [Error codes](/docs/errors)