Full application deploy

POST /v1/infra/servers/:id/deploy

A full deploy cycle in a single request: install the runtime → stop the previous service → download the archive → extract → install dependencies → write .env → run preStart commands → create the systemd unit → start → health check. Use it instead of chaining /upload + /exec — it is faster. If the runtime step fails, the deploy does not issue the stop command, clean or replace the application tree, or read or rewrite .env. The runtime installer runs as root and can change the host's system dependencies, so the previous application is not guaranteed to keep running. After a successful runtime, later failures retain the existing behavior: there is no new rollback, the unit may remain stopped, and the application tree may already have been replaced. By default the response is JSON (recommended for AI agents): the platform answers 200 before the first deploy step and writes the body once all the steps are done — the connection stays open all that time. A sleeping machine is woken up first, and until that wake finishes the client gets neither the status nor the headers, so the HTTP-client timeout has to cover both the wake and the deploy itself. For line-by-line progress, pass ?stream=true — the server returns an SSE stream (Server-Sent Events) with an event on each step.

For AI agents and MCP clients, always use JSON mode (without ?stream=true). The official Vibecode MCP client (the manage_server_deploy tool) strips this parameter automatically and always works in JSON mode.

Deploy and application access to the Bitrix24 account

The key used to call POST /v1/infra/servers/:id/deploy is not automatically copied into the application environment. A successful deploy and health check do not verify the application's access to Bitrix24 account data.

On a successful deploy with an OAuth app key, the response adds one warning about this boundary: in warnings of the JSON response for a dedicated virtual machine and a Galaxy application, or in warnings of the SSE done event. This is a reminder to configure authentication, not a runtime credential check: it appears regardless of the supplied env, preserveEnv, or chosen runtime, including static. Deploy success and existing warnings are preserved. This warning is not added for a personal key or a failed deploy.

To act as the visitor, supply the application with the key of the same OAuth application that issued the user session. The application server reads the incoming X-Vibe-Authorization and forwards its value as Authorization in the outgoing /v1/* request, together with the application key in X-Api-Key. For a headless service, explicitly supply a personal key through env, restrict it to the minimum required scopes, and keep server access at OWNER_ONLY. See Application contract for both flows.

If your code reads BITRIX_API_KEY and BITRIX_API_BASE_URL, these are client-chosen variable names. The platform does not create them automatically: supply the required values explicitly and configure the application to read them. The absence of these names in env alone does not prove that the application has no credentials.

Galaxy application — deploy right after creation

If the server is a Galaxy application (the createdVia field equals galaxy in the response of POST /v1/infra/servers), run the deploy right after creation, without waiting for blackholeStatus: "CONNECTED" — the container is built by the deploy itself. The placement model, lifecycle, and pricing are on the Galaxy application page.

Differences in the deploy for a Galaxy application:

• runtime is required. start is required for every runtime except static; for static it is optional and ignored. Without runtime the request returns 400 GALAXY_DEPLOY_RUNTIME_REQUIRED.
• The source is the inline source.content (a base64 archive). The source.url and source.versionId variants are available where the platform has enabled link deploys for you; otherwise they are rejected with 400 GALAXY_DEPLOY_CONTENT_ONLY. Prefer a link when you have one: the host downloads the archive itself, so nothing large travels in the request body and the inline size limit does not apply. The link must point at source storage — a saved version and its signed link both qualify, while an outside address is rejected with 400 GALAXY_SOURCE_URL_NOT_ALLOWED. A separate virtual machine has no such restriction.
• A Dockerfile in the archive is not required — the platform generates it itself from runtime and port, and for non-static runtimes from start. Static always gets the platform nginx command. If you put your own Dockerfile in the archive, it is ignored (the platform always generates its own). See "Known specifics" below.
• The container working directory is /opt/app (the same as extractTo on a regular virtual machine): the code is copied there, so both a relative command (start: "node server.js") and an absolute path (start: "node /opt/app/server.js") work. The /app path also points to /opt/app — it is a symlink kept for backward compatibility. That is, the same start works for both VM and galaxy deploys.
• The deploy is addressed by the application's own id (kind equals GALAXY_APP). The same request with the id of the host machine (kind equals GALAXY) is refused — 400 GALAXY_HOST_NOT_A_DEPLOY_TARGET.
• Dedicated virtual machine fields do not apply to a Galaxy application: preStart, systemd, serviceName, cleanDeploy, extractTo, hardening, preserveEnv, dataDirs, dataDirsRecursive. A request carrying them goes through, but the values have no effect. Put the commands that must run before the application starts into install — it runs while the container is built. The healthPath field does apply and sets the readiness probe path inside the container. The extractTo and dataDirs paths are still validated: an unacceptable value returns 400 INVALID_EXTRACT_TO or 400 INVALID_DATA_DIRS, and the same code comes back for dataDirsRecursive without dataDirs.

The Galaxy application lifecycle is on the Galaxy application page. The "deploy in a single request on creation" scenario is on the Create server page.

Parameters

Request fields (body — JSON)

Request fields (body — multipart/form-data)

An alternative to JSON — upload the archive without base64. Useful from bash/PowerShell scripts.

Deploy steps

Steps run sequentially. If one fails, the deploy stops.

Examples

Examples with an external source.url include the X-Skip-Source-Snapshot header: with source storage enabled, a deploy from a third-party address without it returns 409 SNAPSHOT_REQUIRED. Details and the alternative via storage are in the "Known specifics" section.

curl — personal key

# JSON, Node.js with migrations
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Skip-Source-Snapshot: deploy from external URL" \
  -d '{
    "source": { "url": "https://github.com/user/app/archive/main.tar.gz" },
    "runtime": "node20",
    "install": "cd /opt/app && npm install --production",
    "preStart": "cd /opt/app && npx prisma migrate deploy",
    "start": "cd /opt/app && node server.js",
    "port": 3000,
    "env": { "NODE_ENV": "production", "DATABASE_URL": "postgresql://localhost/mydb" }
  }'

# Multipart — local archive
tar -czf app.tar.gz -C ./my-app .
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@app.tar.gz" \
  -F "runtime=node20" \
  -F "install=cd /opt/app && npm install --production" \
  -F "start=cd /opt/app && node server.js" \
  -F "port=3000"

curl — inline archive (minimal set of fields)

# Canonical inline deploy: source.content + start is enough.
# The archive type is detected automatically from the signature of the first bytes —
# tar.gz, zip, and tar.bz2 are supported, no separate format field is needed.
B64=$(base64 < app.tar.gz | tr -d '\n')
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"source\": { \"content\": \"$B64\" },
    \"start\": \"cd /opt/app && node server.js\",
    \"port\": 3000
  }"

Only two fields are required: source (one of content / url / versionId) and start. The archive can be wrapped as zip (zip -r app.zip .) or tar.gz (tar -czf app.tar.gz -C ./my-app .) — the platform recognizes both from their content.

curl — arbitrary stack without a runtime

# Deploy without runtime — any software is installed via preStart
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Skip-Source-Snapshot: deploy from external URL" \
  -d '{
    "source": { "url": "https://example.com/my-app.tar.gz" },
    "preStart": "apt-get update -qq && apt-get install -y ffmpeg imagemagick",
    "install": "cd /opt/app && npm install --production",
    "start": "cd /opt/app && node server.js",
    "port": 3000
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Skip-Source-Snapshot: deploy from external URL" \
  -d '{
    "source": { "url": "https://github.com/user/fastapi/archive/main.tar.gz" },
    "runtime": "python311",
    "install": "cd /opt/app && pip install -r requirements.txt",
    "start": "cd /opt/app && python3.11 -m uvicorn main:app --host 0.0.0.0 --port 3000",
    "port": 3000
  }'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/deploy`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
      'X-Skip-Source-Snapshot': 'deploy from external URL',
    },
    body: JSON.stringify({
      source: { url: 'https://github.com/user/app/archive/main.tar.gz' },
      runtime: 'node20',
      install: 'cd /opt/app && npm install --production',
      start: 'cd /opt/app && node server.js',
      port: 3000,
    }),
  }
)
const body = await res.json()
if (body.success) {
  console.log(`Application is live: ${body.data.appUrl}`)
} else {
  console.error(`Failed at step ${body.error.step}: ${body.error.message}`)
}

JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/deploy`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
      'X-Skip-Source-Snapshot': 'deploy from external URL',
    },
    body: JSON.stringify({
      source: { url: 'https://github.com/user/app/archive/main.tar.gz' },
      runtime: 'node20',
      install: 'cd /opt/app && npm install --production',
      start: 'cd /opt/app && node server.js',
      port: 3000,
    }),
  }
)

Response fields

Response headers

On a dedicated virtual machine (kind: "STANDALONE"), the deploy opens the operation record BEFORE the pipeline. On an already available machine the id reaches the client before the work starts. On a sleeping machine the record is already visible in the server operation list, but the blocking wake completes before the HTTP status, headers, or an SSE frame can reach this connection:

X-Vibe-Operation-Id: clz9k2m4x0001qw8h3f7d2n5p

The same id is mirrored in the body (data.operationId on success, error.operationId on failure), and with ?stream=true it also arrives as the first frame before the first event: step — after any blocking wake has completed:

event: operation
data: {"operationId":"clz9k2m4x0001qw8h3f7d2n5p"}

The frame exists because a browser EventSource does not expose response headers at all.

For a Galaxy application (kind: "GALAXY_APP"), the record is opened after the application mutex is acquired, on entry to the first step. Its id arrives in the header and terminal JSON body; this branch has no early SSE frame. If the connection dropped earlier, find the run through GET /v1/infra/servers/:id/operations.

A missing header does NOT mean the deploy never started. A sleeping standalone connection may have dropped during the wake, a galaxy connection may have dropped before the terminal response, or the platform may have failed to create a record and continued without an id. Do not redeploy on that basis — a second run would land on top of an application that may already be up. First read the recent server operations, state, and logs; for an addressable outcome see Deploy outcome.

Headers arrive before the pipeline, after any blocking wake; the body arrives at the end. In JSON mode on a dedicated virtual machine (kind: "STANDALONE") the platform sends 200 and the response headers before the first step and writes the response body once the deploy has finished: the connection is held open with spaces all that time. If the machine was asleep, the deploy creates an operation first and then wakes it; until that wake finishes — up to 6.5 minutes — the client gets neither the status, nor the headers, nor the id itself over this connection. While the request is silent, the operation is already visible as running, with no deploy steps, through GET /v1/infra/servers/:id/operations. If wake returns a refusal and the operation record was created, the response carries the same id in X-Vibe-Operation-Id and error.operationId; 503 WAKE_TIMEOUT remains 503, and after a successful asynchronous write the operation code is WAKE_TIMEOUT. The operation can briefly remain running just after the response; if the terminal write fails, it later reads as unknown. A client with a short timeout closes the connection earlier and sees a 200 whose body is empty or does not parse as JSON, and a drop during the wake leaves it with no response at all. The deploy keeps running on the server either way, and it must not be re-sent. How long the platform holds the connection and which timeout to set — "A long deploy and HTTP-client timeouts" under "Known specifics". Step-by-step progress instead of waiting is what ?stream=true gives, and the outcome of an interrupted deploy is read by its operation id — Deploy outcome.

For a Galaxy application (kind: "GALAXY_APP") the whole response — headers and body alike — arrives once the build has finished, so the same timeout margin is required and there is no "work in progress" signal before the response.

On success: false the response additionally carries error.code, error.message, and error.step with the name of the failed step, and data.steps contains the timeline of steps up to the failure. If the hardened-start auto-rollback fired, the error envelope also carries error.hardeningRollback — the same value as on the hardening step. The field exists on the plain response only. With ?stream=true no envelope carrying it is sent: the outcome is read from the event: step frame with status: "error" and from the hardening step frame preceding it. An event: error frame does occur in the stream — when the operation is aborted and when the server is busy with another operation — but it never carries hardeningRollback. An absent field means "no rollback was attempted", NOT "isolation was never applied" — the latter is answered by the service_user step (ok — applied, warning — not applied, and no such step at all means the deploy never got that far). On a dedicated virtual machine (kind: "STANDALONE") such a response arrives with HTTP status 200 — the connection is held from the start of the deploy, so a failed step is visible in the success field, not in the status. For a Galaxy application (kind: "GALAXY_APP") the same error arrives with the status 502.

A Galaxy application's response shape differs. For a Galaxy application (kind: "GALAXY_APP") a successful response carries data of the form { "id", "status", "appUrl", "buildLog", "steps", "autoSaved", "skippedReason" }, plus warnings[] when displayName/description are not passed or are not applied, and when deploying with an OAuth app key (see above). The sleepAfterMinutes field is not part of this shape — it belongs to a dedicated-virtual-machine deploy response only. The autoSaved and skippedReason fields sit directly on data, not on data.source, and there is no data.source.savedVersionId field in the response — read the source auto-save outcome from data.autoSaved. Build details stay in the buildLog field.

A Galaxy application's data.steps[] array is shorter than a dedicated machine's and holds at most two steps:

"steps": [
  { "step": "build", "status": "ok" },
  { "step": "healthcheck", "status": "ok", "httpCode": 200, "healthPath": "/health" }
]

The build step with the ok status is in every successful response. The healthcheck step is added only when the platform made an HTTP request to the application: status: "ok" — the application answered with a 2xx or 3xx code, status: "warning" — it answered with a 4xx or 5xx code, and the deploy still counts as successful because the application is reachable.

Response example

A successful deploy (JSON):

{
  "success": true,
  "data": {
    "steps": [
      { "step": "runtime", "status": "ok", "duration": 45 },
      { "step": "stop_existing", "status": "ok" },
      { "step": "download", "status": "ok" },
      { "step": "install", "status": "ok", "duration": 12 },
      { "step": "env", "status": "ok" },
      { "step": "platform_env", "status": "ok" },
      { "step": "systemd", "status": "ok" },
      { "step": "start", "status": "ok" },
      { "step": "healthcheck", "status": "ok" }
    ],
    "serviceName": "app",
    "status": "running",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
    "sleepAfterMinutes": 60,
    "source": { "autoSaved": false, "skippedReason": "deploy from external URL" }
  }
}

A source.url acquisition failure retains the top-level DEPLOY_FAILED code, while stable details are duplicated in error and in the terminal step:

{
  "success": false,
  "error": {
    "code": "DEPLOY_FAILED",
    "message": "The source could not be reached within the retry budget.",
    "step": "download",
    "causeCode": "DOWNLOAD_SOURCE_UNREACHABLE",
    "retryable": true,
    "attempts": 4
  },
  "data": {
    "steps": [
      {
        "step": "download",
        "status": "error",
        "error": "The source could not be reached within the retry budget.",
        "causeCode": "DOWNLOAD_SOURCE_UNREACHABLE",
        "retryable": true,
        "attempts": 4
      }
    ]
  }
}

The data.source block is the result of source auto-save. In the examples above the deploy comes from an external URL with the X-Skip-Source-Snapshot header, so autoSaved: false and skippedReason echoes the passed reason. On a deploy from storage — source.content or source.versionId — the block looks like { "autoSaved": true, "savedVersionId": "vN", "skippedReason": null }. For the full contract and the skippedReason values, see Source storage.

The warnings field in a successful response appears only when there is something worth flagging — for example, displayName/description were not passed or were not applied (see "Known specifics"), or the runtime step ended with status warning and its messages are waiting in that step's stdout. In JSON mode it is warnings at the top level of the response, alongside data; in SSE mode it is the same field in the final event: done.

A successful deploy of a regular dedicated virtual machine that is not covered by agent/bot idle-sleep protection appends one entry starting with AUTO-SLEEP POLICY: to warnings[] when the snapshot at the start of the deploy has a numeric sleepAfterMinutes and no enabled recurring wake window. Disabled windows do not suppress it; at least one enabled window or sleepAfterMinutes: null does. This is only the display condition for the deploy warning: its absence does not mean the server cannot sleep. An enabled window can suppress the warning while the server still sleeps after its saved numeric timeout. If an older record already contains null plus an effective schedule, the platform's post-window timeout applies. Unless the server is in the SCHEDULE run mode, current writes reject setting null while windows are enabled, and reject any schedule creation or update while null is stored — even when the window is disabled. The check and the returned value refer to the same starting snapshot: a policy change during the deploy appears only in the next response. The warning is advisory and does not make the deploy fail.

During lengthy runtime preparation, the SSE stream repeats the event: step frame with status: "running" and an elapsedSeconds field. It is the number of whole seconds since the step started; the field is absent from the first frame and from every terminal ok/error frame. The plain JSON response still completes only when the operation ends and keeps the connection alive with whitespace, so use ?stream=true for meaningful intermediate progress.

SSE stream with ?stream=true:

event: step
data: {"step":"runtime","status":"running"}

event: step
data: {"step":"runtime","status":"running","elapsedSeconds":15}

event: step
data: {"step":"runtime","status":"ok","duration":45}

event: step
data: {"step":"stop_existing","status":"ok"}

event: step
data: {"step":"download","status":"ok"}

event: step
data: {"step":"install","status":"ok","duration":12}

event: step
data: {"step":"healthcheck","status":"ok"}

event: done
data: {"serviceName":"app","status":"running","appUrl":"https://app-abc12345.vibecode.bitrix24.com","sleepAfterMinutes":60,"warnings":["displayName and description were not set on this deploy — the Bitrix24 catalog card uses displayName as the title and description as the subtitle, and falls back to the server's technical identifier (slug) without them. The deploy is NOT complete until they are set: re-send the deploy with displayName and description added so the app appears in the catalog with an adequate name."]}

event: source
data: {"autoSaved":false,"skippedReason":"deploy from external URL"}

Error response example

The deploy failed at the install step (HTTP 200, success: false):

{
  "success": false,
  "error": {
    "code": "DEPLOY_FAILED",
    "message": "npm ERR! Missing dependencies",
    "step": "install"
  },
  "data": {
    "steps": [
      { "step": "stop_existing", "status": "ok" },
      { "step": "download", "status": "ok" },
      { "step": "install", "status": "error", "stderr": "npm ERR! Missing dependencies" }
    ]
  }
}

The app came up, but the health check answers with an error, and the platform has already rolled it back to administrator privileges (HTTP 200, success: false):

{
  "success": false,
  "error": {
    "code": "DEPLOY_FAILED",
    "message": "App returned HTTP 503 at /health (process is up but responding with error). …",
    "step": "healthcheck",
    "hardeningRollback": "completed"
  },
  "data": {
    "steps": [
      { "step": "service_user", "status": "ok" },
      { "step": "systemd", "status": "ok" },
      { "step": "start", "status": "ok" },
      { "step": "hardening", "status": "warning", "hardeningRollback": "completed", "stdout": "…" },
      { "step": "healthcheck", "status": "error", "httpCode": 503, "healthPath": "/health", "portOwner": "unknown", "error": "…" }
    ]
  }
}

What a program reads here without parsing any prose: httpCode: 503 — the app answers over HTTP, so the code is deployed and the process is up; hardeningRollback: "completed" — isolation was removed and the app runs with administrator privileges. The deploy is still not counted as successful: success and the step status decide that, not httpCode. portOwner: "unknown" is normal here — the port-ownership probe does not run on 5xx responses.

Errors

The HTTP status does not reflect the deploy's outcome. On a dedicated virtual machine (kind: "STANDALONE") the connection is held open for the whole deploy, and the 200 status is sent before it begins — so both a successful and a failed deploy arrive with the code 200. The failure marker is the success: false field and the error object in the response body. Check success in the body, not the HTTP status: a client that branches on the status will treat a failed deploy as successful. For a Galaxy application (kind: "GALAXY_APP") the same error arrives with the status 502.

In streaming mode (?stream=true) a step failure arrives as an SSE step event with status: "error" — it carries the name of the failed step. On an exception or a transport drop, a separate error event carries code and message. On a stuck exec mutex, the terminating error event carries code: "DEPLOY_FAILED", step, and hint, but no message. There is no success field in the stream — the failure marker for a step is status: "error" in its step event.

The full list of common API errors — Errors.

The platform passes the port in `PORT`

An application does not have to know its port number up front: the platform passes it in the PORT environment variable — the same convention Heroku, Render, Railway and Cloud Run use. The value is always the request's port field (3000 by default) — the same number the platform forwards public traffic to and runs the health check against.

So ordinary code just works:

require('http').createServer(handler).listen(process.env.PORT, '0.0.0.0')

How it is delivered:

• Dedicated virtual machine (kind: "STANDALONE") — the platform_env step writes a separate file .vibe-platform.env next to your .env, holding a single PORT line, and the systemd unit loads both files: yours first, the platform's second. Systemd applies environment files in declaration order, so for a variable set in both files the later one wins — the platform file. Your .env is neither read nor rewritten in the process.
• Galaxy application (kind: "GALAXY_APP") — PORT is passed to the container as an environment variable at start, alongside your own variables.

What to keep in mind:

• PORT is reserved by the platform. If you pass your own env.PORT that differs from the port field, the platform overrides it and says so with a line in the response warnings[] of the form: Deploy field "port" is 3000; your env.PORT was "9999" and was overridden. This is not an error — the deploy succeeds. Passing a matching value is fine — there will be no warning.
• If you kept something other than your listen port in env.PORT — a database port, an upstream service port — rename that variable. Your value used to reach the application; now PORT belongs to the platform and gets overridden, and the warnings[] entry is about exactly that case.
• An application that reads the .env file directly (instead of the process environment) will not find PORT there: the platform value lives in a separate file. Read process.env.PORT — common loaders (dotenv and friends) do not overwrite already-set environment variables by default, so such code works unchanged.
• Your own systemd unit (systemd: false). You own the unit in that mode, so the platform file is not loaded automatically — add the line EnvironmentFile=-<extractTo>/.vibe-platform.env after the line with your .env. Until you do, your env.PORT keeps winning, and the response warning says exactly that instead of "was overridden". The platform still writes the file, but if that write fails the deploy is not aborted in this mode — the platform_env step returns warning.
• Already running applications receive PORT on their next deploy — the environment of a running process is not changed retroactively.

Known specifics

• The multipart archive ceiling depends on whether the archive streamed into storage. The former 500 MB applies only when three conditions hold at once: you reach the server as its direct owner, not through another application's card and not with a management key; the server is either not a Galaxy application, or link deploys for Galaxy applications are fully enabled for you; and source storage is enabled both platform-wide and for your Bitrix24 account. If even one of them fails, streaming does not kick in, the archive is buffered in memory whole, and its ceiling becomes the same as for an inline base64 body: about 72 MB of archive, refused with 413 INLINE_SOURCE_TOO_LARGE and the same error.hint. The path that does not depend on these conditions is to save the archive as a version through POST /v1/infra/servers/:id/sources and deploy it with {"source": {"versionId": "vN"}}: there the bytes stream and run into the source-version cap instead, 500 MB of archive. For how storage works, see Source storage.

• In multipart mode the source version is created before the deploy starts. The archive is streamed into storage while the request is still being read, and the version is marked failed right away — a successful deploy switches it to success. So a failed deploy leaves a version in history with the status failed: that is not junk but an honest note saying "the bytes were accepted, the deploy did not get through". For what the history contains, see Source storage. If storage itself did not accept the archive, the deploy does not start at all and the request returns 502 SOURCE_DEPOT_UNAVAILABLE — the body is fine, a plain retry helps.

• The deploy FILLS IN the Bitrix24 catalog card's name and description — it does not rename them. displayName is written only while it still equals the server's technical identifier, description only while it is empty. Pass both on the first deploy: without them the catalog keeps the technical identifier and the response returns warnings[] with a hint. If the field is already set, the value you send is not applied — the response says so in a separate warnings[] entry and points at PATCH /v1/infra/servers/:id, the only rename endpoint. A separate entry arrives when the APPLIED value lost its non-ASCII characters on the way in (Windows PowerShell without explicit UTF-8 serialization is the usual case): the deploy itself is normal, and the value reaches the card as is. A dropped field gets no such entry — it never reached the card. A repeat deploy with the same value is silent too: nothing is written, and fixing the charset of a string already on the card goes through the rename endpoint.

• Non-ASCII characters in displayName and description from Windows PowerShell. Sent without explicit UTF-8 serialization, they reach the catalog card as question marks (?): the bytes are lost on the client side, before the request is sent. A ready-to-run call with UTF8.GetBytes — Windows / PowerShell and UTF-8.

• A non-root healthPath means the deploy also checks the root. Once the given path answers, the platform probes / — the address Bitrix24 opens. A 5xx at the root ends the deploy with an error on the healthcheck step: a light endpoint such as /api/health answers 200 even when the application page is down, and such a deploy used to report success. A 4xx does not abort the deploy — an app_root step arrives with status warning: a server with no page at the root (an API-only backend, for instance) is a working shape. A probe that never reports back is also a warning, not an error. With the default healthPath (/) no extra request is made.

• A non-root healthPath with a root appUrl produces a warnings[] entry. Bitrix24 opens the app at the linked application's appUrl, and the platform fills it with the bare subdomain origin — no path. If the app answers ONLY on the subpath, the health check is green (it probed exactly that subpath) while the Bitrix24 frame opens the root, where the app is not. The deploy response carries a warnings[] hint — act on it only if the root is genuinely not served: a probe on a subpath while the UI lives at the root (healthPath: "/health") is a normal, correct shape, and moving that path into appUrl would instead break the embed (the frame would open a JSON endpoint). If a subpath is genuinely unavoidable, fix both halves: deploy there AND move the same subpath into appUrl via PATCH /v1/apps/{id} (id from GET /v1/apps, matched on appUrl). The check runs only on POST /v1/infra/servers/:id/deploy, and only when appUrl points at THIS server's subdomain; server-creation responses do not carry it. Why the root is preferred and not merely tidier: after a user signs in, the gateway returns them to the subdomain root rather than to the subpath, so an app with a subpath in appUrl lands on its own 404 on the first visit of each session; a hash-router app additionally loses location.hash on the wake screen. This is a known gateway limitation and is being fixed separately.

• A warning status on the tunnel_routing step does not mean the deploy failed. After a successful healthcheck, the platform verifies that the Gateway tunnel routes public traffic to the right port (set_port + agent probe). If the port has not been detected yet or the agent runs in fixed-port mode, the step gets status warning (not error) and the deploy is not aborted. The application's public URL may serve the Black Hole placeholder page for about a minute while the agent's port scanner detects the listening port. The placeholder goes away on its own if the previous port was released. If a live process still answers on the previous port, the scanner deliberately keeps it and will not switch on its own — set the port explicitly via PATCH /port or stop that process. If the agent has no port auto-detection at all (agentError: NO_SCANNER in the step text), call /repair.

• The application code is passed via source.content, not via start/install/preStart. The command fields (start, install, preStart) are short shell commands with a 5000-character limit each (command in /exec is 10000). They are not meant for file contents: the base64 of a whole archive does not fit there and gets truncated. Put the code itself (tar.gz / zip, including a single file) in source.content — a base64 string of the archive, up to 96 MB per request body, which is about 72 MB of archive — or in source.url, and leave only the start command in start (for example node server.js). An archive larger than 72 MB cannot be sent inline and is refused with 413 INLINE_SOURCE_TOO_LARGE: send it as a link in source.url or as a saved version in source.versionId, both of which accept up to 500 MB of archive. On a Galaxy application both paths are available where link deploys are enabled for you — otherwise shrinking the archive is the only option left.

• Four strategies for .env. The file is written to {extractTo}/.env (by default /opt/app/.env) and with cleanDeploy: true is deleted before the next deploy:

  1. Pass env on every /deploy — it is regenerated automatically (recommended).
  2. preserveEnv: true — the platform reads .env before the clean and writes it back at the env step. If the deploy aborts after the snapshot was created and the clean began, for example on archive download or dependency install, the saved copy is put back on disk best-effort. A runtime failure happens before the snapshot and clean: the platform does not read the previous .env or upload a copy back, and the file stays in place. Useful when the variables are not at hand at redeploy time. An env passed in the same request wins: the file is written anew and the saved copy is discarded. Dedicated virtual machine only (kind: "STANDALONE").
  3. Store .env outside extractTo — for example, /var/lib/myapp/.env. That directory is not touched by cleanDeploy. Specify the explicit path in start.
  4. cleanDeploy: false — an accumulating (merge) deploy, .env survives, but stale files from previous deploys remain along with it.

  The strategies above apply to a dedicated virtual machine. A Galaxy application's env behavior is covered in a separate entry below.

• The platform writes the wake windows' timezone into .env itself. If a dedicated virtual machine (kind: "STANDALONE") has enabled scheduled wake windows and all of them declare one and the same timezone, the deploy adds to .env a TZ variable carrying that zone — the application receives it along with the other variables and uses it to compute local time. Your own TZ passed in the env field wins: the platform does not override it. With preserveEnv: true the zone is appended to the file restored at the env step when that file carried no TZ line. If the deploy aborts after the snapshot was created and the clean began, but before the env step, the saved copy is put back as it was, with no zone appended — the next successful deploy adds it. A runtime failure happens earlier: the previous file stays in place without being read or uploaded back. If the windows declare different zones, or there are no windows at all, TZ is not set. For a Galaxy application (kind: "GALAXY_APP") the zone is not injected — the container receives only the variables from the env field of that request.

• Scheduled wake brings the server up; it does not keep it running. If scheduled wake is available for your Bitrix24 account, an enabled recurring window is a good fit for work at a fixed time, when a task with no inbound activity finishes before the server's explicit numeric data.sleepAfterMinutes; the schedule does not shorten that numeric timeout. Unless the server is in the SCHEDULE run mode, current writes reject setting null while windows are enabled, and reject schedule creation or update while null is stored — even for a disabled window. If an older record still holds null together with an effective schedule, the platform's post-window fallback applies — 15 minutes by default. Inbound HTTP requests and SSH activity reset the timer; cron, background processes, and the application's outbound traffic do not. Continuous or longer work requires { "sleepAfterMinutes": null } and no enabled wake window. The absence of a deploy warning — with null, or with windows already created — does not itself promise no-sleep behavior.

• An app that itself calls the Vibecode V1 API needs its own key. If the deployed app talks to the Vibecode V1 API (/v1/deals, /v1/users, etc.), it sends its own personal vibe_api_ key in the X-Api-Key header. The platform does not issue that key automatically: the user creates it in the API Keys section (/keys; for a read-only dashboard, in READONLY mode with minimal scopes) and passes it to the app via the env parameter (for example env: { "VIBE_API_KEY": "<key>" }); the app reads process.env.VIBE_API_KEY and sends it as X-Api-Key. A 401 (MISSING_API_KEY / INVALID_API_KEY) means the app carries no valid key, not a plan problem. A personal key talks to Bitrix24 as its owner — keep the server accessPolicy at OWNER_ONLY, otherwise other users would see the key owner's data. If the app is embedded in Bitrix24 as a placement and shows per-user data, that is a different auth flow, see App authorization.

• Automatic loading of .env in systemd. The unit declares EnvironmentFile=-{extractTo}/.env (the - sign makes the file optional). The application gets the variables itself via systemd. But with systemd: false or commands from install/preStart, env is not loaded — pass it explicitly.

• If dependencies and devDependencies are mixed, npm install --production will not install packages from devDependencies. For cron scripts with tsx, ts-node, etc., drop --production or add them separately via preStart.

• A repeat deploy with the same runtime reinstalls it. Omit the runtime parameter on repeat deploys — it saves 45+ seconds. The first deploy with runtime is required to install it.

• The health check may not succeed in time. Up to 10 attempts at a 3-second interval — that is about 30 seconds in total. If the application takes longer to start, add a /health endpoint that responds 200 immediately, even before warm-up, or move the long initialization into preStart.

• The start command stays in the foreground and holds the listener itself. On a dedicated virtual machine the platform runs it as a systemd unit of type simple: the unit counts as alive exactly as long as the process it launched has not exited. A command that hands the work to a background daemon and exits does not hold the unit — once it exits, the service moves to inactive and systemd stops whatever processes it left behind. The listener disappears along with them. Write a command that never returns control: node server.js, python3 app.py, nginx -g 'daemon off;'. A process manager inside start (pm2 start server.js --name app && pm2 save, and any other form that launches and then exits) does not work under this scheme, even when the runtime installed that manager for you.

  Such a command has two outcomes, both from the same cause. First, the health check finds no listener and the deploy fails with attempt 10/10: curl exit=7. Second, the check reaches the app while the background process is still alive, so the deploy finishes successfully and the app stops answering a few seconds later: the deploy response is green and there is no application on the port any more. What tells the two outcomes apart is the deploy result itself: a red deploy carrying attempt 10/10: curl exit=7 is the first one, a green deploy whose app goes silent a few seconds later is the second. The portOwner field of the healthcheck step does NOT separate them — unknown arrives in both: in the first the port-ownership probe never ran at all (there was no status code in the 200–399 range), in the second it did run and could not name your unit as the owner. service arrives only for a command that holds the port itself, so unknown on a green deploy confirms that the port is held by a leftover background process rather than by the unit.

• A successful deploy means the application answered a GET. The healthcheck and app_root steps request healthPath and the root with the GET method. The deploy does not check whether POST, PATCH and DELETE routes are ready: an application that answers them with an error still passes the deploy green. Check such routes with your own call after the deploy.

• Background applications must also listen on port 3000. The healthcheck step runs on every deploy — even if the application does not serve HTTP traffic (a bot that only polls events, a cron daemon, a queue worker). Without a process listening on port 3000, the step retries and finishes with the error attempt 10/10: curl exit=7 (failed to connect). Alongside the main logic, bring up a minimal HTTP server that responds with code 200 to GET /:

  Node.js:

  javascript Copy

  require('http').createServer((_req, res) => res.end('ok')).listen(3000)
  // then — the application's main logic

  Python:

  Python Copy

  import http.server, threading
  
  class Health(http.server.BaseHTTPRequestHandler):
      def do_GET(self):
          self.send_response(200)
          self.end_headers()
          self.wfile.write(b'ok')
      def log_message(self, *args):
          pass
  
  threading.Thread(
      target=lambda: http.server.HTTPServer(('', 3000), Health).serve_forever(),
      daemon=True,
  ).start()
  # then — the application's main logic

• A 15-minute lock. A single /deploy blocks /exec and other /deploy calls. If the previous /deploy failed at the healthcheck step or the client dropped the connection on timeout, subsequent /exec and /deploy calls return 409 EXEC_BUSY until the lock expires automatically — that is, up to 15 minutes from the start of the interrupted deploy. The 409 EXEC_BUSY response carries a Retry-After header and retryable: true / retryAfter (seconds) fields — this is a short poll interval, so keep retrying with it; the full upper bound until the lock clears is in error.hint.autoExpiresInSeconds. What comes next depends on the KIND of the stuck lock. A leaked exec mutex is cured by the guarded POST /v1/infra/servers/:id/unstick: a holder record with op: exec that outlived its TTL is released without force. The server lock of an interrupted DEPLOY is not that — a legitimate deploy outlives its TTL, so there /unstick without force answers 409 while the lock is observed and the wait stands. ⚠️ Both calls require an independently confirmed idle server — its state and its logs: the tunnel bounce kills whatever the agent is running. The unconditional DELETE /v1/infra/servers/:id/lock cuts the wait only on the replica that HOLDS the lock — the broadcast deliberately spares a live foreign deploy — and it stays the last step, allowed only once the server is independently confirmed idle. There is no need to recreate the server.

• A long deploy and HTTP-client timeouts. A full cycle — especially with a runtime install and a large npm install / pip install — really takes several minutes. In JSON mode the server holds the connection, sending HTTP 200 + chunked spaces every 15 s until it is ready (so Content-Length is absent and the response looks "hung"). The spaces go inside the already-opened JSON object, so the body looks like JSON ({) from its very first byte. The platform window is 660 seconds: the connection is not held longer than that. Set the HTTP-client timeout to at least 690 seconds — strictly above the platform window, because a timeout equal to it races the platform itself and the response can be lost. If the client drops the connection earlier (for example, curl --max-time 120, or an SDK default, which in some clients is 300 seconds), the request still keeps running on the server. Symptoms of such a drop: the client got 200 and the headers while the body is empty or does not parse as JSON — the response broke off on the keep-open spaces. A drop during the wake looks different: there is no response at all, because the status and the headers reach the client only after the machine is up. The operation itself is already visible through GET /v1/infra/servers/:id/operations: find the run there, then use its id to read the addressable Deploy outcome. If wake returned a refusal, its HTTP response carries the id in X-Vibe-Operation-Id and error.operationId; after a fail-open insert there may be no id, and that does not prove that the run never started. Subsequent /exec and /deploy calls return 409 EXEC_BUSY until the server-side part finishes or the 15-minute lock expires. What to do: (a) in curl — --max-time 690 or higher, (b) in any SDK — set the request timeout to ≥ 690 s for this endpoint, (c) or use ?stream=true (SSE) — in that mode events arrive line by line as the steps progress, and proxy and SDK timeouts behave more reliably. A backend lock left behind by such a drop is not something POST /v1/infra/servers/:id/unstick can take away: it is guarded, answers 409 on its own while the lock is observed, and clears one by itself only when that lock is an exec mutex past its own TTL. What remains is to wait the 15 minutes out or move to the unconditional DELETE /lock — it stays the last step and only once the server is independently confirmed idle. Do not re-send the deploy before reading that outcome: a second run would land on top of an application that may already be up. A sleeping server adds up to 6.5 minutes to that window: the spaces start only after the wake, so the first deploy after sleep meets up to 6.5 minutes of silence before the platform's 660-second window even begins. Set the timeout with that margin, or wake the machine in advance with /wake and wait=true.

• apt-get in preStart works without sudo. The agent and the deploy commands run as root — there is no need to write sudo and it will not cause an error.

• The app itself runs under an unprivileged account. Deploy commands (install, preStart) and /exec run as root, but the application process that systemd starts runs as the dedicated vibeapp user. It owns the deploy directory (extractTo, /opt/app by default) and $HOME points there, so writing inside its own directory, npm/pip caches and data files all work unchanged. What stops working: writing outside its own directory unless that directory is declared in dataDirs (see the next item), connecting to a database reachable only through a root-owned socket (MySQL with auth_socket), and running docker from the start command. Ports below 1024 do work — the platform grants a separate permission for them.

• A state directory outside extractTo is declared with the dataDirs field. A clean deploy wipes extractTo, so durable data belongs in a separate directory — /opt/data, for example. That directory is created by root (your install or preStart step, or the platform itself), so under an unprivileged start the app cannot write there until the directory is declared. Pass "dataDirs": ["/opt/data/state"] in the deploy body — the platform then creates the directory and hands it to vibeapp on every deploy, and hands ownership back if hardening is rolled back. The path must be absolute, already normalized and inside /opt, /srv or /var/lib; the bare roots (/opt, /var/lib) are refused with INVALID_DATA_DIRS before the deploy starts. Up to eight directories can be declared.

  What is handed over is the directory itself, not its contents — enough for the app to create its own files there. Files root put inside earlier stay with root, so the app cannot rewrite them. If the app has to modify exactly those (a database deployed in advance, a tree baked into the image), add "dataDirsRecursive": true.

  What matters about permissions. Whoever owns a directory can delete or replace any file in it, including files root put there. So do not declare a directory that holds scripts you later run as root (a database restore script you launch through /exec, for instance) or credentials the app is not meant to touch. Keep those in a directory you did not declare — which is exactly why the examples declare the /opt/data/state subdirectory rather than /opt/data itself: /opt/data is where our own recipes put service scripts that are run as root, along with a password file with 0600 permissions. For the same reason dataDirsRecursive is not accepted for /opt/data at all.

  If the deploy is not hardened ("hardening": "off", "systemd": false, or an extractTo outside the accepted roots) the field does nothing — the app already runs with administrator privileges. A separate data_dirs step then returns warning and says so explicitly. On a Galaxy application the field is ignored: durable data lives in the /data volume there.

• A file uploaded through /upload after a deploy belongs to root. The upload is performed by the agent with administrator privileges, while the deploy directory belongs to vibeapp once the deploy finishes — so the app cannot append to or overwrite such a file. If the app is meant to modify an uploaded file, ship it inside the source archive or hand ownership over in the next deploy's preStart.

  If the app fails its healthcheck under this mode, the deploy automatically restores the previous mode (both the unit and directory ownership) and finishes successfully, adding a hardening step with warning status and the journal tail explaining why. You will not lose a deploy to hardening.

  The rollback restores privileges and directory ownership, and that is all it does: it does not lift the requirement on the start command. A command that launches a daemon and exits behaves the same way after the rollback — the service dies together with it, whichever account it runs under. A hardening step in the response reports a change of run mode, not the reason the application is not answering.

  To skip the attempt outright, pass "hardening": "off" in the deploy body. That is the right call for apps that genuinely need administrator privileges: nginx as the start command, MySQL over the root socket, or a Docker-driven start.

• The install, preStart and start commands run through the POSIX shell /bin/sh. Write them in POSIX-compatible syntax. To stop on the first error, use set -e; for conditions, use [ ... ]. The set -o pipefail option is available only in bash — if you need it, call bash explicitly: bash -c 'set -o pipefail; commands'. The same applies to a separate script launched from start — begin it with the line #!/bin/bash or run it via bash script.sh.

• docker-compose-plugin is missing from the standard Ubuntu repositories — install Docker via the official script. The docker-compose-plugin package is a Docker CE component from the docker.com repository, which is not in the standard Ubuntu 24.04 apt sources. apt-get install docker-compose-plugin fails with the error Unable to locate package. The correct way to install Docker Engine + Compose V2 in a single command:

  Copy

  "preStart": "curl -fsSL https://get.docker.com | sh && systemctl enable --now docker"

  After that docker compose (no hyphen) is available as a plugin. If you only need Compose V1 (deprecated, for compatibility only), it is in the Ubuntu repos: apt-get install -y docker-compose.

• cleanDeploy: true cleans only extractTo, not the whole system. By default the /opt/app directory is deleted before extracting the new archive. System packages (apt), databases, files in /var/lib/, /etc/, /root/ are not affected — they survive any number of repeat deploys.

• System packages persist across sleep/wake, reboot, and repair. All these operations keep the virtual machine disk intact. There is no need to reinstall software via preStart on every deploy — doing it once is enough. Subsequent deploys without runtime and without the needed preStart commands find the packages in place.

• /etc/systemd/system/ is writable. You can create custom systemd units via preStart or /exec: systemctl daemon-reload && systemctl enable --now myservice. The standard deploy unit (app.service) does not conflict with user units when the names differ.

• When you change serviceName between deploys, stop the old service manually. The stop_existing step stops only the service with the current serviceName. If the previous deploy used the default name app and the next one uses dedup, then systemctl stop dedup does not find the previous app.service. The previous service keeps running and holds the app port — 3000 by default. The new service cannot bind to the port and goes into a restart loop. The healthcheck step recognizes this state, including the case where the previous process answers the request with code 200: the deploy fails. The error message names the port number and the process holding the port, and in the restart-loop case the state of the service as well. It does not always offer the command to free the port (fuser -k <port>/tcp): if the new service stayed up and the port is held by a process that was already on it before the deploy began, the message says exactly that and gives no command, because the holder may be a service you need. The platform does not terminate an unrelated process. Free the port with fuser -k <port>/tcp, stop the previous service with systemctl stop <old-name>.service via /exec, or restore the previous serviceName value, and then repeat the deploy. One caveat: when the port diagnostics could not run, a response with status 200–399 counts as success and the deploy completes successfully.

• Use debug: true when /deploy and the manual path diverge. It adds a debug_info step with sha256sum of files and file -i — it helps compare the state of /deploy with manual /upload + /exec byte by byte. A typical case — Tailwind v4 oxide fails on unexpected UTF-8.

• The archive type is detected automatically, there is no separate format field. For source.content the platform reads the signature of the first bytes (PK → zip, 1F 8B → tar.gz, BZ → tar.bz2), for source.url — the path extension. You do not need to pass the type as an explicit field — and there is no field to pass it in. Do not rely on an unrecognized archive being parsed. The recognized format now also selects how the archive is delivered to the machine, so "the format was not recognized, we will read it as tar.gz" turned from a promise into a last-resort fallback on the older delivery path. Package the archive as tar.gz (tar -czf app.tar.gz -C ./my-app .) or zip (zip -r app.zip .) — then the result does not depend on which delivery path the platform picks.

• tar.gz is preferred for uploading code. Both formats extract, but a zip built with PowerShell's Compress-Archive stores paths with a backslash \. Nested files from such an archive may end up in the root of extractTo instead of their folders, and part of the code will not reach the right place. The normalize_windows_paths step brings such paths back to normal, but to avoid the issue, pack the code into tar.gz: tar -czf app.tar.gz -C ./my-app .. If you need zip — pack it with a Unix tool: zip -r app.zip ..

• In the new mode, the platform downloads a dedicated VM's source.url archive. For servers enrolled in the rollout, it validates the destination of every connection and redirect, streams the response, and relays bounded chunks to the VM over the existing tunnel. Source availability therefore does not depend on that VM's egress or NAT path. Transient DNS/TCP/TLS/HTTP/body failures get up to four attempts with backoff inside a shared five-minute budget; extraction runs once after size and SHA-256 checks. Before enrollment, or when the agent does not support relay, a compatible VM-download path is used; while the kill switch is off it preserves the historical URL, timeout, and error contract. Stable sanitized failures apply to the new mode.

• Large inline archives compete for a slot. A source.content larger than ~10 KB holds the request in memory for the whole deploy, so only a few such requests run concurrently (by default 2 per backend). When you exceed it, a 429 is returned with a hint to switch to source.url or source.versionId: they do not consume this inline-memory slot, but URL relay has its own bounded pool. When saturated it returns DOWNLOAD_RELAY_BUSY after a successful runtime, when one was passed, but before stop_existing and clean: the orchestrator has not stopped the unit or cleaned the application tree. The runtime installer may already have changed host dependencies, and those changes are not rolled back. Small inline archives and versionId do not take a slot.

• A deploy from an external URL requires a source snapshot or an explicit opt-out. When source storage is enabled for your Bitrix24 account, a deploy with a source.url that does not point at Vibecode storage returns 409 SNAPSHOT_REQUIRED — this way the application version history is not lost on a deploy from a third-party address. There are two options. Pass the X-Skip-Source-Snapshot: <reason ≤200 characters> header — the deploy continues without saving a snapshot. Or first upload the archive via POST /v1/apps/:id/sources and deploy it via { "source": { "versionId": "vN" } } — then the platform saves the version. A source from storage itself — source.versionId or source.content — does not require this header. More details — Source storage.

• A Galaxy application does not need its own Dockerfile — the platform generates it itself. From the deploy fields runtime and port, and for non-static runtimes start, the platform builds a Dockerfile with the runtime base image and an EXPOSE <port> line. Non-static CMD is derived from start; static uses the platform nginx command and ignores start. Putting your own Dockerfile in the archive is not required and not needed. This applies only to a Galaxy application — the createdVia field equals galaxy.

• The build error published no host port for <port> means the container did not stay up on port, not that EXPOSE is missing. For a Galaxy application this text arrives when the container crashed on start, the start command is wrong, or the application listens on a different port — that is, nothing responds on port. Fix start and port so the application actually listens on port. There is no need to add EXPOSE manually: the platform already set it from port.

• A Galaxy application's env variables are injected into the container at startup, not baked into the image. The platform passes them with the docker run --env flag when the container starts, so secrets from env do not end up in the image layers and are not visible in its history. This applies only to a Galaxy application — the createdVia field equals galaxy.

• A Galaxy application deploy without user env resets environment variables and returns warnings[]. The container is recreated on every deploy, and variables are passed only as startup arguments from the current request. If /deploy omits env, sends {}, or sends only the platform-owned PORT, the owner's container starts without previous user variables; the successful response warns about the reset and asks for the complete env set on every deploy. preserveEnv is ignored for a Galaxy application and does not hide the warning. A development-team member's deploy is the exception: the platform preserves variables already set by the owner, so there is no reset warning; env sent by the member is ignored with a separate warning. The .env-preservation strategies — preserveEnv, a file outside extractTo, cleanDeploy: false — are available only for a dedicated virtual machine.

• The galaxy host downloads an archive from source storage itself, and the cause of a failure is named separately. When the deploy runs from a source.versionId snapshot and the archive is packed as tar.gz, the machine downloads it itself and checks the size and the checksum against the saved version right there. If the download or the unpacking fails, 502 GALAXY_APP_BUILD_FAILED arrives and the buildLog tail opens with a cause marker: UPLOAD_DOWNLOAD_FAILED — it did not download, UPLOAD_EXTRACT_FAILED — it did not unpack, UPLOAD_NO_SPACE — the host is out of space. The markers land in error.category as SOURCE_FETCH_FAILED, SOURCE_EXTRACT_FAILED and RESOURCE — what to do about each cause is in the category table below. The one thing the table does not say: when the host is out of space, shrinking the archive is pointless — it is not your files that filled the disk. The host-side download is enabled per account, while zip archives and archives above the link size cap take the previous path — there the cause arrives as a single message about the failed extraction.

• Galaxy build and start errors arrive with the cause diagnosed. For 502 GALAXY_APP_BUILD_FAILED and 502 GALAXY_APP_START_FAILED the platform parses the build log and, when the cause is recognized, adds two fields to the error object: category — a machine code for the cause, buildHint — a recommendation in the API key's language. The possible category values:

  Value	What happened
  NO_SOURCE	The application slot was created, the code was never uploaded
  DEPLOY_INCOMPLETE	The code upload did not finish — the build was interrupted or the host was unreachable
  SOURCE_FETCH_FAILED	The archive could not be downloaded to the machine — the link expired, the connection dropped, or the contents did not match the saved version. Send the deploy again: a fresh link is issued
  SOURCE_EXTRACT_FAILED	The archive downloaded but could not be unpacked — a corrupt archive, or members pointing outside the extraction directory
  EMPTY_CONTEXT	The archive extracted to an empty context — it holds no application files
  BUILD_TIMEOUT	The build did not finish within its time limit
  PORT_NOT_PUBLISHED	The container did not bind to port — the application exited right at start
  RUNTIME_CRASH	The container built but did not stay alive after start
  RUNTIME_OOM	The container ran out of memory after start — it hit the galaxy memory limit
  RESOURCE	The host ran out of free disk space — either while the archive was being downloaded to the machine or during the build itself. Over HTTP a build-time shortage arrives under its own code, 502 GALAXY_LOW_DISK, which is retryable and does not mark the application broken, while the server record keeps this category
  BASE_IMAGE_UNAVAILABLE	The image registry was unreachable at the step that fetches the build base image. This is transient — the same deploy goes through on a retry
  HOST_UNAVAILABLE	The galaxy host was unreachable during the build
  NO_PACKAGE_JSON	An install command was set explicitly, but there is no package.json at the archive root
  MODULE_NOT_FOUND	A module was not found — the entry path in start, or a missing dependency
  INSTALL_FAILED	Dependency installation failed
  INSTALL_AUTH	The package registry returned 401 or 403 — no access to a private package
  INSTALL_REGISTRY_UNAVAILABLE	The Python or Node.js package registry, or the Debian package source, did not answer while installing a dependency or system package. The failure is terminal — the platform does not retry it
  NATIVE_PREBUILD_UNAVAILABLE	The prebuilt artifact of a dependency shipping compiled code could not be downloaded: the external source did not answer, and the app image provides no way to build it from source. The condition is temporary — the same deploy passes on a retry. The failure is terminal: the platform does not retry it — send the deploy again yourself in a few minutes

  When the cause could not be recognized, neither field is present — only code, message and buildLog remain. Branch in code on category, show buildHint to the user.

• The 502 GALAXY_HOST_UNREACHABLE response has an error.hint field with a recovery plan. It is an object of four strings: reason — why the host is unreachable right now, recovery — what to do, recoveryAction — the next safe call, note — a caveat that the host status in the listing can lag behind the real tunnel state. Deploy has two branches. With retryable: false, the build was dispatched and its durable outcome is unknown: recoveryAction points to the operation list; do not repeat the deploy blindly. Without retryable: false, the refusal happened before build dispatch and the hint permits a retry after the tunnel recovers. There is no need to delete and recreate the application — the slot, container and /data volume are intact.

• The deploy wakes a sleeping dedicated virtual machine itself and waits for it within the same request. If the server (kind: "STANDALONE") is in sleeping status, the deploy starts the wake and waits for readiness for up to 6.5 minutes: 5 minutes for the machine to start and the tunnel to connect, then another 90 seconds of waiting without a reboot. If it makes it in time, the deploy continues in the same request and a separate /wake call is not needed. If it does not, 503 WAKE_TIMEOUT arrives and the server returns to sleeping — a repeat request is safe and starts the wake over. The deploy does not bypass a wake block: with a frozen balance the request is rejected before the deploy with 402 ACCOUNT_FROZEN, and for the other causes — for example, expired platform access or an administrative block — 403 SERVER_WAKE_BLOCKED arrives. In both cases a retry will not help until that state changes. /exec, /upload and /logs behave the same way.

• The deploy wakes a sleeping galaxy itself, and the first request may not have enough time. If the galaxy host is asleep, the deploy starts the wake in the background and waits for the tunnel to connect for about 4 minutes. A cold host usually fits into that window and the deploy goes through in a single request. If the wait times out before the build is dispatched, 502 GALAXY_HOST_UNREACHABLE arrives without retryable: false, and the host keeps booting — the platform does not roll the wake back; follow error.hint after the tunnel recovers. If the response carries retryable: false, the build was dispatched and its outcome is unknown: read the operation list, server state, and logs first; do not repeat the deploy blindly. A host frozen for billing or stopped manually is not woken — a retry will not help there until that state changes.

See also

• Runtimes list
• Run a command
• Service logs
• Release a stuck lock
• Set the port
• Scheduled wake
• Source storage