Before you start
Deploy runs a container image as a service with a public HTTPS address. Everything on this page can be done by a script or an AI agent through the Management API. Three account steps need a person in a browser.
- The image must be built for linux/amd64 and stored in a registry: a public registry, a private Docker Hub or GitHub Container Registry repository, or your own ACDN registry.
- The account needs a verified email address, a balance above zero, and an approved identity verification. GET /api/user/deploy/requirements reports which of these is missing and returns the page where the account owner completes it.
- One application runs up to 3 instances at once. A release of a service without volumes temporarily adds one instance, so an application that contains such a service can be configured with up to 2 instances.
- Usage is charged from the account balance. Prices are listed under Billing at the end of this page.
When a request returns status 403, call GET /api/user/deploy/requirements and show the message and action_url of the unmet requirement to the account owner. Only that person can resolve it; repeating the request does not help.
Connect acdn-agent.py
acdn-agent.py is a single-file helper that obtains an OAuth token through the device flow and passes it to curl. The authorize command prints a link and a code and waits; the account owner opens the link, signs in, and approves access. The token is saved in tmp/acdn-agent/ under the current directory and refreshed automatically.
curl -fsSLO https://acdn.uz/tools/acdn-agent.py
python3 acdn-agent.py authorize --no-browser
# what the account still needs, available regions, limits, prices
python3 acdn-agent.py call /api/user/deploy/requirements
Arguments after "--" are passed to curl. The examples use --json, which needs curl 7.82 or newer; with older versions send --header "Content-Type: application/json" --data instead. A failed request prints the JSON error body and exits with a non-zero status. Messages are returned in the language of the account; add --header "Accept-Language: en" after "--" to receive English.
Create an application
An application groups the services, volumes, and endpoints of one project in one region and one private network. Keep the returned id. The application is prepared in the background, normally within seconds; wait until its status is ready before you deploy.
python3 acdn-agent.py call /api/user/deploy/applications -- \
--json '{"name":"Chat backend","region":"UZ"}'
# repeat until "status":"ready"
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID
- Poll every few seconds. Preparation gives up after 5 minutes with status failed; then send POST /api/user/deploy/applications/prepare/APPLICATION_ID to try again.
- Volumes, services, and endpoints can be created in any application status except while it is being deleted. A deployment is accepted only when the status is ready; otherwise the request returns 409.
- Do not repeat the create request after a timeout without listing applications first: every accepted request creates another application.
Add a volume and a service
Create the volume first, then the service that mounts it. endpoint_ports requests a public HTTPS address for each listed container port; the generated hostname is returned in endpoints.
python3 acdn-agent.py call /api/user/deploy/volumes -- \
--json '{"deploy_application_id":"APPLICATION_ID","name":"data","size_gb":1}'
python3 acdn-agent.py call /api/user/deploy/services -- --json '{
"deploy_application_id": "APPLICATION_ID",
"name": "web",
"image": "ghcr.io/example/chat:1.4.2",
"http_port": 8080,
"health_check_path": "/healthz",
"replicas": 1,
"volume_mounts": [{"deploy_volume_id": "VOLUME_ID", "mount_path": "/data"}],
"environment_variables": [
{"name": "LOG_LEVEL", "value": "info", "is_secret": false},
{"name": "SESSION_SECRET", "value": "change-me", "is_secret": true}
],
"endpoint_ports": [8080]
}'
- http_port is the port your process listens on. Listen on 0.0.0.0, not only on 127.0.0.1. No PORT variable is provided.
- health_check_path must answer with a status from 200 to 399 once the service can take traffic. The check is sent straight to the instance, not through the public address.
- volume_mounts is required; send an empty array for a service without volumes.
- A service that keeps a database file on a volume must use replicas 1: every instance gets its own separate disk.
- Secrets are write-only. They reach the container as environment variables and are never returned by the API.
- Nothing runs yet: the service is created with status draft.
Deploy and wait for the result
The deploy request returns immediately with the new deployment in latest_deployment. Remember its id, then poll about every 5 seconds until that deployment reaches active, failed, or cancelled. A deployment has 10 minutes to become ready.
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST
# status of the service and of its latest deployment
python3 acdn-agent.py call /api/user/deploy/services/SERVICE_ID
# recent deployments with their timelines; find yours by id
python3 acdn-agent.py call /api/user/deploy/services/deployments/SERVICE_ID
- Success: your deployment has status active and the service has status running. The service answers at endpoints[].url over HTTPS.
- Failure: failure of your deployment gives the reason and progress lists what happened. Read the logs before you change anything, because they disappear when the instance is replaced.
- After a failed deployment the platform may add a newer deployment with action recover that restores the previous release. The service then shows running again although your deployment failed, so always check the deployment with the id you started.
- A new hostname is published in DNS when the endpoint is created. Allow a few minutes before it resolves everywhere.
Read status and logs
# health-check state of every instance
python3 acdn-agent.py call /api/user/deploy/services/readiness/SERVICE_ID
# last 1000 lines of the first instance; the response lists all instances
python3 acdn-agent.py call /api/user/deploy/services/logs/SERVICE_ID
# output of the run before the last restart of one instance
python3 acdn-agent.py call '/api/user/deploy/services/logs/SERVICE_ID?instance=INSTANCE_ID&instance_uid=INSTANCE_UID&previous=1'
- Logs are the standard output and standard error of the container, with a timestamp before each line.
- Only recent output of instances that still exist is available. Read the logs of a failed deployment promptly.
- INSTANCE_ID and INSTANCE_UID come from a previous logs response: instances[].id lists the instances, and instance_uid belongs to the instance whose text was returned.
- A service with no instances returns an empty text and instance null.
Redeploy, roll back, stop
To release a new image, push it and deploy again: the tag is resolved to its digest at every deployment. To change settings, update the service or its environment first, then deploy. Saved changes have no effect until the next deployment.
# replace the environment, then release it
python3 acdn-agent.py call /api/user/deploy/services/environment/SERVICE_ID -- --request PUT --json '{
"environment_variables": [
{"name": "LOG_LEVEL", "value": "debug", "is_secret": false},
{"name": "SESSION_SECRET", "value": "", "is_secret": true}
]
}'
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST
# return to an earlier release: choose a deployment with "can_rollback": true
python3 acdn-agent.py call /api/user/deploy/services/rollback/SERVICE_ID -- \
--json '{"source_deployment_id":"DEPLOYMENT_ID"}'
# start fresh instances of the current release, or stop the service
python3 acdn-agent.py call /api/user/deploy/services/restart/SERVICE_ID -- --request POST
python3 acdn-agent.py call /api/user/deploy/services/stop/SERVICE_ID -- --request POST
# remove everything, including volume data
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID -- --request DELETE
- The environment request replaces the whole list. An existing secret listed with an empty value keeps its value; a variable that is not listed is removed.
- Rollback restores the image, configuration, environment, and secrets of that release. Data on volumes is not rolled back.
- A rollback does not change the saved configuration. The next deploy applies the saved configuration again, so after rolling back also save the settings you want to keep.
- A deployment can be used for rollback only if it was active at some time; any other id returns 404.
- Deploy, stop, restart, and rollback together accept 6 requests per minute, and only one deployment per service can be in progress (status 409 otherwise). Every request counts toward the limit, including rejected ones.
Billing
- CPU: $0.02 per CPU-hour. Only processor time actually consumed is counted, so an idle service costs almost nothing for CPU.
- Memory: $0.005 per GiB-hour of memory in use, measured as the working memory of the instance including actively used file cache.
- Volumes: $0.10 per GiB-month of allocated size for every disk, whether or not it is full and whether or not the service is running. A volume costs nothing until a service that mounts it has been deployed (allocated_bytes is 0 until then).
- Outgoing traffic: $0.05 per GiB sent by your instances. Traffic served on a custom domain through a CDN pull zone is additionally billed as CDN delivery at the price of the pull zone tier.
- There is no free allowance, no minimum charge, and no charge for the application or the endpoint itself.
- Usage is recorded about every 30 minutes and deducted from the account balance. The API returns the current month's usage with every service, volume, and application.
- Creating an application requires a balance above zero. When a negative balance is detected, existing Deploy services get a three-day (72-hour) payment grace period. They keep running, and deployments and restarts remain available during this period. Usage continues to be charged.
- Emails announce the grace period and its exact deadline, remind you 24 hours before expiry, and confirm suspension after services have stopped. GET /api/user/deploy/requirements returns negative_balance_grace_ends_at and deployments_blocked. Balance checks run every minute; the deadline is null until a negative balance is detected.
- If the balance is still negative at the deadline, all Deploy workloads, including personal registries, are gracefully stopped. Deploy, restart and rollback return 402 until the debt is covered. Restoring the balance to zero or above clears the countdown; a partial payment that leaves it negative does not extend the deadline.
- After the balance reaches zero or above, you receive a confirmation email and services suspended for unpaid balance restart automatically from their previous release. Recovery is checked every minute and waits for any shutdown already in progress. A suspended personal registry starts before services that need its images. Manually stopped services stay stopped. Settings and stored data are retained; allocated volumes and registry Storage continue to be billed until deleted.
Exact request and response fields, limits, and error responses are in the Management API reference.