aidrop.itDocs

Build a Project with an AI agent

The full path for an AI agent building a product on aidrop.it: plan the frontend, backend and database, push the code, build, verify and hand over.

Updated

Let your agent build this

Copy one prompt and paste it into Claude Code, Codex or Cursor. Your agent builds what this page describes and puts it online on aidrop.it. Fill in the parts in brackets before you send it.

See the prompt
Build this product and run it on aidrop.it: [DESCRIBE THE PRODUCT, WHO USES IT AND WHAT IT MUST DO].

Before writing any code, list the aidrop.it Projects, Services and repositories that already exist, and propose the shape: which parts deploy as separate Services and whether it needs a database. Ask me before anything that costs money and before using my own domain. Secrets: ask me for each value the code needs, store each one with project_secret_set under a clear name, and list those names in required_secret_names when you build. Never print a value back to me, and never write one into code, the repository, a commit or a log.

Then write the code, push it to a repository on aidrop.it, build each Service, and check that every address answers. If a build fails, read the log, fix the cause and build again. Finish with a short note in the repository of what runs where and what to do next.

This task comes from the aidrop.it guide "Build a Project with an AI agent": https://docs.aidrop.it/build-a-project. Read that page if you need more detail; it says what to ask me for, what it costs and what will not work.
Use the aidrop.it MCP tools (server: https://aidrop.it/mcp). If you do not have them, stop and tell me to connect them first, as described at https://docs.aidrop.it/quickstart#1-connect-your-agent.
On this page

This is the checklist your agent follows to go from an idea, or an existing repository, to a running app with a frontend, backend and database. Your agent does the work and makes every call. You decide what costs money and which domain to use, and you hand over each secret value once, when the agent asks for it.

A Project is the product. A Service is one deployable part inside it: a web application, an API, a worker, or another container with its own build, settings and aidrop.it address. A Project may contain several Services. Its secrets and its database, cache or queue stay inside that Project. Every session starts by reading projects_list, services_list and repositories_list, so the agent knows what already exists before it makes anything new.

1. Choose the shape before writing code

Decide which parts deploy independently. A browser application, an API and a background worker are separate Services even when they live in one repository: each runs one container, listens on one port, and has its own build, settings and address. They can still share a Project, its secrets and its database.

Product shape Project and Service shape
A landing page or a small HTTP application One Project, one Service
Browser application plus API One Project, two Services
Monorepo with an API and a worker One Project, one Service for each process that must run independently
Separate customer products One Project per product; nothing in a Project is shared with another

Worked examples of these shapes: put a landing page online is one Service; add an AI chatbot to your website is one small Service that keeps your AI key off the page; a Telegram bot built with Claude Code is one Service that runs around the clock; and self-hosting n8n is one Service plus a PostgreSQL database.

If the application keeps records, sessions, queued work, or anything that must survive a restart, plan its database, cache or queue before writing files. An application has no persistent disk: its filesystem is read-only, and only /tmp, /run and /var/tmp are writable scratch space that is lost on restart. Do not use a file as a database, queue, upload store, or cache that must survive.

Before choosing a stack, read runtime templates and plan limits. It lists the sizes (how much memory and CPU each Service gets) and the databases, caches and queues the Team’s plan includes. Every Service in a Project shares the plan’s memory and CPU, and a database, cache or queue does not count against the plan’s number of Projects. For an existing Service, service_get returns a runtime_envelope: the rules that Service’s container runs under.

An application can reach the public internet only through the supplied HTTP proxy on ports 80 and 443. Use proxy-aware HTTPS clients for external APIs; a public database’s native port or SMTP is not reachable.

2. Create or select the Project

Use an existing Project when the work is another deployable part of the same product. Otherwise call project_create with the product’s name and description. The result’s project_id is the boundary for everything after it: Service builds, Project secrets, and databases use that id.

Do not create a Service as a separate preparatory step. The first service_build creates it, links its repository, and records its first runtime settings in one call.

3. Put the code in a repository

There are two ways in:

  1. Existing GitHub code. A person installs the aidrop.it GitHub App on the GitHub account that owns the repository. The repository then appears in repositories_list; use its repository_ref. The agent cannot install the App or supply GitHub credentials. Deploy an existing GitHub repository covers this route on its own.
  2. New code or a local working tree. Call repository_create with the selected project_id. It returns an empty Team repository, a clone URL and a push credential. An agent with a local shell writes the code, commits it, and pushes it with git. A chat-only client cannot move local files or push an archive; it can only build code that is already in a repository.

Before linking a repository, read repositories_list. It shows whether the repository already backs a Service in the selected Project. Reuse that Service when it is the same deployable; add a second Service only when the repository really contains another process that must run separately.

The tracked branch is explicit. A Team repository starts on main; a GitHub repository starts on its existing default branch. Pass branch to the first build when another branch should be deployed, then push later changes to that branch.

4. Decide how the Service runs

aidrop.it works out how to build the image (with nixpacks, unless you name a Dockerfile), but it never works out how the app runs: the port, the size and the health path. The agent reads the code and passes those answers to service_build:

Setting Decision
container_port Required on the first build. The port the process listens on inside the container. The application must bind the PORT it receives.
health_path The HTTP path that must answer successfully after start-up; / by default.
resource_class The size: how much CPU and memory the Service gets. If omitted, the smallest size in the plan is used.
runtime_kind container by default, or a named runtime whose starter files and rules are returned in runtime_envelope.
build_type nixpacks by default, or dockerfile.
build_dockerfile_path Required with build_type: dockerfile; a path such as Dockerfile or build/Dockerfile.api, relative to the repository root.
required_secret_names Exact names of the Project secrets this Service receives at run time.

Nixpacks is an open-source build tool that reads a repository and writes a Dockerfile for it, so a repository without one still builds. That Dockerfile is a guess. For a repeatable build, commit a Dockerfile and pass both build_type: dockerfile and build_dockerfile_path. A Dockerfile that is present but not named is never used. The repository root is the build context, even when the Dockerfile lives in a subdirectory.

5. Add a database and secrets only when the code needs them

Call shared_resources_list for the current Project before creating a database, cache or queue. Each one belongs to one Project and is available only to the Services in it.

If PostgreSQL already exists, create another database in that instance with shared_resource_create and its parent_resource_id. That database does not need confirmed, because the instance is what is billed. Name the service_id that should use it in the call, or attach it afterwards with shared_resource_update. Do not create a second PostgreSQL instance. If none exists, creating the first one requires the user’s explicit confirmed decision because it costs money. PostgreSQL needs the Pro plan or higher; the 7-day trial includes one database.

Attaching a database returns its connection string and environment-variable name, but does not save either one. Store the returned connection string with project_secret_set for the same Project, then include that variable in the Service’s required_secret_names on the next build. A Service receives only the secrets it names; another Project’s secrets and databases never reach it.

A third-party key, such as a payment or mail API key, follows the same rule: ask the person for it when the code needs it, store it with project_secret_set, and name it in required_secret_names. Only the agent stores a value; the dashboard’s Project Secrets page lists the names and when each was written, never the values. Stored secrets are never returned by a tool, so never repeat one back or write it into code, a commit or a log.

6. Build and wait for the result

The first build creates the Service and links the repository. A typical first call has this shape:

service_build(
  project_id: "…",
  name: "web",
  repository_ref: "team/product",
  container_port: 3000,
  health_path: "/health",
  build_type: "dockerfile",
  build_dockerfile_path: "Dockerfile",
  required_secret_names: ["DATABASE_URL"]
)

Use the values that fit the actual repository; the example is not a template to copy unchanged. Later builds pass service_id and keep the previous settings unless a setting is supplied again.

The build is queued and takes minutes. Poll service_get until the build succeeds or stops; its next_step says what follows from the current state. If it stops, read service_logs, fix the code or settings, commit and push to the tracked branch, then call service_build again. A successful image build is not a successful deployment: the application must also answer on its configured port and health path.

7. Verify, operate, and leave a clear next step

The first successful deployment creates the Service address. It is public on the internet immediately; add sign-in to the application itself when visitors must log in. service_get returns the address and the current build, repository, runtime settings and runtime_envelope.

For a custom domain, call service_domain_add, create the one DNS record it returns, then call service_domain_verify with the returned domain_id. Creating the DNS record is the person’s step; do not guess a target from another Service. A custom domain needs the Pro plan ($20/month) or higher; see aidrop.it pricing.

Every successful build has an image tag. service_tags_list lists the tags, and service_start with an earlier tag rolls the code back without rebuilding. Poll service_get until that image reports running. A rollback does not roll the database schema back, so make migrations forward-compatible. service_stop pauses an application; service_start without a tag resumes its current image. Before handing the app over, have the person read how to stop your AI agent from deleting your project: it sets the agent’s role and the safety rules future sessions follow.

Keep the hand-over notes with the code: document local commands, required secrets by name, migrations, Service boundaries and deployment decisions in the repository’s CLAUDE.md or equivalent. The next agent starts by reading the repository and the current Project, Service and build records rather than guessing from an earlier chat.