Start with the credentials and shell setup. Choose the Bash, PowerShell or Node.js version at each step. Use the matching setup's helpers and variables. If you issued a service token in the slice guide, continue with that token and set the service base URL; do not create another token.
For GitHub setup, release webhooks, or switching deployment sources, see Configure GitHub deployment through the API.
For an already configured API-upload service, the process is:
Configuration, troubleshooting and rollback instructions are included below.
See Runtime operations and private database services for Docker HEALTHCHECK readiness, private MariaDB/Redis provisioning, maintenance jobs, start/stop/restart, resource samples and capability discovery.
Check the service#
Linux / macOS - Bash
api "$BASE" | jq .data
api "$BASE/configuration" > "$STATE/configuration.json"
jq .data "$STATE/configuration.json"
Windows - PowerShell 7.4+
$capabilities = Invoke-Api -Uri $Base -Token $ServiceToken
$capabilities.data | ConvertTo-Json -Depth 30
$configuration = Invoke-Api -Uri "$Base/configuration" -Token $ServiceToken
Save-Json $configuration "$State/configuration.json"
$configuration.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
console.log((await api(base)).data);
const configuration = await api(`${base}/configuration`);
await saveJson(`${state}/configuration.json`, configuration);
console.log(configuration.data);
}
Capabilities report supported inputs, target platform, upload limits and ready.
If ready is false, inspect the reason. Missing application settings can be
configured below; placement/capacity problems require Budgethost support.
Configuration exposes two different kinds of address:
urls: public service URLs, including the automatically assigned public address when its route has been applied. This list can be empty before the first successful deployment or when no public route is configured. Use the returned scheme; HTTPS appears once a certificate is applied.internal_hostname: the private DNS hostname for connections from services on the same Docker virtual network. It is not a public URL or a readiness check.
Linux / macOS - Bash
api "$BASE/configuration" | jq '.data | {urls, internal_hostname}'
Windows - PowerShell 7.4+
$configuration = Invoke-Api -Uri "$Base/configuration" -Token $ServiceToken
$configuration.data | Select-Object urls, internal_hostname
Node.js - all operating systems
{
const { urls, internal_hostname } = (await api(`${base}/configuration`)).data;
console.log({ urls, internal_hostname });
}
See Connect services internally. Configuration lists assigned resources and environment names but omits environment values and secret values. If your service is already configured, skip to Prepare source or an image.
Configure a new service#
Skip this section when you only want to deploy a new release with existing settings.
Port and storage#
The final Dockerfile stage's single literal EXPOSE port can be inferred. Override
it with manifest.port when needed. Source uploads do not implicitly apply settings.
The app must actually listen on that port on all container interfaces. Dockerfile
ENV, VOLUME and shell HEALTHCHECK instructions are not imported as API settings.
If persistent storage is not already attached, create it once. Reuse existing volumes when deploying a new release:
Linux / macOS - Bash
uuid > "$STATE/storage.key"
cat > "$STATE/storage-request.json" <<'JSON'
{
"name": "data",
"mount_path": "/data"
}
JSON
api --header 'Content-Type: application/json' \
--header "X-Idempotency-Key: $(cat "$STATE/storage.key")" \
--data-binary @"$STATE/storage-request.json" "$BASE/storage" > "$STATE/storage.json"
api "$BASE/configuration" > "$STATE/configuration.json"
Windows - PowerShell 7.4+
New-Key "$State/storage.key"
Save-Json @{ name = 'data'; mount_path = '/data' } "$State/storage-request.json"
$storage = Invoke-Api -Uri "$Base/storage" -Token $ServiceToken -Method Post `
-KeyFile "$State/storage.key" -BodyFile "$State/storage-request.json"
Save-Json $storage "$State/storage.json"
Save-Json (Invoke-Api -Uri "$Base/configuration" -Token $ServiceToken) "$State/configuration.json"
Node.js - all operating systems
{
await newKey(`${state}/storage.key`);
await saveJson(`${state}/storage-request.json`, { name: 'data', mount_path: '/data' });
const storage = await api(`${base}/storage`, {
method: 'POST', keyFile: `${state}/storage.key`, bodyFile: `${state}/storage-request.json`,
});
await saveJson(`${state}/storage.json`, storage);
await saveJson(`${state}/configuration.json`, await api(`${base}/configuration`));
}
The mount is saved in desired configuration and takes effect at deployment.
For an existing mount at /data, no additional storage binding is needed. For an
unmounted resource, use its returned storage ID/path key in the configuration
request's bindings.storage map. Never guess IDs or use another service's storage.
Secrets#
Create a secret from a private JSON file containing {"value":"YOUR_SECRET"}.
Do not put this file inside the source tree:
Linux / macOS - Bash
# SECRET_FILE is an absolute path to your private JSON file.
api --request PUT --header 'Content-Type: application/json' --data-binary @"$SECRET_FILE" \
"$BASE/configuration/secrets/APP_SECRET" > "$STATE/app-secret.json"
APP_SECRET_ID=$(jq -er '.data.secret_id' "$STATE/app-secret.json")
Windows - PowerShell 7.4+
# Set $SecretFile to the absolute path of your private JSON file.
$secret = Invoke-Api -Uri "$Base/configuration/secrets/APP_SECRET" `
-Token $ServiceToken -Method Put -BodyFile $SecretFile
Save-Json $secret "$State/app-secret.json"
$AppSecretId = $secret.data.secret_id
Node.js - all operating systems
{
// Set secretFile to the absolute path of your private JSON file.
const secret = await api(`${base}/configuration/secrets/APP_SECRET`, {
method: 'PUT', bodyFile: secretFile,
});
await saveJson(`${state}/app-secret.json`, secret);
deploy.secretId = secret.data.secret_id;
}
The response contains a secret ID, never its value. Repeat for other secret names as needed. Replacing signing keys or application passwords can affect sessions; retain existing secrets when you are only deploying new code.
Preview your configuration#
Here is a generic example for a service that listens on port 8080, has a /health endpoint, and uses /data for persistent files. Change these values to match your application. This example assumes the volume is already attached.
Linux / macOS - Bash
cat > "$STATE/configuration-template.json" <<'JSON'
{
"manifest": {
"version": 1,
"port": 8080,
"readiness": {
"path": "/health"
},
"storage": [
{ "name": "data", "mount_path": "/data" }
],
"environment": {
"DATA_DIRECTORY": { "default": "/data" },
"APP_SECRET": { "required": true, "secret": true }
}
}
}
JSON
# Add your Dockerfile and the secret ID returned in the previous step.
jq --rawfile dockerfile Dockerfile --arg secret "$APP_SECRET_ID" \
'. + {dockerfile: $dockerfile, bindings: {secret_refs: {APP_SECRET: $secret}}}' \
"$STATE/configuration-template.json" > "$STATE/configuration-request.json"
api --header 'Content-Type: application/json' --data-binary @"$STATE/configuration-request.json" \
"$BASE/configuration/preview" > "$STATE/review.json"
jq .data "$STATE/review.json"
Windows - PowerShell 7.4+
$configurationRequest = @{
manifest = @{
version = 1
port = 8080
readiness = @{ path = '/health' }
storage = @(@{ name = 'data'; mount_path = '/data' })
environment = @{
DATA_DIRECTORY = @{ default = '/data' }
APP_SECRET = @{ required = $true; secret = $true }
}
}
dockerfile = Get-Content -LiteralPath './Dockerfile' -Raw
bindings = @{ secret_refs = @{ APP_SECRET = $AppSecretId } }
}
Save-Json $configurationRequest "$State/configuration-request.json"
$review = Invoke-Api -Uri "$Base/configuration/preview" -Token $ServiceToken `
-Method Post -BodyFile "$State/configuration-request.json"
Save-Json $review "$State/review.json"
$review.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
const request = {
manifest: {
version: 1,
port: 8080,
readiness: { path: '/health' },
storage: [{ name: 'data', mount_path: '/data' }],
environment: {
DATA_DIRECTORY: { default: '/data' },
APP_SECRET: { required: true, secret: true },
},
},
dockerfile: await readFile('Dockerfile', 'utf8'),
bindings: { secret_refs: { APP_SECRET: deploy.secretId } },
};
await saveJson(`${state}/configuration-request.json`, request);
const review = await api(`${base}/configuration/preview`, {
method: 'POST', bodyFile: `${state}/configuration-request.json`,
});
await saveJson(`${state}/review.json`, review);
console.log(review.data);
}
Apply the reviewed configuration#
Review changes, warnings and missing. Resolve missing settings before saving.
Defaults only fill absent environment variables. To change a declared non-secret
variable explicitly, use bindings.environment. New installations must also declare
and bind their required bootstrap username/password; a required secret uses
{ "required": true, "secret": true } plus its ID in bindings.secret_refs.
Linux / macOS - Bash
jq -e '.data.can_apply == true' "$STATE/review.json" >/dev/null
jq --slurpfile review "$STATE/review.json" \
'. + {review_id:$review[0].data.review_id}' "$STATE/configuration-request.json" \
> "$STATE/configuration-apply.json"
api --header 'Content-Type: application/json' --data-binary @"$STATE/configuration-apply.json" \
"$BASE/configuration/apply" | jq .data
Windows - PowerShell 7.4+
$review = Read-Json "$State/review.json"
if (-not $review.data.can_apply) { throw 'Resolve missing settings before applying.' }
$apply = Read-Json "$State/configuration-request.json"
$apply.review_id = $review.data.review_id
Save-Json $apply "$State/configuration-apply.json"
$result = Invoke-Api -Uri "$Base/configuration/apply" -Token $ServiceToken `
-Method Post -BodyFile "$State/configuration-apply.json"
$result.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
const review = await readJson(`${state}/review.json`);
if (!review.data.can_apply) throw new Error('Resolve missing settings before applying');
const request = await readJson(`${state}/configuration-request.json`);
request.review_id = review.data.review_id;
await saveJson(`${state}/configuration-apply.json`, request);
console.log((await api(`${base}/configuration/apply`, {
method: 'POST', bodyFile: `${state}/configuration-apply.json`,
})).data);
}
Apply saves settings but does not restart the application. Deploy afterwards. A stale review returns 409: inspect current settings and preview again. Configuration mutations are blocked during active deployments.
Prepare source or an image#
Choose one of the two options below.
Read current capabilities for actual limits; defaults are 256 MiB compressed source, 2 GiB image archive, 2 GiB extracted source, 100,000 source entries and a 30-minute preparation timeout.
Source: prepare a clean build-context directory containing the root Dockerfile,
.dockerignore, and required source files. Exclude credentials, .git, databases,
user uploads and build output before archiving. .dockerignore does not remove
files from the uploaded tarball. Links, special files, duplicate paths and traversal
are rejected; use ustar rather than PAX/GNU extension records.
Linux / macOS - Bash
# Set SOURCE_DIR to your reviewed, clean build-context directory.
test -f "$SOURCE_DIR/Dockerfile"
test -f "$SOURCE_DIR/.dockerignore"
FILE="$STATE/source.tar.gz"
COPYFILE_DISABLE=1 tar --format=ustar -czf "$FILE" -C "$SOURCE_DIR" .
TYPE=source
Windows - PowerShell 7.4+
# Set $SourceDir to your reviewed, clean build-context directory.
$SourceDir = (Resolve-Path -LiteralPath $SourceDir).Path
foreach ($required in @('Dockerfile', '.dockerignore')) {
if (-not (Test-Path -LiteralPath "$SourceDir/$required" -PathType Leaf)) {
throw "Missing $required"
}
}
$File = "$State/source.tar.gz"
# PowerShell 7.4+ includes .NET's USTAR writer; no external tar is required.
$archive = [IO.File]::Create($File)
try {
$gzip = [IO.Compression.GZipStream]::new($archive, [IO.Compression.CompressionLevel]::Optimal, $true)
try {
$writer = [System.Formats.Tar.TarWriter]::new($gzip, [System.Formats.Tar.TarEntryFormat]::Ustar, $true)
try {
foreach ($item in Get-ChildItem -LiteralPath $SourceDir -Recurse -Force) {
if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw "Links are not allowed: $($item.Name)" }
if ($item.PSIsContainer) { continue }
$relative = [IO.Path]::GetRelativePath($SourceDir, $item.FullName).Replace('\', '/')
$writer.WriteEntry($item.FullName, $relative)
}
} finally { $writer.Dispose() }
} finally { $gzip.Dispose() }
} finally { $archive.Dispose() }
$Type = 'source'
Node.js - all operating systems
{
// Set sourceDir to your reviewed, clean build-context directory.
// Requires tar on PATH (included with modern Windows and macOS; install on Linux).
for (const name of ['Dockerfile', '.dockerignore']) {
if (!(await stat(path.join(sourceDir, name))).isFile()) throw new Error(`Missing ${name}`);
}
deploy.file = path.join(state, 'source.tar.gz');
run('tar', ['--format=ustar', '-czf', deploy.file, '-C', sourceDir, '.'], {
env: { ...process.env, COPYFILE_DISABLE: '1' },
});
deploy.type = 'source';
}
Image: build for the platform returned by capabilities, then save exactly one
image. Use docker save, not docker export. No registry login/push is required:
Linux / macOS - Bash
PLATFORM=$(api "$BASE" | jq -er '.data.platform')
docker build --platform "$PLATFORM" -t my-app:release .
FILE="$STATE/image.tar"
docker save -o "$FILE" my-app:release
TYPE=image
Windows - PowerShell 7.4+
$platform = (Invoke-Api -Uri $Base -Token $ServiceToken).data.platform
docker build --platform $platform -t my-app:release .
if ($LASTEXITCODE -ne 0) { throw 'Docker build failed.' }
$File = "$State/image.tar"
docker save -o $File my-app:release
if ($LASTEXITCODE -ne 0) { throw 'Docker save failed.' }
$Type = 'image'
Node.js - all operating systems
{
const platform = (await api(base)).data.platform;
run('docker', ['build', '--platform', platform, '-t', 'my-app:release', '.']);
deploy.file = path.join(state, 'image.tar');
run('docker', ['save', '-o', deploy.file, 'my-app:release']);
deploy.type = 'image';
}
Build-time private package credentials are not supplied through runtime secret settings. Contact support if the build requires a private dependency source.
Create the deployment#
Create retry keys once for this release and retain the state directory. Do not rerun the key-generation commands when recovering an interrupted request.
Linux / macOS - Bash
uuid > "$STATE/create.key"
uuid > "$STATE/start.key"
# Python avoids GNU/BSD differences between Linux and macOS.
BYTES=$(python3 -c 'import os, sys; print(os.path.getsize(sys.argv[1]))' "$FILE")
SHA=$(python3 - "$FILE" <<'PYTHON'
import hashlib, sys
checksum = hashlib.sha256()
with open(sys.argv[1], "rb") as archive:
for chunk in iter(lambda: archive.read(1024 * 1024), b""):
checksum.update(chunk)
print(checksum.hexdigest())
PYTHON
)
cat > "$STATE/create.json" <<JSON
{
"type": "$TYPE",
"bytes": $BYTES,
"sha256": "$SHA"
}
JSON
api --header 'Content-Type: application/json' \
--header "X-Idempotency-Key: $(cat "$STATE/create.key")" \
--data-binary @"$STATE/create.json" "$BASE/deployments" > "$STATE/deployment.json"
ID=$(jq -er '.data.id' "$STATE/deployment.json")
printf '%s\n' "$ID" > "$STATE/deployment.id"
Windows - PowerShell 7.4+
New-Key "$State/create.key"
New-Key "$State/start.key"
Save-Json @{
type = $Type
bytes = (Get-Item -LiteralPath $File).Length
sha256 = (Get-FileHash -LiteralPath $File -Algorithm SHA256).Hash.ToLowerInvariant()
} "$State/create.json"
$deployment = Invoke-Api -Uri "$Base/deployments" -Token $ServiceToken `
-Method Post -KeyFile "$State/create.key" -BodyFile "$State/create.json"
Save-Json $deployment "$State/deployment.json"
$Id = $deployment.data.id
$Id | Set-Content -LiteralPath "$State/deployment.id" -Encoding utf8NoBOM
Node.js - all operating systems
{
await newKey(`${state}/create.key`);
await newKey(`${state}/start.key`);
const hash = createHash('sha256');
for await (const chunk of createReadStream(deploy.file)) hash.update(chunk);
await saveJson(`${state}/create.json`, {
type: deploy.type,
bytes: (await stat(deploy.file)).size,
sha256: hash.digest('hex'),
});
const deployment = await api(`${base}/deployments`, {
method: 'POST', keyFile: `${state}/create.key`, bodyFile: `${state}/create.json`,
});
await saveJson(`${state}/deployment.json`, deployment);
deploy.id = deployment.data.id;
await writeFile(`${state}/deployment.id`, deploy.id, { mode: 0o600 });
}
Upload the archive#
Linux / macOS - Bash
api --request PUT --header 'Content-Type: application/octet-stream' --data-binary @"$FILE" \
"$BASE/deployments/$ID/artifact" > "$STATE/upload.json"
Windows - PowerShell 7.4+
$uploaded = Invoke-Api -Uri "$Base/deployments/$Id/artifact" -Token $ServiceToken `
-Method Put -UploadFile $File
Save-Json $uploaded "$State/upload.json"
Node.js - all operating systems
{
const uploaded = await api(`${base}/deployments/${deploy.id}/artifact`, {
method: 'PUT', uploadFile: deploy.file,
});
await saveJson(`${state}/upload.json`, uploaded);
}
Start the deployment#
Linux / macOS - Bash
api --header 'Content-Type: application/json' \
--header "X-Idempotency-Key: $(cat "$STATE/start.key")" --data '{}' \
"$BASE/deployments/$ID/start" > "$STATE/start.json"
Windows - PowerShell 7.4+
Save-Json @{} "$State/start-request.json"
$started = Invoke-Api -Uri "$Base/deployments/$Id/start" -Token $ServiceToken `
-Method Post -KeyFile "$State/start.key" -BodyFile "$State/start-request.json"
Save-Json $started "$State/start.json"
Node.js - all operating systems
{
await saveJson(`${state}/start-request.json`, {});
const started = await api(`${base}/deployments/${deploy.id}/start`, {
method: 'POST', keyFile: `${state}/start.key`, bodyFile: `${state}/start-request.json`,
});
await saveJson(`${state}/start.json`, started);
}
Start returns 202 Accepted. Preparation finishes before the running app is changed. A build/import failure leaves the current app in place. A failure during runtime replacement can affect availability; inspect the failure and explicitly redeploy a retained successful image when appropriate.
Poll and read logs#
Linux / macOS - Bash
while :; do
api "$BASE/deployments/$ID" > "$STATE/status.json"
STATUS=$(jq -er '.data.status' "$STATE/status.json")
printf '%s\n' "$STATUS"
case "$STATUS" in
succeeded) break ;;
failed|cancelled) jq '.data.failure' "$STATE/status.json"; break ;;
esac
sleep 3
done
jq .data "$STATE/status.json"
# A script must fail when deployment failed.
jq -e '.data.status == "succeeded"' "$STATE/status.json" >/dev/null
Windows - PowerShell 7.4+
do {
$status = Invoke-Api -Uri "$Base/deployments/$Id" -Token $ServiceToken
Save-Json $status "$State/status.json"
Write-Host $status.data.status
if ($status.data.status -in @('succeeded', 'failed', 'cancelled')) { break }
Start-Sleep -Seconds 3
} while ($true)
$status.data | ConvertTo-Json -Depth 30
if ($status.data.status -ne 'succeeded') { throw 'Deployment failed. Inspect its failure and logs.' }
Node.js - all operating systems
{
while (true) {
const status = await api(`${base}/deployments/${deploy.id}`);
await saveJson(`${state}/status.json`, status);
console.log(status.data.status);
if (['failed', 'cancelled'].includes(status.data.status)) throw new Error('Deployment did not succeed; inspect status, failure and logs');
if (status.data.status === 'succeeded') { console.log(status.data); break; }
await new Promise(resolve => setTimeout(resolve, 3000));
}
}
Stages are awaiting_upload, ready, queued, building or importing,
deploying, verifying, and finally succeeded or failed. An explicitly
cancelled unstarted deployment has status cancelled. To stop waiting,
interrupt the polling command; this does not cancel the deployment.
For a new hostname, HTTPS certificate issuance and activation can finish shortly after deployment succeeds. If HTTPS is not ready yet, wait a few seconds and retry with normal certificate verification enabled. Refresh the service configuration to read its current URLs; they use HTTPS once a certificate is applied to the route. If HTTPS continues to fail, contact support with the hostname and deployment ID.
Run log commands separately while a build is running and after completion:
Linux / macOS - Bash
CURSOR=0
api "$BASE/deployments/$ID/logs?cursor=$CURSOR&limit=100" > "$STATE/logs.json"
jq '.data.entries' "$STATE/logs.json"
CURSOR=$(jq -er '.data.next_cursor' "$STATE/logs.json")
# Repeat the request with the updated CURSOR for subsequent entries.
api "$BASE/deployments" | jq .data
Windows - PowerShell 7.4+
$Cursor = 0
$logs = Invoke-Api -Uri "$Base/deployments/$Id/logs?cursor=$Cursor&limit=100" -Token $ServiceToken
Save-Json $logs "$State/logs.json"
$logs.data.entries | Format-Table at, message -Wrap
$Cursor = $logs.data.next_cursor
# Repeat the log request with the updated cursor for subsequent entries.
(Invoke-Api -Uri "$Base/deployments" -Token $ServiceToken).data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
deploy.cursor ??= 0;
const logs = await api(`${base}/deployments/${deploy.id}/logs?cursor=${deploy.cursor}&limit=100`);
await saveJson(`${state}/logs.json`, logs);
console.log(logs.data.entries);
deploy.cursor = logs.data.next_cursor;
// Repeat the log request with the updated cursor for subsequent entries.
console.log((await api(`${base}/deployments`)).data);
}
These are deployment/build logs, not a live application stdout stream. They include bounded build output and platform stage messages. Avoid printing secrets in builds; redaction cannot recognize every possible secret.
Log entries include at, stream, stage and a monotonic cursor. Poll with
next_cursor; continue immediately while has_more is true. The server retains
at most 1000 entries / 512 KiB per deployment for up to 30 days. Check
cursor_expired, first_available_cursor, dropped_entries, transport_gaps
and entry-level truncated / dropped_bytes for missing output.
progress.current_step identifies the Dockerfile step when available.
progress.last_output_at records output activity; progress.last_worker_at
records the latest build-progress confirmation, even when a command produces no output.
coverage: not_reported means no live output or heartbeat has been received;
live means current build progress has been reported; expired means retained history expired.
An empty page alone does not establish that a build is stalled or healthy.
Failures expose a safe reason and message, plus exit_code when available.
For example, SOURCE_DOCKERIGNORE_REQUIRED means the source archive needs a
regular .dockerignore at its root. BUILDER_SETUP_FAILED requires support to
check the builder; changing your archive may not resolve it.
Cancel an unstarted upload#
Before start has been accepted, cancel an awaiting_upload or ready deployment
to replace an incorrect archive. This requires deploy permission. Repeating the
request is safe and returns cancelled; no idempotency key is needed. The upload
and reservation are released while the running application and volumes stay intact.
Create the corrected deployment with a new creation key and its new length/hash.
Linux / macOS - Bash
api --request POST --header 'Content-Type: application/json' --data '{}' \
"$BASE/deployments/$ID/cancel" > "$STATE/cancel.json"
Windows - PowerShell 7.4+
Save-Json @{} "$State/cancel-request.json"
$cancelled = Invoke-Api -Uri "$Base/deployments/$Id/cancel" -Token $ServiceToken `
-Method Post -BodyFile "$State/cancel-request.json"
Save-Json $cancelled "$State/cancel.json"
Node.js - all operating systems
{
await saveJson(`${state}/cancel-request.json`, {});
const cancelled = await api(`${base}/deployments/${deploy.id}/cancel`, {
method: 'POST', bodyFile: `${state}/cancel-request.json`,
});
await saveJson(`${state}/cancel.json`, cancelled);
}
Once start has been accepted, even while queued, cancellation returns
409 DEPLOYMENT_ALREADY_STARTED. Keep polling the existing deployment.
Recover interrupted requests#
- Lost create response: repeat the exact create POST using saved
create.jsonandcreate.key; extract the returned ID again. Do not create a fresh release. - Interrupted upload: inspect deployment status. Before start, retry the complete PUT from byte zero with the same archive. Partial files do not become ready.
- Lost start response: repeat POST
/deployments/{id}/startwith the saved start key and{}. Then poll the same ID. Do not upload again after start. - 401: token expired, revoked or invalid. Obtain replacement credentials. Check history before retrying mutations under a different token.
- 409: read
error.codeanderror.details; a deployment may be active, input may differ from the original key, or configuration may have changed. Poll/inspect rather than blindly creating another operation. - 413: archive exceeds limits. Reduce its size or contact support. A checksum failure requires the original matching bytes or a new creation request/key.
- Network/5xx: preserve state and inspect/retry the same request. For recurring errors, send support the deployment ID and redacted response/request ID.
Roll back explicitly#
List deployment history and select a retained, successful deployment from this same service. Rollback creates a new deployment and uses the current configuration. Database migrations, persistent files and secret changes are not undone.
Linux / macOS - Bash
# Set PREVIOUS_SUCCESSFUL_ID after inspecting history.
ROLLBACK_STATE=$(mktemp -d)
uuid > "$ROLLBACK_STATE/create.key"
uuid > "$ROLLBACK_STATE/start.key"
jq -n --arg id "$PREVIOUS_SUCCESSFUL_ID" \
'{type:"redeploy",deployment_id:$id}' > "$ROLLBACK_STATE/create.json"
api --header 'Content-Type: application/json' \
--header "X-Idempotency-Key: $(cat "$ROLLBACK_STATE/create.key")" \
--data-binary @"$ROLLBACK_STATE/create.json" "$BASE/deployments" \
> "$ROLLBACK_STATE/deployment.json"
ID=$(jq -er '.data.id' "$ROLLBACK_STATE/deployment.json")
api --header 'Content-Type: application/json' \
--header "X-Idempotency-Key: $(cat "$ROLLBACK_STATE/start.key")" --data '{}' \
"$BASE/deployments/$ID/start" > "$ROLLBACK_STATE/start.json"
STATE="$ROLLBACK_STATE"
Windows - PowerShell 7.4+
# Set $PreviousSuccessfulId after inspecting history.
$RollbackState = New-RequestDirectory
New-Key "$RollbackState/create.key"
New-Key "$RollbackState/start.key"
Save-Json @{ type = 'redeploy'; deployment_id = $PreviousSuccessfulId } "$RollbackState/create.json"
$deployment = Invoke-Api -Uri "$Base/deployments" -Token $ServiceToken `
-Method Post -KeyFile "$RollbackState/create.key" -BodyFile "$RollbackState/create.json"
Save-Json $deployment "$RollbackState/deployment.json"
$Id = $deployment.data.id
$Id | Set-Content -LiteralPath "$RollbackState/deployment.id" -Encoding utf8NoBOM
Save-Json @{} "$RollbackState/start-request.json"
$started = Invoke-Api -Uri "$Base/deployments/$Id/start" -Token $ServiceToken `
-Method Post -KeyFile "$RollbackState/start.key" -BodyFile "$RollbackState/start-request.json"
Save-Json $started "$RollbackState/start.json"
$State = $RollbackState
Node.js - all operating systems
{
// Set previousSuccessfulId after inspecting history.
const rollbackState = await newState();
await newKey(`${rollbackState}/create.key`);
await newKey(`${rollbackState}/start.key`);
await saveJson(`${rollbackState}/create.json`, {
type: 'redeploy', deployment_id: previousSuccessfulId,
});
const deployment = await api(`${base}/deployments`, {
method: 'POST', keyFile: `${rollbackState}/create.key`, bodyFile: `${rollbackState}/create.json`,
});
await saveJson(`${rollbackState}/deployment.json`, deployment);
deploy.id = deployment.data.id;
await writeFile(`${rollbackState}/deployment.id`, deploy.id, { mode: 0o600 });
await saveJson(`${rollbackState}/start-request.json`, {});
const started = await api(`${base}/deployments/${deploy.id}/start`, {
method: 'POST', keyFile: `${rollbackState}/start.key`, bodyFile: `${rollbackState}/start-request.json`,
});
await saveJson(`${rollbackState}/start.json`, started);
state = rollbackState;
}
Use the same polling/log commands. No artifact upload is required. Retry with the saved rollback keys if interrupted. There is no automatic rollback. History/logs are normally retained for 30 days; rollback also requires the referenced image to remain retained. The current image and five previous successful images are protected from registry cleanup. Every successful deployment referencing an image in this retained set stays usable, including the original handle after repeated same-image redeploys. Retained handle metadata lasts while that exact image is protected; its logs still expire after 30 days. Once the image leaves the retained set, its handles become unretained and ordinary 30-day record cleanup applies. Ownership and exact image identity are checked on every redeploy; no different image is silently selected.
Registry pull credentials#
Use GET, PUT or DELETE on
/v1/deploy/services/{serviceId}/configuration/registry-login for an enabled
registry-backed application. Use a service token: read permits GET;
applications:manage permits PUT and DELETE. A slice token must first issue a
member service token. An environment secret does not configure image-pull access.
PUT accepts exactly username and password; a registry access token can be the
password. The server derives the registry from the service's configured image,
normalizing Docker Hub aliases to docker.io. A service without an image returns
409 REGISTRY_IMAGE_REQUIRED. It does not accept an arbitrary registry server or
secret ID. Usernames are trimmed, limited to 256 characters, and cannot contain
colons or line breaks. Passwords must contain 1-16384 characters without NUL or
line breaks. Neither field may contain NUL.
These operations update the registry binding visible in Portal and preserve
application environment, storage, routes and other settings. PUT saves a new
credential version before switching the binding. Failed service validation leaves
the previously bound username and password intact. A concurrent configuration
change returns 409 CONFIGURATION_REVIEW_STALE; reload the configuration and
review the intended credentials before retrying. DELETE stops supplying the saved service-specific login on future image pulls.
It does not revoke the credential at your registry; revoke it there if needed.
Repeating the current PUT or DELETE has the same
desired effect. No idempotency key or replay receipt is used; do not retry an older
rotation after saving a newer one. Mutations reject active deployments and locks.
A response contains configured, server, username,
authentication_verified:false and runtime_changed:false, never a password,
access token or secret reference. configured:true is not proof of registry
access. Saving does not pull, restart or redeploy containers. Use a separate
supported deployment/reapply action to test the exact image with the new login.
Changing the image's registry requires replacing or removing its old login.
DELETE stops supplying this service-specific credential on future pulls; any
other configured registry authentication may still apply.
Create a private JSON file outside your source tree with the shape
{"username":"registry-user","password":"registry-access-token"} and your real
credentials. Set REGISTRY_LOGIN_FILE (Bash), $RegistryLoginFile (PowerShell), or
registryLoginFile (Node.js) to its path. Reuse the credentials and helpers from
the setup guide. Keep this file out of version control and deployment archives.
Linux / macOS - Bash
chmod 600 "$REGISTRY_LOGIN_FILE"
api "$BASE/configuration/registry-login" --request PUT \
--header 'Content-Type: application/json' --data-binary "@$REGISTRY_LOGIN_FILE" | jq .data
api "$BASE/configuration/registry-login" | jq .data
Windows - PowerShell 7.4+
Invoke-Api -Uri "$Base/configuration/registry-login" -Token $ServiceToken `
-Method Put -BodyFile $RegistryLoginFile | ConvertTo-Json -Depth 10
Invoke-Api -Uri "$Base/configuration/registry-login" -Token $ServiceToken |
ConvertTo-Json -Depth 10
Node.js - all operating systems
{
console.log((await api(`${base}/configuration/registry-login`, {
method: 'PUT', bodyFile: registryLoginFile,
})).data);
console.log((await api(`${base}/configuration/registry-login`)).data);
}
Only when you want to remove the service login:
Linux / macOS - Bash
api "$BASE/configuration/registry-login" --request DELETE | jq .data
Windows - PowerShell 7.4+
Invoke-Api -Uri "$Base/configuration/registry-login" -Token $ServiceToken `
-Method Delete | ConvertTo-Json -Depth 10
Node.js - all operating systems
{
console.log((await api(`${base}/configuration/registry-login`, { method: 'DELETE' })).data);
}
Pull failure diagnostics#
Public deployment failures distinguish REGISTRY_ACCESS_DENIED from
IMAGE_PULL_FAILED, with failure_stage: "pull" and an optional exit_code.
The deployment's outer stage remains runtime. Raw command output and
credentials are withheld. An access-denied error can mean an invalid credential
or insufficient repository permissions; configuring a login does not establish
which one failed. An image-download failure prevents that deployment from starting the application.
Configure GitHub deployment through the API#
Use this workflow for an existing custom application, including one previously created or deployed through the API. If needed, provision the application first using the slice API, then issue a service token. Managed services such as WordPress bundles and managed databases keep their managed deployment model.
The service token needs read, deployment:configure, and deploy. The new
deployment:configure grant is opt-in: existing tokens do not receive it automatically.
An administrator can update its permissions, or a slice token with tokens:manage
and those same grants can issue a member service token. applications:manage alone
does not authorize changing deployment sources. Use the token permission editor in
Portal or the management console to add the grant.
Configure the application's runtime environment, storage, ports and readiness using the existing configuration workflow before switching from API upload. Changing source preserves those bindings and the service ID. It does not migrate the service, change its runtime template, deploy, or restart anything. Your image must remain compatible with its ports, health checks and storage mounts. Build infrastructure and capacity are supplied by Budgethost; build allowance and host selection are not token settings.
Managed public-image updates#
Custom applications default to manual updates, including existing applications.
For a public upstream image, send managed_image_updates: true when saving its
type: "image" settings. Enabling requires both deployment:configure and deploy.
GET returns image_update_policy.mode (manual or managed). Saving consent
queues no deployment: it permits image-only refresh during Budgethost
maintenance, not a timed updater.
Private images, GitHub/API builds, customer build repositories and digest pins
are excluded. Registry access is verified anonymously before updating; failed
verification or rate limiting skips the service. Updates follow the selected tag
without changing the image reference. Moving tags such as latest can introduce
major upgrades; select a suitable version track and keep backups. Image or source
changes clear consent and require an explicit opt-in for the new selection.
These examples opt in the current saved image. Review the GET result first;
the service must already use Container image as its deployment source. Existing
registry credentials are preserved. Use false to withdraw consent.
Linux / macOS - Bash
api "$BASE/deployment-settings" > "$STATE/update-policy-before.json"
jq -e '.data.type == "image"' "$STATE/update-policy-before.json"
jq '{revision: .data.revision, type: "image", image: .data.image,
managed_image_updates: true}' "$STATE/update-policy-before.json" > "$STATE/update-policy-request.json"
api -X PUT -H 'Content-Type: application/json' \
--data-binary @"$STATE/update-policy-request.json" "$BASE/deployment-settings"
Windows - PowerShell
$current = Invoke-Api -Uri "$Base/deployment-settings" -Token $ServiceToken
if ($current.data.type -ne 'image') { throw 'Review the deployment source first.' }
$request = @{ revision = $current.data.revision; type = 'image';
image = $current.data.image; managed_image_updates = $true }
Save-Json $request "$State/update-policy-request.json"
Invoke-Api -Uri "$Base/deployment-settings" -Token $ServiceToken -Method Put `
-BodyFile "$State/update-policy-request.json"
Node.js
{
const current = await api(`${base}/deployment-settings`);
if (current.data.type !== 'image') throw new Error('Review the deployment source first.');
await saveJson(`${state}/update-policy-request.json`, {
revision: current.data.revision, type: 'image', image: current.data.image,
managed_image_updates: true,
});
console.log((await api(`${base}/deployment-settings`, {
method: 'PUT', bodyFile: `${state}/update-policy-request.json`,
})).data.image_update_policy);
}
Security advisories are separate from update consent. GET may include a
security_notice with remediation instructions, a deadline and hold_active.
An administrator may suspend a verified high-risk service after notice; this
preserves its data and blocks deployment/restart. An administrator must verify
remediation or mitigation and release the hold. Consent never authorizes forced
replacement of a private or customer-built image.
Read and save the source#
Read GET /v1/deploy/services/{serviceId}/deployment-settings and copy data.revision
into the following PUT request. The revision prevents overwriting concurrent changes.
The same endpoint works for initial setup and later changes.
{
"revision": "COPY_FROM_GET",
"type": "github",
"github": {
"repository_url": "https://github.com/your-organization/your-application",
"ref": "main",
"context_path": ".",
"build_method": "dockerfile",
"port": 3000,
"auto_deploy": { "enabled": true }
}
}
Set context_path to the repository-relative application directory; its Dockerfile
is used for build_method: "dockerfile". Use the port your application actually
listens on. For Node.js command builds, choose "nodejs" and also provide
install_command, build_command (may be empty), and start_command. Optional
node_image selects the Node base image. build_environment supplies non-secret
build variables; omit it to preserve them, or pass {} to clear them.
For a private repository, add repository_token to github using a GitHub credential
that can read that repository. The API stores it without returning it. Omitting the
token keeps it only for the same repository. Changing repositories clears the old
credential binding. clear_repository_token: true removes it; do not also supply a
replacement token. Removing a binding does not revoke the credential at GitHub.
The examples below use the helpers from credentials and shell setup. Edit the example repository and port before running them. Responses can contain a new webhook secret, so keep the state directory private and outside your repository.
Linux / macOS - Bash
api "$BASE/deployment-settings" > "$STATE/deployment-settings-before.json"
jq '{revision: .data.revision, type: "github", github: {
repository_url: "https://github.com/your-organization/your-application",
ref: "main", context_path: ".", build_method: "dockerfile", port: 3000,
auto_deploy: {enabled: true}
}}' "$STATE/deployment-settings-before.json" > "$STATE/deployment-settings-request.json"
# For a private repository, edit the request securely to add github.repository_token.
api -X PUT -H 'Content-Type: application/json' \
--data-binary @"$STATE/deployment-settings-request.json" \
"$BASE/deployment-settings" > "$STATE/deployment-settings-saved.json"
jq '.data | {service_id, type, saved, runtime_changed, webhook_url: .github.auto_deploy.webhook_url}' \
"$STATE/deployment-settings-saved.json"
Windows - PowerShell 7.4+
$current = Invoke-Api -Uri "$Base/deployment-settings" -Token $ServiceToken
$request = @{ revision = $current.data.revision; type = 'github'; github = @{
repository_url = 'https://github.com/your-organization/your-application'
ref = 'main'; context_path = '.'; build_method = 'dockerfile'; port = 3000
auto_deploy = @{ enabled = $true }
} }
# For a private repository, add repository_token to $request.github securely.
Save-Json $request "$State/deployment-settings-request.json"
$saved = Invoke-Api -Uri "$Base/deployment-settings" -Token $ServiceToken -Method Put `
-BodyFile "$State/deployment-settings-request.json"
Save-Json $saved "$State/deployment-settings-saved.json"
$saved.data | Select-Object service_id, type, saved, runtime_changed
Node.js - all operating systems
{
const current = await api(`${base}/deployment-settings`);
const request = { revision: current.data.revision, type: 'github', github: {
repository_url: 'https://github.com/your-organization/your-application',
ref: 'main', context_path: '.', build_method: 'dockerfile', port: 3000,
auto_deploy: { enabled: true },
} };
// For a private repository, add repository_token securely before saving.
await saveJson(`${state}/deployment-settings-request.json`, request);
const saved = await api(`${base}/deployment-settings`, {
method: 'PUT', bodyFile: `${state}/deployment-settings-request.json`,
});
await saveJson(`${state}/deployment-settings-saved.json`, saved);
console.log({ type: saved.data.type, saved: saved.data.saved, runtime_changed: saved.data.runtime_changed });
}
A successful save returns runtime_changed: false. It does not test repository
access or build the application. A private repository's validity is checked during
its first build. On CONFIGURATION_REVIEW_STALE, GET again, review the changes and
submit the new revision. Do not blindly overwrite concurrent edits.
Connect GitHub release events#
The API configures the receiving side. It does not create a webhook in your GitHub account. In that repository's Settings > Webhooks, add a webhook using:
- Payload URL:
data.github.auto_deploy.webhook_urlfrom the saved response. - Content type:
application/json. - Secret:
data.webhook_secretfrom the saved response. - Events: releases. Deployment responds to
release.published, using the release's tag. - Active: enabled; retain SSL verification.
For fully automated setup, call GitHub's Create a repository webhook API with a GitHub credential granting Webhooks: write on that repository. Use that credential only for the GitHub request; the Budgethost service token cannot authorize it.
POST https://api.github.com/repos/OWNER/REPO/hooks
Authorization: Bearer GITHUB_WEBHOOK_ADMIN_TOKEN
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10
Content-Type: application/json
{
"name": "web",
"active": true,
"events": ["release"],
"config": {
"url": "COPY_data.github.auto_deploy.webhook_url",
"content_type": "json",
"secret": "COPY_data.webhook_secret",
"insecure_ssl": "0"
}
}
Replace the placeholders from the saved response and retain GitHub's returned hook
ID. Before retrying an uncertain creation request, list repository hooks and check
for the matching URL. For rotation, update that hook's configuration with the new
secret rather than creating a second hook. The cloning credential supplied as
repository_token does not need webhook administration access.
The branch/ref in the settings is used for manual builds. A push by itself does not
trigger this release-based workflow. Publish a release to deploy its tag automatically.
An accepted release updates the stored ref to that tag; read the settings before your
next manual build. For a newly provisioned application, complete the manual deployment
below once before relying on release webhooks.
Enabling auto_deploy requires both deployment:configure and deploy.
The webhook secret appears once, only when created or rotated. GET shows only
whether it is configured. If you lose the response or need to rotate it, GET the current
revision and PUT the full GitHub settings with auto_deploy.rotate_webhook_secret: true.
Update the GitHub webhook with the replacement secret. A repository change creates a
new webhook secret when automatic deployment is enabled; remove the old repository's
webhook. Revoking the service API token does not remove an already configured GitHub
webhook; disable auto_deploy explicitly when retiring that trigger.
Build and deploy manually, then poll#
To deploy the configured image or GitHub ref explicitly, POST
/deployment-settings/deployments with the saved revision and a stable
X-Idempotency-Key. This action is separate from saving and requires deploy.
It uses the same manual build limits as Portal.
Linux / macOS - Bash
jq '{revision: .data.revision}' "$STATE/deployment-settings-saved.json" > "$STATE/source-deploy-request.json"
if [ ! -s "$STATE/source-deploy.key" ]; then uuid > "$STATE/source-deploy.key"; fi
api -X POST -H 'Content-Type: application/json' \
-H "X-Idempotency-Key: $(cat "$STATE/source-deploy.key")" \
--data-binary @"$STATE/source-deploy-request.json" \
"$BASE/deployment-settings/deployments" > "$STATE/source-deploy.json"
OPERATION_ID=$(jq -er '.data.id' "$STATE/source-deploy.json")
api "$BASE/deployment-settings/deployments/$OPERATION_ID" | jq .data
Windows - PowerShell 7.4+
$saved = Read-Json "$State/deployment-settings-saved.json"
Save-Json @{ revision = $saved.data.revision } "$State/source-deploy-request.json"
New-Key "$State/source-deploy.key"
$operation = Invoke-Api -Uri "$Base/deployment-settings/deployments" -Token $ServiceToken -Method Post `
-BodyFile "$State/source-deploy-request.json" -KeyFile "$State/source-deploy.key"
Save-Json $operation "$State/source-deploy.json"
Invoke-Api -Uri "$Base/deployment-settings/deployments/$($operation.data.id)" -Token $ServiceToken
Node.js - all operating systems
{
const saved = JSON.parse(await readFile(`${state}/deployment-settings-saved.json`, 'utf8'));
await saveJson(`${state}/source-deploy-request.json`, { revision: saved.data.revision });
await newKey(`${state}/source-deploy.key`);
const operation = await api(`${base}/deployment-settings/deployments`, {
method: 'POST', bodyFile: `${state}/source-deploy-request.json`, keyFile: `${state}/source-deploy.key`,
});
await saveJson(`${state}/source-deploy.json`, operation);
console.log((await api(`${base}/deployment-settings/deployments/${operation.data.id}`)).data);
}
Repeat the GET every few seconds until succeeded or failed. running and
awaiting_follow_up are nonterminal; finishing a build alone is not a successful
deployment. steps contains sanitized work statuses, not credentials or raw build
payloads. A 202 response only acknowledges admission. Keep the same key and revision
when retrying an uncertain POST. A new intended deployment needs a new key and a fresh
reviewed revision. There is no automatic rollback.
Change or retire a source#
GET the latest settings, then PUT the appropriate source:
{"revision":"COPY_FROM_GET","type":"image","image":"ghcr.io/your-organization/app:v2"}
For private images, include registry_login: {"username":"...","password":"..."}.
Credentials are bound to the registry derived from the image; use registry_login: null
to clear them. Save first, then use the explicit configured-source deployment endpoint.
{"revision":"COPY_FROM_GET","type":"api"}
Selecting API upload disables GitHub automatic deployment and enables the existing artifact upload/start workflow in this guide. Existing tokens are not revoked by a source switch. API artifact deployment and runtime configuration writes are blocked while an explicitly selected source is image or GitHub. To change those runtime settings, select API upload, use the configuration workflow, then reselect your source and review its deployment settings. Ordinary settings saves never start a deployment.
To keep GitHub while stopping automatic releases, PUT the full GitHub settings with
auto_deploy.enabled: false. To change its repository, branch, directory, commands or
build method, PUT the updated full GitHub settings with the latest revision.