Service lifecycle

A Service is one deployable piece of a Project — a frontend, a backend, a worker: one repository, one runtime, one address, and the audit trail of what was done to it, kept together so the next person or assistant can continue the work without reconstructing it from old chats. The Project is the product those pieces make up; projects_list and project_create are where one starts.

This page is the map. Each step links to the tool that performs 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. What it is, and how it builds and runs, is what the agent passes to that first build — because the agent wrote or read the code and Aidrop did not. A starter was chosen from a description until 2026-09-01, sixteen monorepo shapes each implying a runtime contract; the whole registry is gone.

The repository is the Team’s, not the Service’s. It exists before any Service builds from it, one repository may back several Services, and 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. The port the application listens on, its health path, its size, how the image is built and the names of the values it reads all arrive with the first service_build — a runtime profile is bound to a revision by its table’s contract.

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 Service, read repositories_list before creating a duplicate: it says which Services build from each repository.

2. Get the code into a repository

Two paths, depending on where the code lives. Either way the repository is linked to the Service by the first service_build, not by a step of its own.

GitHub. A person installs the Aidrop GitHub App for the account — this is a browser step and an agent cannot do it. The repository then appears in repositories_list, and Aidrop syncs it on push.

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

• An agent with a local git client calls repository_create with a name, which makes an empty repository and returns a push credential for the agent’s own git to use; 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 path to get code in. Aidrop accepts no uploaded archive and never commits on your behalf, so such a session can read and remember but cannot start a codebase. Push from a terminal, or use an existing GitHub repository.

Which branch builds is stated, not assumed. service_get’s repository carries branch. A repository Aidrop created for you is main and has no other; an imported repository keeps the default it already had, and 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 head of the tracked branch and, when the build succeeds, deploys the image to the Service’s address — one call, queued, minutes long. 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 bounded CPU/memory envelope — see sizes.	the smallest size the plan includes
runtime_kind	How the application serves traffic.	container
build_type	nixpacks infers the build from the repository and needs no Dockerfile; dockerfile builds your own.	nixpacks — Aidrop 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 — 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 values this Service reads at run time — the selection as well as the requirement: exactly these reach its environment, and a Project value it does not name never does.	none

Every later call keeps them 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 the App cannot read, a named value the Project does not hold, a size the plan does not include, hosting paused. Values are stored on the Project — by a person in the dashboard, or by an agent with project_secret_set — and no tool ever answers one back.

The settings cannot carry arbitrary Docker options, Compose, host configuration, volume paths, commands, or secret values — that boundary is what keeps 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, and 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, while application.deployment_id, application.commit_sha and application.tag identify what is actually serving the address. A later failed attempt does not make an earlier active revision disappear.

service_logs is the latest build’s log, credential-redacted and bounded. A build that failed says why there; the agent reads it, changes the code, pushes, and calls service_build again. A run that stopped before a build was queued — no builder available, no settings — answers its stop reason instead.

Two things account for most first builds that fail: nothing listening on the PORT the runtime hands the container, and an image that exits before it serves. The runtime_envelope service_get answers is what settles both before a build is spent: its resources name the port, its runtime_rules say what a container may and may not do here, and its dockerfile — for a named runtime kind — is one 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.

It was closed by default until 2026-09-09 — a preview password, a forward-auth gateway, and a visibility argument to move between the two. All of it is gone. Say what a deploy does before the first build, not after it.

service_stop pauses the application — the container stops and the address stops answering — and 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.

Promotion into a second application, behind a human review, was how this worked until 2026-08-23. It asked somebody building a landing page to learn staging and an approval queue in order to show their work to a client, which is the wrong price for the thing they actually wanted. The five separate calls that remained after it — index, preflight, profile, address, deploy — became one service_build on 2026-09-02, and preflight itself went on 2026-09-09: aidrop.it runs no analyser over a customer’s repository, and a build is the only thing that says whether a revision works.

6. Keep it continuable

What the next person or assistant needs to continue this Service lives in the repository — CLAUDE.md and its equivalents, the changelog, the commit history — and in the Service’s audit trail, which records every tool call and every build.

Knowledge records, work instructions, secret-pattern findings and the production publish review were a separate store on the Service until 2026-09-05, when they were removed: what a Service is worked on by is what its repository says, where the next session reads it anyway. Credential-shaped files are still withheld from the indexed snapshot; what changed is that nothing keeps a list of them afterwards.

What only a person can do

Not a limitation to work around — these are the points where a human decision is the product:

• Installing the GitHub App.
• Entering runtime values. An agent can learn a value is required; it can never read or write it.
• Confirming that an address is made public, that an application is paused, that a billed service is created or deleted, and that a Project or Service is archived.