Service lifecycle: build, deploy, roll back

Follow an app on aidrop.it from its first build to a rollback: get the code in, build, open the address, fix failures, and the steps only a person can do.

This page follows your app from its first build to a rollback, and lists the few steps only a person can do. Your agent does everything else through the aidrop.it MCP server, and each step below names the tool it uses.

A Service is one deployable piece of a Project: a frontend, a backend or a worker. It has one repository, one runtime and one address. It also keeps an audit trail of what was done to it, so the next person or agent can continue without digging through old chats.

The Project is the product those pieces make up. projects_list and project_create are where one starts. To plan a product with several Services, read how an agent builds a full Project. For the same lifecycle told in plain words, see build and host a Telegram bot with Claude Code or keep a Discord bot online 24/7.

What does a person still have to do?

These are the points where a human decision is the product, not a limitation to work around:

Installing the GitHub App. This is a browser step on GitHub, and an agent cannot do it.
Handing over secret values, such as API keys. The agent asks for each one when the code needs it, and the person gives it in the chat once. The agent stores it with project_secret_set and must never show it again or write it into code, the repository or a log. No tool ever reads a value back, and the dashboard lists the names only.
Agreeing to the first deploy, because it puts the app on the open internet.
Confirming that an application is paused, that a billed database, cache or queue is created or deleted, and that a Project or Service is deleted. Most of these tools refuse until they are called with confirmed. service_delete does not: it takes effect at once, so the agent must ask the person before calling it.

1. A Service is made by building one

There is no create call. service_build makes the Service: name the Project it belongs to and a name for the deployable, and the first call creates it. A later call with the same project_id and name builds that same Service again, so repeating the call never leaves a second one behind. Pass service_id instead once you have one.

A Service has no shape until code is pushed to it. Nothing is read out of the repository to decide what it is. How it builds and runs is what the agent passes to that first build, because the agent wrote or read the code and aidrop.it did not.

The repository is the Team’s, not the Service’s. It exists before any Service builds from it, and one repository may back several Services. The first service_build links one to the Service for good. Find it with repositories_list or make one with repository_create.

The runtime settings are recorded by the build, not before it. These are the port the application listens on, its health path, its size, how the image is built and the names of the secret values it reads. All of them arrive with the first service_build and are kept with the commit they were built for.

Its address answers from that first successful deploy, and it is open to the internet. See The address.

If the repository might already back an aidrop.it Service, read repositories_list before creating a duplicate: it says which Services build from each repository.

2. Get the code into a repository

There are two paths, depending on where the code lives. Either way, the first service_build links the repository to the Service; there is no separate step.

GitHub. A person installs the aidrop.it GitHub App for the account. The repository then appears in repositories_list, and aidrop.it syncs it on push.

Nothing to bring yet, or code only on a local disk. aidrop.it hosts the repository in the Team’s own Git service:

An agent with a local git client calls repository_create with a name. That makes an empty repository and returns a push credential for the agent’s own git. repository_get returns the same credential again for a repository that already exists.
An agent with no shell at all, a chat-only client, has no way to get code in. aidrop.it accepts no uploaded archive and never commits on your behalf. Such a session can read and build what is already pushed, but it cannot start a codebase. Push from a terminal, or use an existing GitHub repository.

Which branch builds is stated, not assumed. service_get shows it as the branch of its repository. A repository aidrop.it created for you uses main and has no other. An imported repository keeps the default branch it already had. Only that branch is built: a push to any other is never deployed. Pass branch to service_build to build, and from then on follow, another one.

3. Build

service_build builds the newest commit of the tracked branch. When the build succeeds, it deploys the image to the Service’s address. It is one call; the build is queued and takes minutes. That address is on the open internet from this first deploy. The first call links the repository and records the runtime settings:

Setting	What it decides	Default
`repository_ref`	The repository this Service builds from, from `repositories_list` or `repository_create`; linked for good.	none: required the first time, not accepted differently afterwards
`container_port`	The port the application listens on inside the container.	none: required the first time
`health_path`	The HTTP path that answers once the application is up.	`/`
`resource_class`	The size: how much CPU and memory the app may use. See sizes.	the smallest size the plan includes
`runtime_kind`	How the application serves traffic.	`container`
`build_type`	`nixpacks` (an open-source builder) works out the build from the repository and needs no Dockerfile; `dockerfile` builds your own.	`nixpacks`; aidrop.it does not inspect the code to choose
`build_dockerfile_path`	Which Dockerfile a `dockerfile` build reads, with its file name, relative to the repository root, such as `build/Dockerfile.api`. The root is the build context whatever the path.	none: required with `build_type: dockerfile`, refused with `nixpacks`
`required_secret_names`	The names of the Project’s secret values this Service reads at run time. Exactly these reach its environment, and a Project value it does not name never does.	none

Every later call keeps these settings unless one is passed again.

A build is refused up front, before a run is opened, for the reasons it would otherwise stop on:

a repository the Team does not have, or one the GitHub App cannot read;
a named secret value the Project does not hold;
a size the plan does not include;
hosting paused.

Secret values are stored on the Project, only by an agent with project_secret_set. No tool ever answers one back. The dashboard’s Project Secrets page lists the names and when each was written, never the values.

The settings cannot carry arbitrary Docker options, Compose files, host configuration, volume paths, commands or secret values. That boundary is what keeps aidrop.it’s managed runtime from becoming general-purpose hosting.

4. Read how it went, fix, build again

service_get is the one call to poll:

Its build is the furthest point reached (created → built → checked → deployed → addressed), with a status of running, succeeded, stopped or superseded.
Its next_step names the one call that follows: wait, read the log, fix and push, or start the application.
Its deployment is the latest attempt. application.deployment_id, application.commit_sha and application.tag identify what is actually serving the address. A later failed attempt does not take down an earlier working version.

service_logs is the latest build’s log, with credentials hidden and its length bounded. A failed build says why there. The agent reads it, changes the code, pushes, and calls service_build again. If a run stopped before a build was queued, for example because no builder was free or no settings were given, the log answers that stop reason instead.

Two things cause most failed first builds: nothing listening on the PORT the runtime hands the container, and an image that exits before it serves. Read the runtime_envelope from service_get before spending a build. It is the set of limits and rules your code has to fit:

its resources name the port;
its runtime_rules say what a container may and may not do here;
its dockerfile, for a named runtime kind, is a Dockerfile that binds that port and runs under those rules.

5. The address

There is no separate production, and no lock. A Service has one address, and deploying is what opens it. Anyone holding the URL can reach the application, and nobody needs an aidrop.it account. Tell the user what a deploy does before the first build, not after it.

service_stop pauses the application: the container stops and the address stops answering. service_start resumes it.

Every build keeps its image under a tag, the first twelve characters of its commit, and the registry keeps every image a build pushed. service_tags_list lists them. service_start with a tag starts that image without rebuilding, under the settings that build ran with. A rollback is that call with an older tag. Nothing is promoted and nothing is rebuilt: the image that ran is the image that runs. For the reader-facing side of this, and of the other layers that undo an agent’s mistake, see how to stop your AI agent from deleting your project.

aidrop.it runs no analyser over your repository. A build is the only thing that says whether a version works.

service_build is refused, by name, for four reasons that are not about the code:

the Team’s plan includes no hosting;
the deploy would use more of the plan’s shared memory and CPU than the plan includes. The message carries the numbers: stop another application, choose a smaller size or change plan;
aidrop.it has suspended the Team;
managed hosting is paused for the whole platform, which is an aidrop.it switch and nothing on your side.

The image builder can be switched off on its own, and says so.

A successful build is never treated as proof that an address is reachable. After a short start-up window, a container that still answers nothing on its port, or answers with a server error (5xx) on its health path, is a failed deployment. A brief gap while a replacement container starts is still in progress during that window.

6. Keep it continuable

What the next person or agent needs to continue this Service lives in two places. The first is the repository: CLAUDE.md and similar instruction files, the changelog and the commit history. The second is the Service’s audit trail, which records every tool call and every build.

Files that look like credentials are left out of the copy of the repository that aidrop.it indexes, and nothing keeps a list of them afterwards.