# Quickstart: deploy from your AI coding agent
Source: https://docs.aidrop.it/quickstart
> Deploy from Claude Code, Codex or Cursor in one session: connect the aidrop.it MCP server, push your code and get a live HTTPS address in minutes.
aidrop.it runs the apps your AI coding agent builds. Connect Claude Code, Codex or Cursor to `https://aidrop.it/mcp`, ask it to build, and it pushes the code and gives you a public HTTPS address in the same session.
You need an aidrop.it account: [start free](https://app.aidrop.it/register) with a 7-day trial and no card. The trial covers one app and one PostgreSQL database.
For a single page you can edit directly in the browser, try [Page Builder](/page-builder). It saves drafts through the same aidrop account.
## 1. Connect your agent
Sign up and name your Team on the first screen. Then add aidrop.it to your agent with the lines below. There is no API key to create or paste. The agent's first call opens a consent screen in your browser, where you allow it to read and change your Services (the permissions, or scopes, are called `service:read` and `service:write`). You can revoke that access any time from **Management → Connected apps**.
**Claude Code:**
```bash
claude plugin marketplace add aidropit/plugins
claude plugin install aidropit@aidropit
```
Then start `claude`, run `/mcp`, pick **aidropit** and sign in.
**Codex CLI** (the desktop app and Codex in ChatGPT read the same configuration):
```bash
codex plugin marketplace add aidropit/plugins --sparse .agents/plugins
codex plugin add aidropit@aidropit
```
Sign in when the install prompts you, or with `codex mcp login aidropit`.
**Cursor, Claude, or any other client that speaks MCP:**
```json
{ "mcpServers": { "aidrop": { "url": "https://aidrop.it/mcp" } } }
```
New to the term? [What an MCP server is](/playbooks/what-is-an-mcp-server) explains in plain words how an agent connects to a service like this one.
**Two words you will see.** A **Project** is your product: a website, a bot, an app. A **Service** is one running piece of it, such as the website, its API or a background worker, each with its own code, address and history. A database, cache or queue also lives inside the Project. It does not count against the number of Projects your plan allows, and everything in a Project shares the plan's memory and CPU.
**Already have code on GitHub?** Skip steps 2 to 4 and [deploy an existing GitHub repository](/bring-your-repository) instead.
## 2. Ask for your first page
This is the fastest way to see the whole product. Copy this into Claude Code, Codex or Cursor and send it:
```text title="Say this to your agent"
Build me an aidrop.it Service called "Bean Counter": a one-page launch site for a coffee subscription, with a hero showing the name and a line about the product, three subscription tiers as cards, and an email field that does not post anywhere yet. Write a Dockerfile for it, push it, build it on aidrop.it, and tell me when it is running.
```
Your agent hands you a URL. Open it and your page is there, on the internet, with a repository and a Service record behind it that outlive the conversation. For a longer walk-through of this exact case, read [put a landing page online](/playbooks/put-a-landing-page-online).
### What just happened
Your agent read the request, proposed a shape and waited for your yes. aidrop.it then made a repository for the code, and the agent pushed to it. Next the agent called `service_build` with a Project, the Service's name, that repository and the port the page is served on. That call creates the Service. The agent polled `service_get` until the build succeeded. A static site needs no database and no secrets, so the agent had no key to ask you for. Then it read you the address.
**Your agent wrote the HTML, the CSS and the Dockerfile on your machine and pushed them with git.** aidrop.it never writes source code. It keeps the repository, builds what was pushed and runs it. That split is the point: you can swap the agent, and the Service stays.
**Decide how it builds.** "Write a Dockerfile" is the one instruction in that paragraph that is not obvious, and skipping it is the most likely way for this to fail. With nothing said, the build is *inferred*: nixpacks, an open-source build tool, reads your repository and writes a Dockerfile itself. That is a guess nothing has checked. For a static site the inferred image writes to paths under `/var`, which cannot be written here: every container runs on a read-only filesystem with three small scratch folders. The image exits before serving anything, so the build goes green and the deploy still fails.
To build your own Dockerfile instead, commit it and have your agent pass `build_type: dockerfile` and `build_dockerfile_path` to `service_build`. A Dockerfile nobody named is never opened. After the first build, `service_get` returns a `runtime_envelope`: the rules every container runs under here and, for a named runtime kind, a Dockerfile written to follow them, ready to adjust.
**Why a landing page for the demo:** it needs no database, cache or queue, so nothing stands between you and the address. A Service that keeps data needs a database. `shared_resources_list` says whether your Project already has one, and checking it before writing code is the difference between a deploy and a container that cannot start.
Steps 3 to 5 are the same path one step at a time, for an app of your own. To plan something larger, with a frontend, a backend and a database, follow the checklist to [build and deploy a full app with an AI agent](/build-a-project).
## 3. Describe your own Service
There is no create call. A Service is made by its first `service_build`: named with a `project_id` and a `name`, that call creates the Service the first time and builds the same one every time after. Repeating it never leaves a second Service behind, and once you hold a `service_id` you pass that instead. The Project is the product the Service belongs to: `projects_list` finds one your Team already has, and `project_create` makes one for a new product.
So this step is a sentence to your agent. Nothing is written until the first build. Replace the description with your own before you send it.
```text title="Say this to your agent"
Create an aidrop.it Service called "Support portal": an internal web app where support staff look up a customer and leave notes. Python API, React front end.
```
It reads that back to you and waits for your yes. **Describe the product in your own words**: the description is recorded on the Service, and it is what the next person or the next assistant reads to learn what this is.
The call your agent makes for it comes in step 5, once the code is in a repository. It names the Project, the Service, the repository and the port:
```text
service_build(
project_id: "5c1d…",
name: "Support portal",
repository_ref: "acme/support-portal",
container_port: 8000
)
```
What comes back is the Service, created by this call, with its first build queued:
```json
{
"service_id": "8b3e…",
"service_name": "Support portal",
"build": { "id": "…", "tag": "3f9c1a2b4d5e", "commit_sha": "3f9c…", "stage": "created", "status": "running" },
"tag": "3f9c1a2b4d5e",
"repository": { "provider": "aidrop_git", "repository_ref": "acme/support-portal", "branch": "main" },
"runtime_settings": { "container_port": 8000, "health_path": "/", "resource_class": "micro", "build_type": "nixpacks" },
"next_step": "The build is queued and takes minutes. Poll service_get until its build status is succeeded or stopped …"
}
```
Two things worth knowing before you move on.
**No repository comes with a Service.** Repositories are your Team's, not the Service's. `repository_create` makes one in your Team's own Git service. It starts **empty**, with no README or scaffold to collide with your first push, and it answers the HTTPS credential your agent pushes with. `repository_get` answers the same credential again later. The first `service_build` links the repository to the Service for good.
**Nothing reads the shape out of your code.** A Service is a name and a description. How it builds and runs is what your agent passes to `service_build`. If the app will keep data, it needs a database: ask `shared_resources_list` what your Project already runs before writing code that stores anything, because the app's own disk is read-only.
## 4. Create the repository and push your first commit
```text title="Say this to your agent"
Create a repository for it on aidrop.it and push what you wrote.
```
An agent with a shell and git does this itself: `repository_create` answers the repository and its credential, and the agent pushes. A chat-only client has no shell and cannot push. It can still build a repository you pushed to yourself.
If you did not ask for a Dockerfile, the build is inferred by nixpacks and the repository needs none. A Dockerfile of your own is used only when your agent names it with `build_type: dockerfile` and `build_dockerfile_path`, and it is then built as-is.
## 5. Build it
```text title="Say this to your agent"
Build it on aidrop.it.
```
One call, `service_build`, with the repository to build from and the port your application listens on. The first call links the repository to the Service and records that port, a health path, a size (the memory and CPU the app gets, the smallest your plan includes unless the agent asks for more) and how the image is built. Every later build keeps them. **You are never asked for an address.** The deploy reserves one itself.
The build is queued and takes minutes. Your agent polls `service_get` until it reports a running application, and reads `service_logs` if it does not. Then it fixes the code, pushes, and builds again. That loop is the whole of deploying here.
```json
{
"build": { "stage": "deploy", "status": "succeeded", "commit_sha": "3f9c…" },
"address": { "url": "https://app-36195f33.cbb.aidrop.cloud", "status": "active" },
"application": { "running": true },
"next_step": "Running at https://app-36195f33.cbb.aidrop.cloud — the address is open to anyone …"
}
```
### What you get
An address like `app-36195f33.cbb.aidrop.cloud`, **open to the internet from this first deploy**. Anyone you give it to can open it, and nobody needs an aidrop.it account. `service_get` answers it, and it is on the Project's page in the dashboard.
The name in it comes from the Service's id, not from what you called the Service, so fixing a typo in the name never moves the address. When you want a memorable address, ask your agent for your own domain: `service_domain_add` answers the single DNS record to create, and `service_domain_verify` starts serving the name once it resolves. There is no screen for it. A custom domain needs the Pro plan ($20/month) or higher; see [aidrop.it pricing](https://aidrop.it/pricing).
### If it does not build
Your agent reads the log with `service_logs`, and `service_get` says which stage stopped and why. Two things account for most failed first builds:
- **A missing secret.** An application that reads `DATABASE_URL` and has none gets a URL to nothing. Secrets belong to the Project, and your agent stores them with `project_secret_set` after asking you for each value. The **Project Secrets** page in the dashboard lists their names, never the values. Each Service names the ones it reads in `required_secret_names`, and `service_build` refuses until every named secret is stored, before a build is spent.
- **Nothing listening on `PORT`.** aidrop.it hands the container its port. An application bound to a fixed number is running and unreachable. A `Dockerfile` at the repository root is always the build path that works.
Push to the tracked branch again and build again.
## Troubleshooting
A tool that refuses says why in a sentence your agent will read back to you. The ones you meet first:
| Refusal | Usual cause |
| --- | --- |
| Not authenticated | The connection lapsed or was revoked. Reconnect from your client (`/mcp` in Claude Code) |
| Missing a scope | The connection was granted `service:read` but not `service:write`. Reconnect and approve both |
| Plan limit reached | Your plan already has as many Projects as it includes. Upgrade at [app.aidrop.it/team/billing](https://app.aidrop.it/team/billing) |
| Already builds from … | That Service already has a repository; a second repository is another Service |
| No repository yet | The first `service_build` needs `repository_ref`, from `repositories_list` or `repository_create` |
| No runtime settings yet | The first `service_build` needs `container_port` |
Connecting a repository that already exists has two more refusals of its own, covered in [deploy an existing GitHub repository](/bring-your-repository).
Every answer carries a `next_step` saying what to do next, including the refusals. Following it is usually faster than reading this page twice.
## What to build next
Each playbook is a paragraph to give your agent plus what to expect. Good next ones: [a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code) that answers 24/7 with your laptop closed, [put your AI agent online](/playbooks/put-your-ai-agent-online) with memory and a spending cap, or [a landing page with its own domain and email signup](/playbooks/put-a-landing-page-online). The rest are in [all playbooks](/playbooks).
## Next steps
- [Deploy an existing GitHub repository](/bring-your-repository): the route for code you already have.
- [Build and deploy a full app with an AI agent](/build-a-project): frontend, backend and database, decision by decision.
- [Service lifecycle](/service-lifecycle): every build, rollback and stop, including what only a person can do.
- [Runtime templates](/runtime-templates): the shapes a Service can take, and what each one needs to run.
- [MCP server](/mcp): every tool an agent gets, plus authentication and permissions.
---
# Build a page with Page Builder
Source: https://docs.aidrop.it/page-builder
> Build and publish one project free for 30 days without an account. Register for 30 more days, then choose paid hosting and a plan for your own domain.
Open [Page Builder](https://builder.aidrop.cloud), describe your page or choose one of thirteen industry templates. A blank canvas is available too. Use the chat to change the copy, colours, images and sections, then review the desktop and mobile previews.
New designs use embedded typefaces, varied photographic and editorial sections, readable service menus, timelines and comparisons. Concept disclosures appear in the footer. Animation respects reduced-motion preferences, and the page stays readable when a browser does not support it. Existing saved designs keep their style; ask the chat for a visual redesign to change it.
A short idea is enough to start. For a new site without business details, Builder can propose a complete design concept with sample offers and copy. A visible notice identifies this sample content on every page. Replace it with your own details before publishing; review prices, contacts and claims rather than treating a generated concept as verified business information. After replacing the samples, tell the assistant that the content is confirmed and ask it to remove the concept notice. You can specify a visual style in your first message or refine it afterward.
The thirteen templates have distinct compositions and three linked detail pages each. They include useful content on the home page as well as those detail pages. A restaurant starts with dishes and a dining guide; a salon with service choices and visit preparation; a product catalog with a collection and selection guidance; and a software page with a worked workflow. New generations use a matching industry brief to connect the offer, examples, practical questions and next step. They do not need invented reviews or customer numbers to fill the page.
Try a short request such as “Make a one-page landing for a hair salon called LINE”, then supply your actual treatments and booking link. For a restaurant, provide the menu when you have it: supplied dishes, prices and descriptions take precedence over sample content. Existing drafts keep their content; ask the chat for the changes you want. This content planning stays within the same AI request allowance.
On desktop, drag the divider between chat and preview to widen the chat. Builder remembers your preferred width in this browser. Double-click the divider to reset it, or focus it and use the arrow keys to resize and Enter to reset. On mobile, use the Chat and Preview tabs.
If an older draft has inner pages but an empty home page, describe what the home page should contain in the chat. Builder keeps the existing inner pages while creating the home page. Before saving, it checks internal links and can repair their destinations automatically. If a request remains paused, review the saved draft and choose **Resume queue**; waiting edits run in order.
## Build a site with several pages
Each industry template starts with four linked pages and shared navigation. Choose **Site pages** above the preview to select the page your next chat request should edit. Links inside the preview also select that page. **Add a page** is available after the home page has content and opens a description form. Enter the new page’s purpose, useful details and links in the language you want, then choose **Create page**. Builder generates one additional page in the site’s shared design and opens it in the preview. Existing pages, branding and your unsent chat text are kept. If the purpose is unclear, the assistant asks for clarification instead of copying a template. A site can contain a home page and up to five additional pages. Ask the chat to rename or edit a page, or use **Delete page** to remove it.
| Template | Included pages |
| --- | --- |
| Restaurant | Home, menu, planning a visit, at the table |
| Coffee shop | Home, menu, the coffee, visit |
| Local services | Home, services, how to scope it, enquiry |
| Consultant | Home, engagements, approach, starting a brief |
| Salon | Home, services, your visit, choosing a service |
| Wellness | Home, classes, your first class, choosing a practice |
| Product catalog | Home, collection, the form, care and delivery |
| Creative studio, portfolio or interior design | Home, work or projects, services or approach, project brief |
| SaaS | Home, how it works, plan fit, starting a project |
| Event | Home, programme, attending, taking part |
| Travel and stays | Home, stays, local guide, booking |
Restaurant menus use readable dish rows with descriptions, prices and dietary notes. Schedules and product catalogs have their own layouts. Replace example prices, hours, policies and dietary information with verified details before publishing. Booking, ticket and purchase buttons link to the real service you provide; they do not create a reservation or charge a card themselves.
Navigation folds into an expandable menu on smaller screens. Review each page in mobile preview as well as desktop preview. Existing drafts keep their current content when templates change.
On phones and smaller tablets, use the persistent **Chat**, **Preview** and **Templates** buttons at the bottom of the editor. Switching views keeps your unsent message, selected site page and scroll position. Choose a page directly above the preview; internal links stay inside the editor. The chat heading shows which page you are editing. You can switch views while generation runs, and a dot on **Preview** marks an updated result.
Send a message to clear the input immediately. On mobile, the input starts compact, grows with your text up to a capped height, and shrinks again when cleared or sent. Sending also dismisses the keyboard; tap the input again to write another change. You can write and send the next change while Builder works; **Change queue** shows the current request and those waiting. Changes run in order against the latest saved result, keeping the page selected when each message was sent. You can remove a waiting request. The queue holds up to ten requests, including the one running.
If a request fails, later changes pause. Review the saved draft, then retry, remove a request or choose **Resume queue**. The queue and unsent text stay in the same browser tab across reloads; restored requests wait for your review and never replay automatically. Keep the tab open for the queue to run. A request interrupted by a connection loss may still finish on the server, so check the draft before repeating it.
## How many AI requests are included?
Guests receive five AI requests. Signing in adds five to the allowance, for ten in total including requests already used as a guest. For example, after five guest requests you have five left; after three, you have seven left. The allowance belongs to your account across all projects. Deleting a project, creating another one or signing in again does not refill this one-time free allowance.
Paid plans include a separate allowance for each paid billing month:
| Plan | AI prompts | Website address |
| --- | --- | --- |
| Guest | 5, once | aidrop address |
| Registered, free or trial | 5 more, 10 total once | aidrop address |
| Starter | 50 per paid month | aidrop address |
| Pro | 100 per paid month | aidrop address or your own domain |
| Scale | 500 per paid month | aidrop address or your own domain |
Paid requests are shared across all your Builder projects. The limit follows your subscription's billing period, not the first day of a calendar month. The chat shows the renewal date in UTC. Unused monthly requests do not roll over. An upgrade changes the limit when Billing applies the plan, while requests already used in that period remain counted. Deleting a site, reconnecting your account or changing plans does not reset the counter. Free and trial accounts keep the one-time ten-request total; an unpaid, canceled or expired subscription does not renew paid prompts. Business workspaces use the same 500-prompt ceiling as Scale.
The chat shows your remaining requests. After the last prompt is used, **Prompt limit reached** appears immediately and stays visible when you reopen Builder. Expand **How these limits work** for the plan table, what counts and renewal rules. Guests can register from the notice; signed-in users can open Billing and refresh their allowance without losing the queued changes.
**Allowance verification needed** means Billing reports an active paid plan without a confirmed current payment period. Your account and saved pages still open, and your text and queue stay saved. AI edits pause without using prompts. Open **Check Billing**, then **Refresh allowance** after the payment period is confirmed. This state does not reset your usage or mean that all prompts were spent.
Temporary rate-limit messages show when you can retry. Shared daily generation limits reset at 00:00 UTC; they are separate from your plan and an upgrade does not bypass them. The photo panel explains exhausted image attempts and full photo libraries, with alternatives such as uploading your own photos or reusing existing ones. A full shared storage pool has no promised reset time.
One message or **Create page** attempt counts once when AI work starts, including an attempt that later fails. Internal planning and repair steps do not cost additional requests. Rejected requests that never start AI work do not use the allowance. Templates, previews, publishing and direct photo controls do not use AI requests.
Only one chat generation can run for your account at a time. Requests also have shared rate limits; when a limit is reached, your queue pauses and keeps its waiting changes. After the guest allowance ends, create an account or sign in to continue within the ten-request total. After all ten are used, choose a paid plan to continue AI edits. If a monthly allowance runs out, wait for the paid renewal or choose a higher plan. Drafts stay saved, and existing publications keep their hosting or expiry terms. Use **View plans and billing**, then **Refresh allowance** after returning to Builder; resume the saved queue when ready.
Luna handles planning, page assembly and later edits. Gemini creates images under its separate allowance. Builder checks safety, page structure, internal links and spending limits before saving. If the AI is unavailable, returns an unusable result or reaches a spending limit, your queue pauses and your last saved draft stays available. Builder does not switch to another text provider automatically.
## From a brief to a useful first draft
Start with the business, what it offers and the action a visitor should take. A short request is enough for a labelled concept; include your real services, menu, prices and booking link when you have them. Builder proposes a visual direction and useful sections for the business, then assembles the site. Restaurant drafts include menu choices; service businesses explain their offers and next steps.
Before saving, Builder checks the offer structure, supplied commercial details and action destinations. It can repair internal links or image placement within a bounded request. A button linking to a service section should describe exploring services rather than pretend to submit a booking. These checks help catch mistakes; review your copy and business details before publishing.
After the first preview, answer the assistant’s next business question, add real photos and try the main action on mobile. Publish when the information and destination are ready. Ordinary edits keep the existing design and images unless you ask to change them.
## Choose the page language
Builder uses the language of your latest chat request for the page and its reply. An English request updates a Russian draft in English, including the existing text and navigation on every page. You can also request a specific language explicitly, such as “Write this page in French.”
## Create images or add your own photos
Builder plans the visual direction before assembling the page: composition, typography, colours, image framing and section treatments. That direction stays with the draft during small edits. A new image-led concept can create one matching illustration automatically after the structure and copy pass their checks; ordinary copy edits reuse existing images. Software and other text-led concepts can use typography and a workflow instead. A failed text draft does not start automatic image creation. If an image is unavailable or the request has too little time left, Builder keeps a text-led draft and explains that no photo was added.
Open **Photos → Create an AI image**, describe what the image should show, and choose **Generate image**. Then choose a page and placement, or send a photo instruction. A manually created image stays unassigned until you choose where to use it.
Image creation has a separate allowance: **one attempt as a guest, three in total after sign-in**, across all projects. An automatic concept image uses this same allowance. Started attempts count even if the provider fails; requests rejected before generation do not. Signing in transfers spent attempts once, and deleting a draft or image does not restore them. Shared spending and storage limits can pause image generation before your personal allowance ends. You can still upload your own photos or use the images already saved.
AI images are illustrative concepts, not photographs of your actual business, products or results. A note identifies them on pages where they are used. Replace them with your own photography when you need to show real premises or products.
Choose **Photos** below the chat input, then **Choose photos**. You can upload up to eight JPEG, PNG or WebP photos per site, each up to 5 MB and 25 megapixels. Animated images and SVG files are not supported. Photos are resized for the page and location metadata is removed. Stored photos are compressed to WebP, at most 1 MB each. Builder also caps total photo storage; if it is full, new uploads pause and your existing photos remain available.
After upload, Builder asks **where the photo should go or what it is for**. Select its page and use **Use as cover** or **Add to gallery** for immediate placement without an AI request. Or describe a destination, such as “use this salon interior in the Visit section”, and choose **Send photo instruction**. This sends that specific photo with your instruction and uses one AI request. Your existing chat text is kept.
**Keep as reference** keeps the photo off the draft page and excludes it from automatic image selection. Builder does not visually analyse reference images; describe any details you want it to follow. Unassigned photos are not automatically placed, and the placement question survives reloading. You can upload before creating the page and describe the page and photo placement together.
When suitable photos cannot be added, the assistant explains that instead of reporting success. New generated pages cannot substitute toy blocks or coffee packaging for unrelated subjects such as a hair salon. Review the preview before publishing.
Uploaded photos have private preview links until they are used on a published page. Do not share a preview link if you want the photo to remain private. Only photos actually used on the published page become publicly accessible. Removing a photo edits the draft; publish the change to remove it from the live page too.
## Publish free without an account
Build one project in your guest browser workspace and choose **Publish page**. It can include a home page and additional pages. The project is available at `builder.aidrop.cloud/` for 30 days from its first publication, without registration or a card. The publication card shows the exact ending date in UTC and buttons to open or copy the link.
Edits, **Update live page**, unpublishing and republishing keep the original deadline. Before publication, a guest draft is kept for 30 days from creation. Clearing the browser's cookies loses guest access; the public link alone cannot restore ownership. To start another guest project, delete the existing one, or sign in to create more saved drafts.
## Register for 30 more days
After publication, choose **Get 30 more days** before the guest period ends. Use your existing aidrop account or register, then return to the same page. Claiming the project adds 30 days to its existing publication deadline once: up to 60 days from the original guest publication. The link stays the same. Later sign-ins and publication updates do not add more time.
Your account keeps the private draft after the free publication ends, and you can open it on another device. Public pages and their public photo links stop being served at the deadline. Choose paid hosting to publish again. Registration alone does not charge a card, create a Service or start a separate hosting trial. Signing in before your first guest publication saves the draft; the normal account-hosting flow below applies when you publish.
The dashboard's **Page Builder** entry opens the same workspace. There is no separate Builder password. The account panel shows the connected email and workspace; if an email is unavailable, it shows the account identifier. **Disconnect** ends the Builder session and returns to guest mode. It keeps saved pages in your account, clears this tab's unsent text and queued requests, and does not sign you out of the aidrop dashboard.
## Publish to your own hosting
For account-created pages, choose **Publish page** when the preview is ready. For a project already published as a guest, its free extension stays on Builder; after upgrading to a paid workspace, choose **Update live page** (or **Publish page** if the free period ended) to move it to your own hosting. Builder prepares a Project, an aidrop Git repository and a template Service in your workspace. If this is your first workspace, a Personal Team is created for you. The usual Project and resource limits apply.
The first publication can take a few minutes. If you close the editor, reopen the saved page and choose **Resume publishing**. Progress is retained, so a retry reuses the same Project and Service.
Your share link remains `builder.aidrop.cloud/` and directs visitors to your Service. Additional pages have addresses such as `builder.aidrop.cloud//menu`, redirecting to `/menu` on that same Service. All site pages share one Project and Service. **Open hosting in aidrop** opens its Project, including deployment status and logs.
Custom domains require **Pro or a higher paid plan**. Starter provides hosting on an aidrop address. After publishing, choose **Connect your domain** in Builder. It checks your current plan and access. If an upgrade is needed, open **View plans**, choose a plan in Billing, return and select **Check again**. If your site still uses free Builder hosting, select **Publish to my hosting** first.
Enter a domain you own, select **Get DNS instructions**, and add the displayed record at your DNS provider. Then select **Verify connection**. DNS propagation and HTTPS setup can take a few minutes; keep the instructions and retry verification if needed. Reopening these settings restores the domain and its status. A root domain may require ALIAS, ANAME or CNAME flattening when reopening instructions. All pages in the site share the connected domain; the original Builder link remains available. Connecting requires a team admin or developer role.
## Edit a published page
Chat changes are saved as a draft. Choose **Update live page** to publish them. Free guest and extended pages update directly at their Builder link. On managed hosting, the Service receives all pages as one complete version and switches them atomically; ordinary text, layout and image changes do not rebuild the application.
A temporary connection failure leaves the last complete version running. **Unpublish** removes the public page when the Service receives that change. It does not delete your saved draft or cancel your aidrop subscription.
## Delete a draft or page
Open **My pages** and choose **Delete** beside a site. Review its name and confirm **Delete site**. This permanently removes the whole Builder site, including its draft, chat, uploaded photos and published versions. Its public Builder links stop working. For managed hosting, the same confirmation also deletes the aidrop Project created for that site and starts stopping its Service. Git code and the workspace subscription are kept. A workspace admin must confirm deletion of a hosted site.
Builder checks the linked Project before deleting it. If you added other Services or backing resources, or changed its association, open **View hosting Project** and review deletion in aidrop first. If aidrop is unavailable, the Builder draft stays saved so you can retry; a retry also handles a Project already deleted by the previous attempt.
To remove one internal page, select it above the preview and choose **Delete page**. This removes it and links to it from the draft, along with any waiting requests targeting that page. The live version stays unchanged until you choose **Update live page**. Home is the site's required root; delete the whole site through **My pages** to remove it.
Deletion requires confirmation and the latest saved version. Finish any active generation or publication first. Viewers cannot delete sites or pages.
## Hosting trial and billing
The guest 30-day period and one-time account extension are served by Builder. They do not create a subscription. Account-created pages that use managed hosting keep the existing offer: new workspaces created by publishing through Builder receive 30 days of hosting from the first verified running site. There is a separate, short provisioning window while the first deployment is prepared. No card is required to start.
After the trial, Starter is $5 per month for one Project. Payment requires an explicit checkout; registering does not charge a card. Existing workspaces keep their current plan and trial terms. The Builder offer cannot be restarted by recreating a Team, and referral and Builder trial durations do not add together.
Free and trial Builder sites include a footer link: “Built and launched on aidrop.it”, localized for supported page languages. It appears on every page alongside your own footer and cannot be removed through chat. Paid plans from Starter omit it. After upgrading, choose **Update live page** to remove the link from the published site; no content edit or application rebuild is needed.
Unpaid hosting is subject to aidrop's normal expiration and suspension rules. Your saved page remains in Builder. See [runtime plans and limits](/runtime-templates) for the current domain and resource allowances.
## What a generated page can do
Builder produces structured pages using a fixed set of components. Generated pages do not execute model-written scripts, server code or arbitrary HTML. Forms, application backends and payments inside the generated page are not supported.
The model cannot access account credentials, Project secrets, Git tokens or deployment tools. Review the generated copy, images and links before publishing. Image credits remain part of the published page when the source requires attribution.
---
# Bring an existing repository
Source: https://docs.aidrop.it/bring-your-repository
> Deploy a repository you already have on GitHub: your AI agent links it to aidrop.it, builds it with one call and gives you a live address to open.
To deploy an existing GitHub repository with your AI agent, install the aidrop.it GitHub App on the account that owns it, then tell your agent to bring it in. The agent reads the code, builds it with one `service_build` call and gives you a public HTTPS address. Nothing is copied into your repository.
If you have no code yet, the [quickstart](/quickstart) is the shorter road. If the product needs several parts, such as a frontend, an API and a database, follow the checklist to [build and deploy a full app with an AI agent](/build-a-project).
Every step here is your agent's: you say what you want and it does the rest. The [quickstart](/quickstart) shows how to connect Claude Code, Codex or Cursor, and the [MCP server reference](/mcp) lists every tool by name.
The whole page, said once. Replace the repository name with yours before you send it.
```text title="Say this to your agent"
I have a GitHub repository, acme/support-portal. Bring it into aidrop.it as a Service, build it here, and tell me what is missing if it does not run.
```
Coming from an AI app builder? These walk-throughs cover what moves and what stays: [host a Lovable app](/playbooks/host-a-lovable-app), [move an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app), and [deploy a Streamlit app](/playbooks/deploy-a-streamlit-app) at a link that does not go to sleep.
## 1. Look at the Team's repositories first
`repositories_list` returns the Team's repositories: the ones on its own aidrop.it Git service and the GitHub ones the aidrop.it GitHub App can reach, each with the Services it already backs. If a repository already backs a Service, you continue in that Service instead of starting a parallel one by accident.
**It is not a refusal.** One repository may back several Services, and sometimes it must. A Service runs one container on one port, so a monorepo (one repository holding several apps) whose API and web app deploy separately is two Services over one repository.
Your agent checks this before creating anything. If the repository already backs a Service in your Team, it offers you that one and asks, rather than quietly creating a second.
**A GitHub repository needs the aidrop.it GitHub App installed for that account.** Installing it is a browser step a person with access to the GitHub account takes, and no agent can do it for them. When the agent hits this, it should hand you the link rather than retry. Until the App is installed, the repository is not in the list and `service_build` refuses by name.
## 2. Name the deployable
There is no create call: `service_build` makes the Service on its first call, from the Project and a name you give it. Tell your agent to read the repository first and describe what it found, so what gets recorded matches the code.
```text title="Say this to your agent"
Read the repository and tell me what it is before you create anything.
```
It shows you what it read from your code and waits for a yes. Nothing is copied into your repository at any point: your code stays yours.
## 3. Build it: the first build links the repository
```text title="Say this to your agent"
Build it on aidrop.it.
```
```
service_build(
service_id: "8b3e…",
repository_ref: "acme/support-portal",
container_port: 8000
)
```
There is no separate connect step: the first `service_build` names the repository, and it becomes the Service's for good. aidrop.it does not read your code to decide how it runs. Your agent passes the port the application listens on, a health path if it is not `/`, and how the image is built. The build is queued, the deploy reserves the address itself, and your agent polls `service_get` until it reports a running application.
Code that is not on GitHub goes through `repository_create` instead. It makes an empty repository on your Team's own Git service and answers a credential your agent pushes with using its own `git`. The same `service_build` links it.
**A Dockerfile is optional.** By default the build uses nixpacks, an open-source tool that reads your repository and writes a Dockerfile itself, so code without one still builds and deploys. What you give up is certainty: that Dockerfile is a guess nothing has checked, and for some apps it produces an image that builds and then exits.
To build your own instead, pass `build_type: dockerfile` **and** `build_dockerfile_path`, the file's path in the repository: `Dockerfile`, or `build/Dockerfile.api` in a monorepo. The file can live anywhere; the repository root stays the build context, so its `COPY` paths are the ones you would write from the root. aidrop.it never goes looking for one, so a Dockerfile nobody named is never opened. After the first build, `service_get` returns a `runtime_envelope`, the rules every container runs under here, with a Dockerfile written to follow them.
## 4. If it does not run
`service_logs` says why. Your agent reads it, changes the code, pushes to the tracked branch and builds again. Pass `branch` to `service_build` if the code to run is on another branch. The quickstart describes the address and custom domains in [what you get after the first deploy](/quickstart#what-you-get).
## Next steps
- [Build and deploy a full app with an AI agent](/build-a-project): plan the parts, the database and the secrets before writing code.
- [Service lifecycle](/service-lifecycle): every build, rollback and stop, including what only a person can do.
- [Runtime templates](/runtime-templates): the shapes a Service can take, and what each one needs to run.
- [MCP server](/mcp): every tool an agent gets.
---
# Build a Project with an AI agent
Source: https://docs.aidrop.it/build-a-project
> 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.
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.
This is the build checklist. [Service lifecycle](/service-lifecycle) is the complete reference for one Service, and the [MCP server reference](/mcp) lists every tool. For a first deploy with no plan at all, start with the [quickstart](/quickstart).
For a landing page without a separate coding agent, [Page Builder](/page-builder) creates the page in chat and publishes it as a Service in your workspace.
## 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](/playbooks/put-a-landing-page-online) is one Service; [add an AI chatbot to your website](/playbooks/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](/playbooks/telegram-bot-with-claude-code) is one Service that runs around the clock; and [self-hosting n8n](/playbooks/self-host-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](/runtime-templates). 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](/bring-your-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:
```text
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](https://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](/playbooks/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.
## Related guides
- [Quickstart](/quickstart): connect your agent and deploy a first page from no code.
- [Deploy an existing GitHub repository](/bring-your-repository): the route for code that already exists.
- [Service lifecycle](/service-lifecycle): every build, deployment, rollback and stop state.
- [Runtime templates](/runtime-templates): runtime kinds, build methods, sizes, storage, and databases, caches and queues.
- [Taking your work with you](/taking-your-work-with-you): clone the code and take a database copy you own.
- [All playbooks](/playbooks): worked examples for bots, landing pages, agents and moved apps.
---
# Service lifecycle
Source: https://docs.aidrop.it/service-lifecycle
> 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](/build-a-project). For the
same lifecycle told in plain words, see
[build and host a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
or [keep a Discord bot online 24/7](/playbooks/host-a-discord-bot-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`](#3-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](#5-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.
The aidrop.it MCP server never writes source code, commits, or pushes to
GitHub. Code changes stay with your own tools.
## 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](/runtime-templates#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](/playbooks/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.
---
# Runtime settings, sizes and plans
Source: https://docs.aidrop.it/runtime-templates
> How apps run on aidrop.it: one port, a health check, a fixed size and no permanent disk. The settings, the sizes, what each plan includes and the databases.
Every app on aidrop.it runs in a small box with fixed rules: one port, a health
check, a memory size and no permanent disk. This page lists those settings, the
sizes, what each plan includes and the databases, caches and queues you can
add.
**Nothing is detected.** Your agent passes every setting to `service_build`,
or the default applies. aidrop.it never reads your repository to decide the
port, the size or the health path. The one thing it can work out is how to
build the image when you have no Dockerfile. A build is the only thing that
says a version does not run here. The [Service lifecycle](/service-lifecycle)
shows where these settings fit between the first build and a rollback.
The settings answer four questions:
| Field | What it decides |
| --- | --- |
| `runtime_kind` | How the application serves traffic: `container` (the default; the image decides everything), `static_site`, `node_http`, `python_http` or `go_http`. |
| `container_port` | The port the container listens on. Required the first time; nothing can default it. |
| `health_path` | The web address path aidrop.it checks once the container runs. An application that answers nothing on its port, or a server error (5xx) here for longer than a start-up takes, is a failed deployment. Default `/`. |
| `resource_class` | The size: how much CPU and memory the app may use, and how many processes. `micro`, `compact`, `dual`, `medium` or `large`. A build that names none gets the smallest the plan includes. |
Beside them, `required_secret_names` lists the names of the secret values the
app reads. The values themselves live on the Project, and no read ever answers
one.
## The runtime kinds
A runtime kind is a family of apps that aidrop.it has a starter Dockerfile for.
`service_get` answers a `runtime_envelope`, the limits and rules your code must
fit. It carries **a `dockerfile`** for this Service's kind: the plainest one
for that family, binding the `PORT` the platform sets, built and run under the
platform's rules.
To use it, commit it, name it in `service_build` with
`build_type: dockerfile` and `build_dockerfile_path`, and adjust the lines
marked `CHANGE ME`. The default kind, `container`, has no starter Dockerfile:
it is the kind for an image that already knows how to run itself.
| Runtime kind | Conventional port | Conventional health path |
| --- | --- | --- |
| `container` | whatever the image listens on | `/` |
| `static_site` | 8080 | `/` |
| `node_http` | 3000 | `/health` |
| `python_http` | 8000 | `/health` |
| `go_http` | 8080 | `/health` |
These are conventions, not detections: `service_build` records the port you
pass, whichever kind you name. There is one starter Dockerfile per kind. It is
precise about the platform's rules and leaves your project layout to you.
**Prefer a Dockerfile of your own to letting the build be inferred.** With
`build_type` unset, the image is built by nixpacks, an open-source builder that
picks a language version from what the repository declares. When the
repository declares nothing, it picks an old default:
- an undeclared Node application is built with **Node 18**;
- `requires-python` in `pyproject.toml` is ignored;
- Go 1.22 and 1.24 resolve to an unspecified toolchain **without raising an
error**.
Declaring `engines.node`, `.nvmrc`, `.python-version` or the `go` directive in
`go.mod` is the cheap fix. A Dockerfile is the certain one.
## Build type is separate
How an image is *built* is not how an application *serves traffic*, so the two
are recorded separately. How it is built is something you pass, never
something aidrop.it reads out of your code.
- `build_type: nixpacks` is the default. The build is inferred and the
Dockerfile is generated; your repository needs none.
- `build_type: dockerfile` builds your own, and `build_dockerfile_path` says
which file that is: `Dockerfile`, or `build/Dockerfile.api` in a monorepo.
The file may be anywhere in the repository. The repository root is always the
build context, so `COPY` paths resolve from the root. A Dockerfile nobody
named is never opened: committing one changes nothing until a build names it.
A build reads the Service's recorded settings and nothing else.
A Dockerfile does not change the runtime kind. A Python service built from its
own Dockerfile is still `python_http`; `container` is the kind for an image
that already knows how to run itself.
**A repository nothing on this page describes is still deployable.** Name
`build_type: dockerfile`, the port and the health path. The image knows how to
build and run itself, and that is all aidrop.it was missing.
## What the build records
`service_build` records the settings it built under, and `service_get`
reads them back as `runtime_settings`:
- `runtime_kind`: how the application serves traffic; `container` when the
Dockerfile decides everything.
- `container_port` and `health_path`: the two the first build asks for.
- `resource_class`: the size, defaulting to the smallest the plan includes.
- `build_type`: `nixpacks` (the default) or `dockerfile`, with
`build_dockerfile_path` when it is `dockerfile`. Passed, never detected.
- `required_secret_names`: the names of the Project's secret values this
Service reads. Only the values it names reach it. The values are stored on
the Project, only by an agent with `project_secret_set`, and no read answers
one back. The dashboard lists the names, never the values. A build is
refused while a named value has none.
There is no preflight check. aidrop.it runs no analyser over your code. When a
build stops, it names what stopped it.
A rollback restores **code**, not the database structure. aidrop.it redeploys
an earlier version against a database that has already been migrated forward,
so migrations must work with both versions: add new columns and tables first,
and remove old ones in a later release. This is the one requirement aidrop.it
cannot enforce for you.
## Sizes
A **resource class** is the size of the box: how much CPU and memory an app
gets. Every container runs inside one, and the numbers are hard limits, not
targets:
| Class | CPU | Memory |
| --- | --- | --- |
| `micro` | 0.5 vCPU | 512 MB |
| `compact` | 1 vCPU | 1 GB |
| `dual` | 2 vCPU | 2 GB |
| `medium` | 2 vCPU | 4 GB |
| `large` | 4 vCPU | 8 GB |
`dual` and `medium` share a CPU figure on purpose. One doubles the cores, the
other doubles the memory. Which you need depends on whether your application
mostly waits or mostly computes. Every class caps processes at 256.
As a guide from the playbooks: a simple
[Streamlit dashboard](/playbooks/deploy-a-streamlit-app) fits the smallest
size. [Self-hosted n8n](/playbooks/self-host-n8n) for daily use, and a
[scheduled web scraper](/playbooks/run-a-web-scraper-on-a-schedule) that drives
a headless browser, want the 1 GB `compact` size, which starts at Pro.
Storage is not on this table because there is none. **The root filesystem is
read-only.** There are three small scratch folders (`/tmp`, `/run`,
`/var/tmp`), and they are emptied on every restart. Anything that must survive
belongs in a database.
## What your plan includes
A plan sets two separate limits:
- **Projects**: how many products you may run. A Project is one product, with
everything inside it.
- **The pot**: the plan's shared memory and CPU. Everything inside your
Projects draws from it.
| Plan | Price | Projects | The pot (memory · CPU) | Sizes | Databases, caches, queues | Custom domain |
| --- | --- | --- | --- | --- | --- | --- |
| Trial | free for 7 days, no card | 1 | 768 MB · 0.75 vCPU | `micro` | PostgreSQL | No |
| Starter | $5/month | 1 | 512 MB · 0.5 vCPU | `micro` | none | No |
| Pro | $20/month | 2 | 3 GB · 3 vCPU | up to `dual` | PostgreSQL | Yes |
| Scale | $99/month | 5 | 8 GB · 8 vCPU | up to `medium` | PostgreSQL, Valkey cache, Valkey queue | Yes |
| Business | $299/month | 20 | 40 GB · 20 vCPU | up to `large` | PostgreSQL, Valkey cache, Valkey queue | Yes |
Prices are in US dollars. Scale adds human support. The current prices are on
the [aidrop.it pricing page](https://aidrop.it/pricing). Without the trial or a
paid plan, nothing runs. [Sign up](https://app.aidrop.it/register) to start the
trial.
From Pro, a Team may also choose how big its database is: `micro` or `compact`
on Pro, plus `dual` on Scale, plus `large` on Business. The size is memory and
CPU out of the same pot. It can be changed on a running database, which
restarts it, so apps reconnect. Going back down is offered too; a smaller size
never takes disk away from a database that is using it.
**A database does not use up a Project. It draws from the pot.** A Project
counts once however many services run inside it. The database, the cache and
the queue behind an application cost you memory and CPU, not Projects.
The pot is therefore the limit that decides what fits, and it is the one to
plan against. Trial shows the arithmetic in full: 512 MB for one `micro` app
plus 256 MB for its PostgreSQL is 768 MB exactly, which is the whole pot.
Two things follow from the pot that the size list does not tell you:
- A size your plan lists still has to *fit*. Pro lists `dual` at 2 GB and has
3 GB in total, so one `dual` app leaves room for a database and nothing
else.
- A stopped application still holds its share. The pot counts what is
reserved, not what is running, so the numbers you see never promise room
that the next deploy would refuse.
Business runs on a cluster of its own rather than the shared one.
## Databases, caches and queues
A **backing service** is a database, cache or queue that aidrop.it runs beside
your application. You do not install or configure one; your agent asks for it,
and its connection string arrives as an environment variable at deploy.
| Service | Variable | Size | Durable |
| --- | --- | --- | --- |
| PostgreSQL | `DATABASE_URL` | 0.25 vCPU · 256 MB | Yes, on its own volume |
| Valkey cache | `CACHE_URL` | 0.25 vCPU · 128 MB | No, evicts under pressure |
| Valkey queue | `QUEUE_URL` | 0.25 vCPU · 256 MB | Yes, append-only, on its own volume |
These are deliberately smaller than any application size. A tuned PostgreSQL
serving one small app needs far less than the app in front of it, and each one
shares a server with the traffic router. **The size is memory and CPU, not
disk.** How much data you keep is not separately capped. A cache or a queue is
not file storage for your app either.
aidrop.it takes daily snapshots. You can also take an independent export whenever you
want one, and [exporting your code and database](/taking-your-work-with-you)
shows how your agent does it.
**The queue is Valkey as well, and speaks `redis://`.** The two Valkey services
differ in the way that matters for what you put in them. The cache evicts old
keys when it is full. The queue refuses the write, because work thrown away in
silence is worse than a producer that finds out. The queue keeps an
append-only log on a volume of its own; the cache keeps nothing.
The cache is Valkey, an open-source fork of Redis. The `redis://` scheme is
unchanged, so every Redis client library connects to it as before.
**Each variable names the role, not the product.** It is `CACHE_URL` and
`QUEUE_URL` rather than `REDIS_URL`, the way `DATABASE_URL` has always worked.
Your code says what it needs the connection *for*, and stays correct if what
runs behind it ever changes.
**A backing service is the Project's, one per kind per Project.** Any Service
in the Project can be attached to it, and each reads the same variable. Inside
one PostgreSQL you can create separate databases and attach each to a
different Service. Several Services then share one claim on the pot while
keeping their data apart.
Never hard-code a connection string. Read the variable: it is what makes the
same code work whether the service was created for this Service or already
existed. The [MCP tool reference](/mcp) lists the calls that create, attach
and resize these services.
## Changing the settings
Pass the value to `service_build` again:
```json
{
"service_id": "…",
"resource_class": "medium",
"required_secret_names": ["DATABASE_URL", "SMTP_PASSWORD"]
}
```
Every setting not passed is kept from the previous build. Settings are never
rewritten in place: a changed value is recorded as a new set, tied to the
commit being built, and the size limits are copied in at that moment. A later
change to this page's tables never alters a build that already ran.
---
# Taking your work with you
Source: https://docs.aidrop.it/taking-your-work-with-you
> How to export everything from aidrop.it: clone your code with your Team's Git credential, have your agent copy the database, and why images are not included.
Nothing here needs aidrop.it's permission or a support request. You can take
your code with Git and your database through your agent, at any time. It is
written down because a way out that only exists if you ask is not much of a
way out.
## Your code
Your repository lives in your Team's own Git service at `git.aidrop.cloud`, and
you hold a credential for it. Ask your agent: `repository_get` answers the clone
URL and the push credential for any repository on that service, and
`repository_create` answered the same when it made one. Then clone as you
would any repository:
```sh
git clone https://git.aidrop.cloud//.git
```
The credential reaches every repository in your Team's service, so one clone
loop takes all of them. If you connected a GitHub repository instead, it was
always yours and aidrop.it only ever read it.
This is the usual case for an app that started in a builder. If you
[moved an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app)
or [host a Lovable app here](/playbooks/host-a-lovable-app), its code sits on
your own GitHub, so there is nothing to export.
## Your database
**aidrop.it takes daily snapshots.** For a move to another provider or an
independent copy in storage you control, ask your agent to export the database.
There are two ways, depending on size:
- **Read it over MCP.** `shared_database_query` runs any SQL statement against
the database server, or against one database inside it, and answers CSV. One
statement is stopped after 30 seconds and its answer cut at 64 KB, so the
agent takes a copy table by table, in pages, with the table definitions from
`information_schema`. This suits a small database. The
[MCP tool reference](/mcp) lists the call and its limits.
- **Run `pg_dump` from inside the Project.** `pg_dump` is PostgreSQL's own
export tool. The database sits on a private network with no public port, so
nothing outside the Project reaches it. Every Service attached to it, though,
is handed a connection string that works from there. Have your agent deploy
a small Service that runs `pg_dump` with that connection string and sends
the file over HTTPS, a container's only way out, to storage you own, such as
an S3 bucket.
Run that second Service on a schedule and it is your backup policy. A
[cron job](/playbooks/what-is-a-cron-job) is the plain-words name for a task
that runs on a timer.
Either way this export is yours to keep, independently of aidrop.it's daily
snapshots. Choose its retention period in your own storage.
Two things worth knowing before you need them:
- The cache has no copy to take, because by design it holds nothing that
survives a restart. The queue keeps a volume, but what it holds is work in
progress rather than a record, so there is nothing to hand over either.
[Databases, caches and queues](/runtime-templates#databases-caches-and-queues)
explains what each one keeps.
- Deleting a database, cache or queue (`shared_resource_delete`) asks for
confirmation and cannot be undone. Take the copy first.
## Your images, and why they are not on this list
aidrop.it builds your source into a container image and keeps it in a registry
service of your own. You cannot pull it, and that is deliberate rather than an
omission.
An image is **derived** from your code: it is what a build produces, not
something aidrop.it holds on your behalf. With the repository and the database
you have both inputs. Any builder, such as `docker build` with the Dockerfile
your repository already carries, produces the same app again. Issuing you
registry credentials would add an account, a way to revoke it and a rate limit
to maintain, in exchange for a file you can rebuild yourself.
If your repository has no Dockerfile because aidrop.it inferred the build,
`service_get` reports the runtime settings it built under: the port, the health
path and the build path. That is the whole of what the build knew.
## What aidrop.it keeps after you leave
Deleting a Service removes its container and its address. It also detaches the
Service from every database, cache and queue without deleting them, because
another Service may still be using one. The repository stays, and can still be
cloned.
---
# aidrop.it MCP server
Source: https://docs.aidrop.it/mcp
> Connect Claude Code, Codex or Cursor to the aidrop.it MCP server: sign-in, the build loop and the full tool reference your agent uses to deploy apps.
aidrop.it runs a remote MCP server at https://aidrop.it/mcp that lets Claude
Code, Codex or Cursor create, build and deploy your Services. MCP (Model
Context Protocol) is the standard way an AI agent calls tools on another
service. If the term is new to you,
[what an MCP server is, in plain words](/playbooks/what-is-an-mcp-server)
explains it before you read this reference.
```text
https://aidrop.it/mcp
```
Any MCP-capable client can connect, including Claude and ChatGPT. What it can
do depends on whether it has a shell:
- **Claude Code, Codex and Cursor** have a local shell and `git`, so they can
write code, push it into a repository, build it, run it and open it to the
internet.
- **A chat-only client** reads the record and can build code that is already
in a repository, but cannot put new code in.
**This is the whole programmable surface.** There is no REST API beside it.
Tools are added and retired as the product changes, and a test fails the build
when the [tool reference](#tools) below and the tools the server answers with
disagree. If a tool is not in that table, it does not exist.
The dashboard and the agent split the work:
- **The dashboard** administers the Team: its members and their roles (admin,
developer, viewer). No tool does that.
- **The agent** creates and removes Projects and Services. `project_create`,
`project_delete`, `service_build`, `service_update` and `service_delete` are
the only way. A Service is created by its first `service_build`, not by a
call of its own.
Access is settled once, on the Team: everyone in it can reach every Project,
and what they may do there is their role.
For the whole path an agent follows to build a product with a frontend, a
backend and a database, read [Build a Project](/build-a-project). To see the
same tools put a working assistant online, step by step, follow
[put your AI agent online](/playbooks/put-your-ai-agent-online).
Every tool publishes an `outputSchema` in `tools/list` and answers the same
JSON document twice: as text, and as `structuredContent` in the shape that
schema promises. A client that reads the schema knows what `service_get` will
answer before it calls; one that only reads text loses nothing.
## Authentication
**OAuth, with dynamic client registration.** OAuth is the standard sign-in
where you approve access in a browser window instead of copying a key. Clients
that speak MCP OAuth (Claude Code, Codex, Cursor, Claude) open that window and
walk you through consent. There is nothing to pre-register and nothing to
copy. A client that cannot complete this sign-in cannot connect: there are no
API keys.
On the consent screen you approve your Team and the scopes, the permissions
the connection gets over it. The connection then reaches every Project in the
Team, and what it may do in each is your role. You revoke it from
**Management → Connected apps** in the dashboard, which lists every
connection that holds access.
There are two scopes:
- `service:read`: open a Service and its safe snapshot.
- `service:write`: create, prepare and operate a Service.
A connection made before these scopes existed must reconnect once to receive
them. Its older `context:*` or `memory:*` scopes are still accepted and allow
nothing.
## Glossary: Team, Project, Service and repository
A **Team** is the membership and billing boundary. An agent authorizes against
one Team and, according to the member's role, can discover that Team's
Projects. It is not the boundary for a database connection or a secret value.
A **Project** is the customer's product, the thing they name, and its
operational boundary. It owns its Services, its backing services and its
secret values. A plan counts Projects. Use the current `project_id` for every
resource, connection string and secret: a backing service or value from
another Project cannot be attached and is not delivered at deploy.
A **Service** is one deployable application inside a Project, for example a
web app, an API or a worker. It has its own build, runtime settings, address
and lifecycle. It draws on the plan's memory and CPU and never counts as a
Project. It does not own a database or a secret: it receives only the named
Project values and the backing services attached to it.
A **backing service** is a managed PostgreSQL database, Valkey cache or Valkey
queue. It is not an application Service. It is the Project's, and it may be
attached only to that Project's Services.
A **repository** is the Team's, not a Service's. It exists before any Service
builds from it and outlives the Services that do. One repository may back
several Services: a monorepo whose API and web app deploy separately is two
Services over one repository.
`repositories_list` shows the Team's repositories, on its own aidrop.it Git service and on GitHub through the
aidrop.it GitHub App, with the Services each backs. A Service is created
**without** a repository; the first `service_build` links one, for good.
`projects_list` and `services_list` are where every session starts.
`service_build` takes a `project_id` from the first and a name for the
deployable, and makes the Service on its first call, so the first deploy still
happens in one session.
## The build loop
The [Service lifecycle](/service-lifecycle) follows this loop step by step,
including the steps only a person can do.
Code reaches a repository from your shell and nowhere else. Where it goes is
decided by one field: `repositories_list` answers `github_accounts`, the GitHub
accounts the aidrop.it GitHub App is connected to for the Team.
- **GitHub connected.** The code lives on GitHub. Push it to a repository under
one of those accounts, usually the local `origin`, and pass `owner/repository`
to `service_build`. A new repository is visible only when the App can reach
it: if the App was given selected repositories, a person adds the new one to
its repository access on GitHub.
- **GitHub not connected.** `repository_create` makes an empty repository on
the Team's aidrop.it Git service and answers its clone URL and a push
credential. Your own `git push` puts the code there. `repository_get`
answers the same credential again for a repository that already exists.
Then the loop, which is the whole of deploying:
1. **`service_build`** builds the newest commit of the tracked branch and,
when the build succeeds, deploys the image to the Service's address. That
address is open to the internet from this first deploy. The build is
queued and takes minutes.
- The first call links the repository: pass `repository_ref`, from
`repositories_list` or `repository_create`. Later calls need no
`repository_ref`.
- The first call also records the runtime settings. `container_port` is
the one value nothing can default. `health_path`, `resource_class`,
`runtime_kind`, `build_type` and `required_secret_names` have defaults
that are defaults, not guesses.
- **Nothing is read out of the code to fill them in.** The image is built
with nixpacks, an open-source builder that needs no Dockerfile, unless
`build_type: dockerfile` and `build_dockerfile_path` name one to build
instead.
- Every later call keeps the settings unless one is passed again. Pass
`branch` to build, and from then on follow, another branch.
2. **`service_get`** says how far it got: the repository and commit, the
build's stage and status, the deployment, the address, the settings, and a
`next_step` naming the one call that follows. Poll it; do not narrate the
wait. `deployment` is the latest attempt. `application` separately names
the active deployment, commit and tag serving the address, which can be an
earlier version when a later attempt failed.
3. **`service_logs`** is the latest build's log, with credentials hidden and
its length bounded. When the build failed, read it, fix the code, push, and
call `service_build` again.
Every successful build keeps its image under a **tag**: the first twelve
characters of the commit it was built from, named in `service_build`'s answer.
`service_tags_list` lists the images a Service has, newest first.
`service_start` with a `tag` starts that image without rebuilding it. A
rollback is that call with an older tag, and returning to the newest version
is the same call with the newest tag. Without a tag, `service_start` resumes
the current image after `service_stop` paused it.
`service_update` renames a Service and restates what it is for. Nothing else
is settable there: the address is open from the first deploy, so there is no
lock to take off.
`service_build` refuses up front with the same sentences a build would stop
on, such as a secret value nobody has stored, a size the plan does not
include, or hosting paused. It does not record a run that stops at `checked`.
### Secret values
Secret values, such as API keys, belong to the **Project**, not to one
Service. `project_secret_set` stores one under a name and
`project_secret_delete` removes it. Both take a `project_id`, and neither ever
answers a value back.
Each Service picks which of the Project's values it gets, in `service_build`
through `required_secret_names`. Exactly the names listed there are put into
that application's environment. A Project value a Service does not name never
reaches it.
Only an agent stores a value. The dashboard's **Project Secrets** page lists
the names a Project holds and when each was written, never the values, and
nothing on it sets or changes one. Ask the customer for a value when the code
needs it, store it at once, and never repeat it back, write it into code, a
commit or a log, or ask for it again once it is stored.
### The runtime envelope
`service_get` returns the **`runtime_envelope`**: the limits and rules the
code you are about to write has to fit. Read it before choosing a stack, not
after a build fails. Its keys:
- `resources`: the CPU and memory the application runs under, its size, its
port and its health path, once the first build has recorded them.
- `storage`: that there is no persistent disk, which scratch paths are
writable (`/tmp`, `/run`, `/var/tmp`) and how large they are.
- `database` and `backing_services`: what this Service can reach and under
which environment variable; see below.
- `branch`: which branch is built, and why that one.
- `build_rules`: how an image is built. That is nixpacks by default, your own
Dockerfile only when `build_type: dockerfile` names it, and which language
versions nixpacks picks when the repository declares none.
- `runtime_rules`: a read-only root filesystem, exactly one replica, no
published port and no host mount. Every Linux capability is dropped except
binding a privileged port, and the rules say why an image that switches
user at start-up serves nothing.
- `egress_rules`: outbound traffic leaves through the proxy only, on ports 80
and 443.
- `dockerfile`: the plainest Dockerfile of this Service's runtime kind,
binding the `PORT` the platform sets and built and run under those rules.
It is `null` for the default kind `container` and before the first build.
- `available_resource_classes`, `environment` and `secrets`: the sizes that
exist, the one environment there is, and how values reach the application.
### Databases, caches and queues
**`backing_services` is the part most worth reading before choosing a
stack.** It lists what this Service can actually reach: a PostgreSQL database,
a Valkey cache, a Valkey queue. Each comes with the environment variable its
connection string arrives under, and whether it survives a restart. An agent
that assumes only a database is available writes its own cache into process
memory and its own queue into a table. Neither is right here, and neither is
guessable.
Two more things it tells you, and both change what you should do:
- **The cache is not durable.** It has no volume, so a restart empties it.
Anything that must survive belongs in the database.
- **A backing service is the Project's, one per kind.** Every Service in the
Project that attaches it reads it under the same variable. Nothing in the
code needs to know whether another Service uses it too, so do not write
logic that branches on it.
`available_on_this_plan` says which kinds the Team's plan includes. The sizes
and the plans are listed in
[Runtime settings, sizes and plans](/runtime-templates).
**You can attach one the Project already runs, and create one it does not.**
- `shared_resources_list` shows what exists, which Services use it and where
its data lives.
- `shared_resource_update` attaches one to a Service or detaches it.
- `shared_resource_create` runs a new one and attaches it in the same call.
Pass `size` for a PostgreSQL instance from Pro. Pass `parent_resource_id` to
make one more database inside an instance the Project already runs, which
keeps two Services' data apart at no extra cost against the plan.
**Choose the database shape before creating anything:**
1. Call `shared_resources_list` for the current Project.
2. If it lists a PostgreSQL instance, create the new database inside that
instance with `shared_resource_create` and its `parent_resource_id`. Do not
create a second instance.
3. If the Project has no PostgreSQL instance, create one with
`kind: "postgres"` when the plan includes it and the user confirms the
billed service. That holds even when another Project in the same Team
already runs PostgreSQL.
Backing services never cross the Project boundary. An instance in another
Project cannot be attached or used as this Project's database.
**Store the connection string yourself.** When a database is attached, the
tool returns its connection string and the environment-variable name for the
application to use. Attaching does **not** store that value:
1. Save it with `project_secret_set` for the same Project.
2. Include exactly that name in the Service's `required_secret_names` on
`service_build`.
A deploy reads only its own Project's named values; a value from another
Project is not supplied.
`shared_resource_resize` moves a running PostgreSQL instance to another size
the plan includes, or back to the cluster's default. It restarts under the new
limits and clients reconnect; the data and every attached Service stay. A size
that does not fit the pot, the plan's shared memory and CPU, is refused with
the numbers.
`shared_resource_delete` removes a service and everything in it. It is
explicitly confirmed and has no MCP undo operation. aidrop.it takes daily
snapshots; take an independent export before deleting data you need:
[export your code and database](/taking-your-work-with-you) shows how.
`shared_resource_inspect` looks inside a cache or a queue: memory against its
limit, how many keys, whether it has evicted anything, the hit rate, and each
key with its type and length.
- The lengths are the point. **A queue's depth is the length of the key your
application writes to**, not a server statistic, so this is what answers "is
the queue draining".
- A cache that evicts is a cache working. A queue that evicts is full and has
thrown away work nobody did. The reply says which of the two you are looking
at.
`shared_resource_purge` empties a cache or a queue, or removes one named key.
It is confirmed and not recoverable: a cache refills itself, but a queue holds
work that has not been done yet. There is no delete-by-pattern, on purpose. It
would mean scanning and then deleting what matched, and a key your application
wrote in between would go with it.
`shared_database_query` runs one SQL statement against a PostgreSQL instance,
or against one database inside it, and hands back what it printed as CSV.
- It is the only way to reach that database from outside a deployed
application. The instance sits on a private network with no published port,
so without it, checking whether a migration landed would mean deploying
something that checks it.
- It runs any statement the database accepts: a `SELECT` to look, a
`CREATE TABLE` or `INSERT` to change. It is your data, and your agent
already writes its schema through the application it builds.
- A statement is stopped after 30 seconds and the answer is cut at 64 KB. The
reply says when that happens.
Three things bound creating a backing service:
- The **plan** decides which kinds may exist and refuses the rest by name.
- **One per kind per Project** is the shape, so a second request is refused
with the name of the first rather than quietly running another container.
- It takes an explicit **`confirmed`**, because the service is billed to the
customer for as long as it exists. That is their decision to make, not their
agent's.
A newly attached service reaches the application on its *next* build, not
immediately.
The tempting wrong answer, when a product needs to keep state and no database
is attached, is to write it to a file. The root filesystem is read-only at run
time and exactly one replica runs, so that fails **after** the build rather
than during it. Resolve the backing service before writing code that stores
anything.
### Outbound traffic
**Outbound traffic leaves through a proxy.** An application aidrop.it hosts
has no direct route to the internet. It reaches the outside only through an
HTTP proxy, whose address arrives as `HTTP_PROXY` and `HTTPS_PROXY`.
Most standard libraries honour those. A client that opens its own socket will
not, and fails with a name that does not resolve. That looks like a DNS fault
rather than a policy, so choose a proxy-aware client up front.
Only HTTP on port 80 and HTTPS on port 443 leave. A connection to SMTP, to a
database on the public internet, or to a message broker will not open. Traffic
inside the Service, including to its own database, is direct and does not use
the proxy. Every outbound request is logged with its destination.
### Bringing a repository that may already be here
When bringing a repository that might already be in aidrop.it, read
`repositories_list` first. It says which Services already build from it, so
the agent offers the existing Service rather than creating a duplicate, or a
second Service on the same repository when that is what the product needs.
`service_build` checks the repository itself when it links it: that it exists
and that the GitHub App can read it. It refuses by name when it cannot. The
user must install the aidrop.it GitHub App in the browser before a GitHub
repository can be linked. The agent never asks for GitHub credentials or
writes source code to GitHub.
A chat-only client has no local `git` to hand a push credential to.
aidrop.it accepts no uploaded archive and never commits on your behalf, so a
chat-only session reads the record and builds what is already pushed. Code
enters a Service from a shell or from a connected GitHub repository.
### Creating and deleting Projects and Services
A Project is the product and a Service is one deployed piece of it. Which
pieces a product needs is settled while it is being built, so the agent
creates, renames and removes them with `project_create`, `project_delete`,
`service_build` (the first call makes the Service), `service_update` and
`service_delete`. The dashboard lists what is running and operates it.
Confirm a delete with the customer before calling it: their application comes
off the cluster and its address stops answering. `project_delete` refuses until
it is called again with `confirmed`, but `service_delete` asks nothing and
takes effect at once, for an admin only, so the question is yours to ask
before the call. Their code does not move. The repository stays in the Team's
Git service and can still be cloned.
A Service is created with a name and a description, and nothing else decides
what it is. How it builds and runs is what the agent passes to
`service_build`, because the agent wrote or read the code and aidrop.it did
not. The repository layout rule still holds and is enforced by the runtime:
**one deployable**, because a Service runs one container on one port.
## Connecting
aidrop.it is not listed in any client's connector directory yet. Claude Code,
Codex and the ChatGPT desktop app install it as a plugin from the
[aidrop.it plugin marketplace](https://github.com/aidropit/plugins). Every
other client is set up as a **custom connector**: you give it the server
address once, and the consent screen it opens on the first call does the rest.
There is no key to paste and no skill or workflow to install: the connector
carries what the agent needs. These are the same steps as on the
[aidrop.it install page](https://aidrop.it/install).
```text
https://aidrop.it/mcp
```
1. Open **Settings → Connectors** and choose **Add custom connector**. On a
Team or Enterprise plan an owner adds it under **Organization settings →
Connectors → Add → Custom → Web** first, and members then find it under
their own Connectors.
2. Name it **aidrop.it**, paste `https://aidrop.it/mcp` as the remote MCP
server URL and click **Add**. The server
registers your client itself.
3. Click **Connect** and approve the access screen — your Team, with
`service:read` and `service:write` over it.
4. Ask your agent to deploy — for example, *"Create a Service in aidrop.it and
deploy this repository."* A chat-only session reads and builds what is
already pushed; the code itself comes from Claude Code, Codex or Cursor.
aidrop.it ships as a plugin in its own marketplace, so Claude Code needs no
server address typed by hand.
1. Add the marketplace and install the plugin from your terminal:
```bash
claude plugin marketplace add aidropit/plugins
claude plugin install aidropit@aidropit
```
2. Start `claude`, run `/mcp`, pick **aidropit** and sign in. The browser opens
the access screen — your Team, with `service:read` and `service:write`
over it.
3. Ask your agent to deploy — for example, *"Create a Service in aidrop.it and
deploy this repository."*
aidrop.it ships as a plugin in its own marketplace, so Codex needs no server
address typed by hand.
1. Add the marketplace and install the plugin from your terminal — the Codex
desktop app and Codex in ChatGPT read the same configuration:
```bash
codex plugin marketplace add aidropit/plugins --sparse .agents/plugins
codex plugin add aidropit@aidropit
```
2. Sign in when the install prompts you, or run `codex mcp login aidropit`,
and approve the access screen — your Team, with `service:read` and
`service:write` over it.
3. Ask your agent to deploy — for example, *"Create a Service in aidrop.it and
deploy this repository."*
The same plugin installs into the ChatGPT desktop app through the Plugins
Directory.
1. Register the marketplace once from your terminal (it needs the Codex CLI):
```bash
codex plugin marketplace add aidropit/plugins --sparse .agents/plugins
```
2. Restart the ChatGPT desktop app, open the **Plugins Directory**, pick the
**aidrop.it** marketplace and click **Install plugin** on **aidrop.it**.
Sign in when prompted and approve the access screen — your Team, with
`service:read` and `service:write` over it.
3. Ask your agent to deploy. ChatGPT has no shell, so it reads and builds what
is already in a repository; use Codex to write and push the code.
Without the desktop app, ChatGPT on the web still takes the server as a custom
connector: **Settings → Connectors → Advanced settings → Developer mode**
(Plus, Pro, Team and Enterprise; a workspace admin turns it on), then
**Connectors → Create**, name it **aidrop.it**, paste
`https://aidrop.it/mcp` as the MCP server URL and choose **OAuth**.
1. Open **Cursor → Settings… → Cursor Settings → Tools & MCP** and click
**New MCP Server**. Cursor opens `mcp.json`; add the entry:
```json title="mcp.json"
{
"mcpServers": {
"aidrop": {
"url": "https://aidrop.it/mcp"
}
}
}
```
2. Save, then click the server's **Needs login** link on the same settings
screen and approve the access screen.
3. Ask your agent to deploy — for example, *"Create a Service in aidrop.it and
deploy this repository."*
Any client that supports remote MCP servers over streamable HTTP works — VS
Code, Continue, Cline, Windsurf, Zed, and others.
1. Add the server to your client config — dynamic client registration means
there is nothing to pre-register:
```json title="mcp.json"
{
"mcpServers": {
"aidrop": {
"type": "http",
"url": "https://aidrop.it/mcp"
}
}
}
```
2. Complete the consent screen your client opens on the first call. A client
that cannot perform an OAuth sign-in cannot connect; there is no API key
to use instead.
3. Ask your agent to deploy. A client with no local git or shell cannot put
code into aidrop.it — use Claude Code, Codex or Cursor for that.
Every connection you make shows up under **Management → Connected apps** in
the dashboard, and is revoked from there.
## Try it
Verify the connection before relying on it:
- **Claude Code:** open `/mcp` in a session — `aidropit` should show as connected, and the same screen lets you re-authenticate.
- **Any client:** ask the assistant to call `services_list`. You should see the
Services your Team member account can open. If the tool is missing, the
connection is older than these scopes: reconnect so it carries
`service:read` and `service:write`.
## What the runtime gives your code
The full list of settings, sizes and plan limits is in
[Runtime settings, sizes and plans](/runtime-templates). The rules your code
meets first:
- **`PORT` is set in the environment**, to the port the route points at. Bind
it rather than a literal: an application that hard-codes 3000 while its
profile says 8000 is running and unreachable, which reads as a broken app.
- **One container, one port, one replica.** A Service deploys a single
service. If a product genuinely needs two independently deployable services,
that is two Services, and worth saying to the owner rather than laying one
repository out as though both will run in one container.
- **Your own `Dockerfile` is the universal path.** It is what makes Java, PHP,
Ruby, Rust and .NET work here: pass `build_type: dockerfile` and
`build_dockerfile_path` to `service_build`, and aidrop.it builds that file
as-is and infers nothing.
- **`active` means a container is running and answering.** A deployment whose
container does not stay running is `failed` and carries the task's own error.
One that runs but answers nothing on its port, or answers 5xx on its
`health_path` for longer than a start-up takes, is `failed` too, with the
reason: bind the `PORT` aidrop.it sets, and make the health path answer.
- **Application files are not durable.** The root filesystem is read-only and
scratch is cleared on restart. Put records in PostgreSQL and uploads/media in
object storage — the runtime gives a Service no data volume, so a local path
is not a place to keep anything.
## Tools
**The product and its pieces**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `projects_list` | `service:read` | List the Team's Projects — the products its Services belong to — with the ids `service_build` and `services_list` take. |
| `project_create` | `service:write` | Create a Project: the product a set of Services belongs to. A developer or admin role in the Team is required. |
| `project_delete` | `service:write` | Archive a Project and every Service in it. Admin role; confirm with the customer first. Code is not touched. |
| `services_list` | `service:read` | List the Services the caller can open, with the Project each belongs to and whether its application is running. Narrow to one Project with `project_id`. |
| `service_get` | `service:read` | Read one Service — its Project, repository, address, latest build and deployment attempt, the exact active deployment and commit serving now, and the runtime envelope the code has to fit. This is the call to poll after `service_build`. |
| `project_get` | `service:read` | Read one Project: its name, what it is for, and the Services in it. |
| `project_update` | `service:write` | Rename a Project or change what it is for. The address and the repository are unaffected. |
| `service_update` | `service:write` | Change a Service's settings: its name and what it is for. The address and the repository keep the slug the Service was created with. |
| `service_delete` | `service:write` | Archive a Service: its application is removed from the cluster and its address stops answering. Admin role. Takes effect at once with no `confirmed` step, so confirm with the customer before calling it. Code is not touched. |
**Repositories**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `repositories_list` | `service:read` | List the Team's repositories — on its aidrop.it Git service and on GitHub through the Aidrop GitHub App — with the Services each one backs, and `github_accounts`: when it is not empty, new code goes to GitHub. |
| `repository_get` | `service:write` | Read one repository: its branch, whether it has commits yet, the Services it backs, and — for an aidrop.it one — the credential your own `git` pushes with. Developer or admin role. |
| `repository_create` | `service:write` | Create an empty repository on the Team's aidrop.it Git service, for a Team without GitHub connected; answers the clone URL and the push credential. Developer or admin role. |
| `repository_delete` | `service:write` | Delete a repository on the Team's aidrop.it Git service, with every commit in it. `confirmed`, not recoverable, and refused while a Service still builds from it. |
**The build loop**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `service_build` | `service:write` | Build the tracked branch's head and deploy it to the Service's address, which is open to the internet from that first deploy. The first call links the repository (`repository_ref`) and records the runtime settings; pass `branch` to follow another branch. |
| `service_logs` | `service:read` | The latest build's log, credential-redacted and bounded. A run that stopped before a build was queued answers its stop reason. |
| `service_tags_list` | `service:read` | The images built for this Service, newest first: tag, commit, status, which one runs now, which are runnable. |
**Run it, open it**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `service_start` | `service:write` | Resume the application after a pause; with a `tag` from `service_tags_list`, start that built image instead — a rollback is this call with an older tag. |
| `service_stop` | `service:write` | Pause the application: the container stops and the address stops answering. Takes `confirmed`. |
**Your own domain**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `service_domain_add` | `service:write` | Claim a domain the customer owns for a Service, and answer the one DNS record they have to create — a CNAME at the Service's own address for a subdomain, an A record or apex alias for a bare domain. From the Pro plan, and only for a Service that has been built. Nothing resolves until the record exists and `service_domain_verify` proves it. |
| `service_domain_verify` | `service:write` | Check the record and, when it is there, start serving the Service on that name — certificate included. DNS takes minutes to hours to spread; a name that is not proved yet is not a failure, call this again. |
| `service_domain_remove` | `service:write` | Stop serving a custom domain. The Service keeps its aidrop address, which cannot be removed. `confirmed`. The DNS record at the registrar is the customer's to delete. |
**The values an application reads**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `project_secret_set` | `service:write` | Store a value the Project's applications read from their environment — an API key, a token, a connection string to something Aidrop does not run. Never answered back by any tool. |
| `project_secret_delete` | `service:write` | Remove one by name. A Service that still names it in `required_secret_names` will refuse to build. |
**Backing services**
| Tool | Scope | What agents use it for |
| --- | --- | --- |
| `shared_resources_list` | `service:read` | List the Project's databases, caches and queues — status, the variable each arrives under, which Services use it, and where its data lives. |
| `shared_resource_create` | `service:write` | Run a new database, cache or queue for the Project and attach it to a Service in one call, or create one more database inside a PostgreSQL instance with `parent_resource_id`. An instance is billed, so it takes `confirmed`; `size` picks a PostgreSQL class from Pro. |
| `shared_resource_update` | `service:write` | Attach a backing service to a Service, detach it, or change the variable the Service reads it as. |
| `shared_resource_resize` | `service:write` | Move a PostgreSQL instance to another size the plan includes — `micro`, `compact` from Pro, `dual` from Scale, `large` on Business — or back to the default. It restarts; the data and the attachments stay. A size the pot cannot hold is refused with the numbers. |
| `shared_resource_inspect` | `service:read` | Look inside a cache or a queue: memory against its limit, key count, evictions, hit rate, and each key with its type and length — which is how a queue's depth is read. |
| `shared_resource_purge` | `service:write` | Empty a cache or a queue, or remove one named key. `confirmed`, and not recoverable. |
| `shared_database_query` | `service:write` | Run one SQL statement against a PostgreSQL instance, or one database inside it, and get what it printed as CSV — the only way to read that data from outside a deployed application. Stopped after 30 seconds, answer cut at 64 KB. |
| `shared_resource_delete` | `service:write` | Destroy a backing service and the data in it; deleting an instance deletes the databases inside it. `confirmed`, and not recoverable. |
**A deployed address is public.** There is no visibility setting and no
preview password. Deploying a Service puts it on the open internet, so tell
the user that before the first build, not after it.
**A custom domain is added by the agent, not in a dashboard.** There is no
screen for it: the three domain tools above are the whole surface, and
`service_get` lists the domains a Service holds with the id each one is
verified by. An agent that tells a customer to go and configure something has
handed back the work they are paying it to do.
Tool calls are not metered. What a plan bounds is how many Projects it includes
and what their Services may run.
---
# Deploy a landing page built with Claude Code, Codex or Cursor
Source: https://docs.aidrop.it/playbooks/put-a-landing-page-online
> Deploy the landing page Claude Code, Codex or Cursor built for you: a live link in minutes, your own domain, and a signup form that keeps the emails.
A landing page is one web page with one job: get a visitor to do one thing,
like join a waitlist or book a call. If Claude Code, Codex or Cursor wrote
yours, this page gets it online at a public link, on your own domain if you
want, with a signup form that really keeps the emails. You paste one
paragraph into your agent, and it puts the page on aidrop.it and gives you the
link. The first build takes a few minutes.
It costs $5 a month on the Starter plan, at an aidrop.it address. Your own
domain needs the Pro plan, $20 a month. If you need a data dashboard rather
than a page, [deploy a Streamlit app](/playbooks/deploy-a-streamlit-app)
instead.
## What you will have at the end
- Your page at a secure link anyone can open.
- If you want, the same page on your own domain, with and without "www".
- A signup form whose emails land somewhere you can read them.
- The page saved in a code repository, ready for the next change.
## Words you will meet
- **Static site**: a site made only of ready files (text, styles, pictures), so it is fast and cheap to run.
- **Domain**: your web name, like yourbrand.com. The version without "www" is the root domain.
- **DNS record**: a line you add where you bought your domain, saying where the name points. Your agent tells you what to type.
- **Database**: a safe place that keeps information, like signup emails, through restarts.
- **Email service key**: the private password your page uses to send welcome emails. You give it to your agent once, when it asks, and the agent saves it in your project's secrets on aidrop.it, never in the page's code.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep it running, Starter at $5/month gives you an aidrop.it address. Your own domain, or keeping emails in your own database, needs Pro at $20/month; Starter has no database. All plans are on the [pricing page](https://aidrop.it/pricing).
- Your agent connected to aidrop.it: see [Quickstart](/quickstart).
- Optional: a form service account such as [Formspree](https://formspree.io/html), and an email service such as [Resend](https://resend.com/docs/api-reference/emails/send-email) for welcome emails.
## Say this to your agent
Replace the part in square brackets before you paste.
```text title="Say this to your agent"
Put my landing page online on aidrop.it. Read aidrop.it's runtime rules first and follow them. Build it as a static site from your own Dockerfile.
If there is no page yet, write one for: [what I offer, and who it is for]. One clear headline, one call to action, a short email signup form, fast and easy to use on a phone.
Use my aidrop.it project, or create one. Warn me before the first deploy that the link will be public. Build it, check it runs, fix anything that fails.
For the signup form, ask me which I want:
A) a form service such as Formspree; I give you its link.
B) one small app that serves the page and saves each email in a PostgreSQL database on aidrop.it. Check whether my project has a database and ask before creating one. Never save emails to a file: the disk is wiped on restart.
Send any email through an email API such as Resend, never SMTP, which is blocked. Secrets: ask me for its key, store it with project_secret_set under a clear name, and list that name in required_secret_names when you build. Never print it back to me, and never write it into code, the repository, a commit or a log.
When I give you my domain, connect www and the bare domain and tell me exactly which DNS records to create.
Report back: the link, where signup emails go, and any DNS record I still have to create.
```
## What your agent does to put the page online
1. Finds or creates your project, and writes the page if you have none.
2. Packs the page into a small web server that follows aidrop.it's rules, saves the code and builds it.
3. Opens the page itself. If it does not show, the agent reads why, fixes the web server setup and tries again.
4. Gives you the link, and later the records for your domain.
## Collecting emails: the honest part
A static page cannot keep anything, so the emails need somewhere to go.
**A form service** is simplest: each email goes to the service, and you read
or export them there.
**Your own database** keeps the list with you. Your agent turns the page into
a tiny app that shows the same page and saves each email. One small app plus
one database fits the trial exactly; after the trial it needs Pro. aidrop.it
takes daily snapshots. You can also ask your agent for an independent copy of the list
([Taking your work with you](/taking-your-work-with-you)).
Sending email works only through an email service's web connection; the
mail-server route many tutorials use is blocked on aidrop.it.
## Your own domain
Your own domain needs the Pro plan. Your agent connects the name and tells
you what to add at your domain company. For "www" it is a simple pointer to
your page. The bare domain cannot take that kind of pointer, because of
[a rule about root domains](https://aidrop.it/blog/your-root-domain-cannot-be-a-cname/),
so it gets an address-style record. If your provider offers "ALIAS", "ANAME"
or "CNAME flattening", prefer that: it keeps working if the address behind
your page changes. Updates take minutes to hours.
## Before you share the link
- **Headline**: says what it is and who it is for, at a glance.
- **One action**: one button or form, not five choices.
- **Speed**: the main content should show within about 2.5 seconds, the "good" mark in [Google's page speed guide](https://web.dev/articles/vitals). Big photos and videos slow it most.
- **Phone**: the form fits, buttons are easy to tap, nothing slides sideways.
## Check the page and the signup form
- Open the link on your phone and on a computer.
- Sign up with your own email and check it arrived.
- Open your domain with and without "www". Both show a padlock.
## When the page, the form or the domain does not work
| What you see | What to tell your agent |
| --- | --- |
| The build finished, but the page never opens | "Read the error log, follow aidrop.it's runtime rules for a static site, and build again." |
| Your domain company refuses the record for the bare domain | "My provider refused it. Give me the other record type." |
| The domain does not open after an hour | "Check my DNS record and verify the domain again." |
| People sign up, but no emails are saved | "The form is not connected. Set up option A or B." |
| The welcome email never arrives | "Send it through the email service's web API, not SMTP." |
## FAQ
### What is a landing page, and how is it different from a website?
A website has many pages for many purposes: about, blog, pricing, support. A
landing page is one page with one goal, usually a signup, a booking or a sale.
Visitors arrive from an ad, a post or an email, and everything on the page
points to that one action.
### What is a good landing page conversion rate?
Conversion rate is signups divided by visitors. Published averages differ a
lot by industry, offer and traffic source, so someone else's number tells you
little. Compare your page with its own last version instead, changing one
thing at a time, such as the headline.
### Is an AI landing page builder easier than a coding agent?
A builder is quick, but the page usually lives inside it, and moving it is
hard. A coding agent writes ordinary files you own. With aidrop.it the
same agent also puts them online, keeps them in a repository and makes the
next change when you ask, so you are not tied to one tool. If your page
already lives in a builder, see how to
[move an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app).
### How much does it cost to host a landing page here?
$5 a month on Starter, at an aidrop.it address, for a page whose form sends
emails to a form service. Your own domain, or a signup list kept in your own
database, needs Pro at $20 a month.
## Related
- [Quickstart](/quickstart)
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [Host a Lovable app](/playbooks/host-a-lovable-app)
- [Deploy a Streamlit app](/playbooks/deploy-a-streamlit-app)
- [Move an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app)
- [All playbooks](/playbooks)
---
# Keep your Streamlit app from sleeping: deploy it always on
Source: https://docs.aidrop.it/playbooks/deploy-a-streamlit-app
> Streamlit Community Cloud puts apps to sleep after 12 hours without visitors. Deploy yours where it stays awake, with private code, from $5 a month.
As of October 2026, Streamlit Community Cloud puts any app with no traffic
for 12 hours to sleep. The next visitor sees a button to wake it and waits
while it starts. This page moves your [Streamlit](https://streamlit.io) app to
aidrop.it, where it keeps running and your code stays private. You paste one
paragraph into your AI coding agent (Claude Code, Codex or Cursor). It
packages the app, builds it, checks that it runs and gives you the link.
A simple dashboard runs on Starter for $5 a month. More memory, a database or
your own domain needs Pro, $20 a month. If your app came from an AI builder
rather than a Python script, [host your Lovable app](/playbooks/host-a-lovable-app)
or [move your Base44 or Replit app](/playbooks/host-a-base44-or-replit-app)
instead.
## What you will have at the end
- Your Streamlit app at its own link, open to anyone you send it to.
- An app that stays awake, with no "wake this app up" button for visitors.
- Your API keys stored as secrets, never written into the code.
- Your own domain, if you want one: your agent tells you the one record to add.
## Words you will meet
- **Streamlit** is a free, open-source Python tool that turns a script into a web app with charts, tables and buttons.
- **API key** is the private value your app uses to call a service such as OpenAI. Streamlit's own hosting keeps these in a secrets file; on aidrop.it your agent saves them as secrets in your project, where only your app can read them.
- **Memory** is how much the app can hold in its head at once. Big spreadsheets loaded into the app eat a lot of it.
- **Size** is how much memory and computing power your app gets. You can move to a bigger size if the app needs it.
- **Live connection** is how a Streamlit page talks to its server while you click. If it breaks, the page keeps saying it is connecting.
- **Database** is a place to keep records that must survive a restart.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep it running, Starter at $5/month fits a simple dashboard. More memory, a database or your own domain needs Pro at $20/month. See the [pricing page](https://aidrop.it/pricing).
- Your app's code: a folder on your computer or a GitHub repository.
- Enough memory. The smallest size has about half a gigabyte. A simple dashboard fits. An app that loads large spreadsheets may need 1 or 2 GB, which the Pro plan and higher include.
- Your agent connected to aidrop.it. See the [quickstart](/quickstart).
- The API keys your app uses, ready to give to your agent when it asks.
## Say this to your agent
Replace the parts in angle brackets before you paste.
```text title="Say this to your agent"
Put my Streamlit app online on aidrop.it. The code is in , and the main file is . Create a new aidrop.it Project called "" for it.
Read aidrop.it's runtime rules before you write anything and follow them. Run Streamlit headless, listening on 0.0.0.0 and the port aidrop.it gives it, with the file watcher and usage stats off. The disk is read-only: point HOME at /tmp and pass Streamlit settings as flags or STREAMLIT_* variables, not a file in the home folder. Use /_stcore/health as the health check.
Read API keys from environment variables, not st.secrets: there will be no secrets.toml file. Secrets: ask me for each API key the app uses, 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.
Pin the dependencies. Estimate how much memory the app needs with its real data (pandas frames included) and pick a size that fits. Anything the app writes to disk is lost on restart; if it must keep data, ask me before adding a PostgreSQL database.
When it runs, open it, click a widget and confirm the page updates. Then tell me the link.
```
## What your agent does to deploy the Streamlit app
1. Reads your app and lists the libraries and keys it needs.
2. Writes a short build recipe that fits aidrop.it's rules and saves it with your code.
3. Asks you for your keys. You paste each one into the chat once, and the agent saves it as a secret in your project. It never shows a key again or writes it into the code, and nothing can read one back. Under **Secrets** in your Project on the aidrop.it dashboard you can check which secrets exist, by name only.
4. Builds the app and waits until Streamlit's own health check answers. A library that will not install is the usual first failure, so it fixes the dependency list and builds again.
5. Opens the app, clicks a widget to check the live connection and gives you the link.
## Check that the app stays awake
- Open the link. The app appears and stops showing its "running" indicator.
- Change a slider or a filter. The chart or table updates. This shows the live connection works.
- Load your biggest real file or query. The app should not restart or freeze.
- Come back the next day. The app opens right away, without a wake-up step.
## When something goes wrong
| What you see | What to tell your agent |
| --- | --- |
| The page keeps saying it is connecting | "The page never finishes connecting. Check the live connection through the aidrop.it address and read the logs." |
| The app restarts or crashes when loading data | "The app runs out of memory. Make it use less, or move it to a bigger size." |
| An error about missing secrets | "Read the keys from the project's secrets, not from a secrets file." |
| Files the app saved are gone after a restart | "Saved files vanish on restart. Keep that data in a database." |
| The build fails on a library | "Read the build log and fix the dependency list." |
## FAQ
### Is Streamlit free?
Yes. Streamlit is open source, so the library costs nothing. Streamlit Community Cloud, the official hosting, is also free, with limits. As of October 2026, its [documented limits](https://docs.streamlit.io/deploy/streamlit-community-cloud/manage-your-app) are: apps with no traffic for 12 hours go to sleep, memory is capped at about 2.7 GB, and you may have one private app at a time.
### How do I deploy a Streamlit app?
You need a host that runs Python and keeps a live connection to the browser open. Install your libraries, start the app with Streamlit's run command, and make it listen on the address and port the host gives it. Keep keys out of the code. Check that clicking a widget updates the page.
### Why does my Streamlit app go to sleep?
Streamlit Community Cloud puts apps to sleep after 12 hours without visitors. The next visitor sees a button to wake the app and has to wait while it starts. A host that keeps the app running all the time avoids that wait, which matters for a tool people open once a day.
### Can I keep my Streamlit app private?
On Community Cloud, an app from a private repository is private, but only one at a time. On aidrop.it your code stays private, while the app's link opens for anyone who has it. If the app itself must be private, ask your agent to add a password or sign-in page to it.
## Related
- [Put a landing page online](/playbooks/put-a-landing-page-online)
- [Host your Lovable app](/playbooks/host-a-lovable-app)
- [Move an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app)
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [App sizes and plans](/runtime-templates)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Build a custom AI chatbot for your website with Claude or OpenAI
Source: https://docs.aidrop.it/playbooks/add-an-ai-chatbot-to-your-website
> Build a custom AI chatbot for your website on the Claude or OpenAI API. It answers from your FAQ, keeps your key private, and costs a plan plus usage.
This page builds a custom AI chatbot that you own: a chat bubble on your
website that answers visitors with Claude or ChatGPT, using your own rules and
your own FAQ. It is not a no-code widget you rent. If you want a chat box today
and do not mind a monthly subscription and someone else's rules, a ready-made
widget service is quicker. Build your own when you want to decide what the bot
says, which AI it uses, and where the conversations go.
It has two parts: a small app that holds your private AI key and talks to the
model, and one line added to your site that shows the bubble. Your coding agent
(Claude Code, Codex or Cursor) writes both and puts the app on aidrop.it. You
paste one paragraph and your FAQ.
The monthly cost has two parts: the hosting plan, from $5 a month on Starter
($20 on Pro if you want to save conversations), and the AI usage your provider
bills per message, which you cap yourself.
## What you will have at the end
- A chat bubble on your website, wherever the site is hosted.
- Answers from your own FAQ, and "I don't know, here is how to reach us" for the rest.
- Your AI key kept private, never visible in the browser.
- A limit per visitor, and a monthly spending cap at your AI provider.
- If you want, a record of what people ask.
## Words you will meet
- **AI model**: the "brain" behind the answers, rented from Anthropic (Claude) or OpenAI (ChatGPT) and paid by how much text it handles.
- **API key**: the password that lets your app use that provider, billed to you. Whoever has it can spend your money.
- **Secret**: where the API key lives, in your aidrop.it project. You give the key to your agent once and it saves it there. The chat app reads it on the server, so it never reaches a visitor's browser.
- **Rate limit**: a cap on how many messages one visitor can send in a given time.
- **Database**: a safe place that keeps conversations through restarts.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep the chatbot running after that, Starter at $5/month runs the chat app; saving conversations needs a database, which means Pro at $20/month.
- Your agent connected to aidrop.it, as in the [Quickstart](/quickstart).
- An API key from [Anthropic](https://platform.claude.com/) or [OpenAI](https://platform.openai.com/).
- Your FAQ as plain text, and access to edit your site.
If your site itself was built with Lovable, you can
[host your Lovable app](/playbooks/host-a-lovable-app) on aidrop.it as well and
add the bubble there.
## First, cap your spending
The chat app has a public address. Anyone can send it messages, even
programs that skip your website, and each message costs a little. So first
set a monthly spend limit at your provider: Anthropic has it in each
workspace's [spend limits settings](https://platform.claude.com/docs/en/manage-claude/workspaces),
OpenAI in each project's
[limits](https://developers.openai.com/api/docs/guides/spend-limits). Make it a
hard limit, not only an alert. When it is reached, the chatbot stops answering
until next month instead of running up a bill.
## Say this to your agent
Replace the parts in square brackets with your contact and your site's address
before you paste.
```text title="Say this to your agent"
Add an AI chatbot to my website, with its backend on aidrop.it. Read aidrop.it's runtime rules first and follow them. Use my aidrop.it project, or create one.
Build one small Python app that:
- answers through the Anthropic API with the official Python SDK (or OpenAI's, if I say so), which works with aidrop.it's outgoing proxy as is. Pick a current fast, low-cost model from the official model list; tell me which.
- reads the API key from a project secret: ask me for the key, store it with project_secret_set under a clear name, and list that name in required_secret_names when you build. Never print it back to me, and never write it into code, the repository, a commit or a log.
- answers only from faq.md in the repository; otherwise says it does not know and gives my contact: [your email].
- serves the chat bubble and gives me one line for my site.
- accepts browser requests only from [https://example.com].
- limits each visitor (about 20 messages per 10 minutes, 1,000 characters each) by their real address, keeps answers short, and has a daily total cap.
Ask me whether to save conversations. If yes, use a PostgreSQL database on aidrop.it (check for one first, ask before creating it), never files.
Warn me before the first deploy that the address is public. Build it, check it runs, fix anything that fails. Report the address, the line for my site, the model, and how to update the FAQ.
```
## What your agent does to build your chatbot
1. Finds or creates your project, and writes the chat app and the bubble.
2. Asks you for your API key. You paste it into the chat once, and the agent saves it as a secret in your project, where only the chat app can read it. It never shows the key again or writes it into the code.
3. Saves the code on aidrop.it, builds it and asks it a question from your FAQ. If the answer does not come back, it checks the key and the provider's reply before building again.
4. Gives you the address and the line for your site.
To change what the bot knows, edit the FAQ and ask your agent to update the
app. A few pages of FAQ fit in the model's instructions, so a small site
needs no search system or "vector database".
## What protects you, and what does not
The key stays on aidrop.it, so nobody can copy it from your pages. Browsers
on other websites are refused, so nobody can reuse your bubble on their site.
That rule does not stop a program calling your app directly; the visitor
limit, the daily cap and your spend limit keep that from becoming a bill.
If you save conversations, mention it in your privacy notice. aidrop.it takes
daily snapshots; ask your agent for an independent export when you need one
([how to take a copy of your data](/taking-your-work-with-you)).
## Check that the chatbot answers from your FAQ
- Add the line to one page of your site. The bubble appears.
- Ask a question from your FAQ. The answer matches it.
- Ask something the FAQ does not cover. The bot says so and gives your contact.
## When something goes wrong
| What you see | What to tell your agent |
| --- | --- |
| The bubble does not appear | "The bubble does not load. Check the line, and whether my site blocks outside scripts." |
| The bubble appears, but every message fails | "Allow requests from my site's exact address, with and without www, and read the error log." |
| Answers never arrive | "Requests to the AI provider time out. Follow aidrop.it's rules for outgoing connections." |
| The build is refused | Give your agent the key again and say "Store it under the name you gave me and build again." |
| Answers are made up | "Answer only from the FAQ, and say you don't know otherwise." |
## FAQ
### How much does a custom website chatbot cost?
Two bills. Hosting on aidrop.it is a flat plan: Starter at $5 a month, or Pro
at $20 if you save conversations ([all plans](https://aidrop.it/pricing)). The
AI usage is billed by Anthropic or OpenAI for each message, so it grows with
your traffic; the hard spend limit you set above is the most it can ever reach.
### Custom chatbot or a no-code chat widget?
Ready-made chat widgets are quick to add, bill monthly and keep your data in
their system. A chatbot you own costs hosting plus what the AI model uses,
answers from exactly the text you give it, keeps conversations in your own
database, and can change any way you like. For a small site, answering from
your own FAQ covers most questions.
### Do I need to know how to code?
No. Claude Code, Codex or Cursor writes the whole thing. Connected to
aidrop.it, the same agent also puts it online, keeps your key as a secret,
reads the error log when something breaks, and updates the bot when your FAQ
changes. Your part is the API key, the FAQ and one line pasted into your site.
### Can the same bot answer in Telegram?
Yes. The answering part stays the same; only the channel changes. Our
[Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
playbook shows the Telegram side, and you can ask your agent to give it the
same FAQ.
## Related
- [Put your AI-built landing page online](/playbooks/put-a-landing-page-online)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Where do the secrets live?](https://aidrop.it/blog/where-do-the-secrets-live/)
- [All playbooks](/playbooks)
---
# Host your Lovable app on your own hosting
Source: https://docs.aidrop.it/playbooks/host-a-lovable-app
> Move the website part of your Lovable app to hosting you control, with your own link and domain. Your AI agent does the moving; your data stays where it is.
This page moves the website part of an app you built in [Lovable](https://lovable.dev)
to aidrop.it. You paste one paragraph into your AI coding agent (Claude Code,
Codex or Cursor). It takes your code from GitHub, builds it and gives you a
working link. The build itself takes minutes. Your database and user sign-in stay
on Lovable Cloud (or your own Supabase). Only the website moves.
The website costs $5 a month on aidrop.it's Starter plan, or $20 a month on
Pro if you want your own domain. On Lovable, a custom domain needs its Pro
plan, from $25 a month as of October 2026
([Lovable's plans](https://docs.lovable.dev/introduction/subscription-plans)).
Your backend stays on Lovable Cloud, under your Lovable account.
## What you will have at the end
- Your Lovable app running at its own secure link, and on your own domain if you want one.
- The same pages, logins and data as before, because the site still talks to the same backend.
- A copy of the code you own, which any agent can change later.
- A way to publish new versions: keep editing in Lovable, then ask your agent to rebuild.
## Words you will meet
- **GitHub** is a website that stores code. Lovable can copy your app's code there and keep it up to date.
- **Backend** is the hidden part of the app: database, user accounts, file storage. For most Lovable apps it is Lovable Cloud, which runs on Supabase.
- **Publishable key** is the public key your site uses to talk to the backend. Browsers see it anyway. It is safe in the code because your database's access rules decide what it can reach.
- **Secret key** is the master key to your backend. It opens everything and ignores those access rules, so it must never be in your website's code.
- **Build** means turning your code into a finished app the internet can open.
- **Domain** is your own address, like myapp.com.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep it running, Starter at $5/month is enough for the website alone; your own domain needs Pro at $20/month. See the [pricing page](https://aidrop.it/pricing).
- A Lovable project connected to GitHub, as Lovable's [GitHub sync guide](https://docs.lovable.dev/integrations/github) explains. The sync works both ways and is available on all Lovable plans.
- Your agent connected to aidrop.it. See the [quickstart](/quickstart).
- Access to your domain's settings, if you want your own address.
## Say this to your agent
Replace the parts in angle brackets before you paste.
```text title="Say this to your agent"
Move the website part of my Lovable app to aidrop.it. The code is on GitHub: . The backend (database, sign-in, storage, edge functions) stays on Lovable Cloud / Supabase. Do not move or change it.
Read aidrop.it's runtime rules before you write anything and follow them. Build from my GitHub repository if aidrop.it can see it; if it can't, give me the link to install aidrop.it's GitHub app. Put the Service in a new aidrop.it Project called "".
Work out which kind of Lovable app this is. An older React + Vite app builds to plain files: serve them as a static site, and send every unknown path to index.html so page links and refreshes work. A newer TanStack Start app (Lovable, May 2026 on) has a server part: build it with Nitro's node-server preset and run it as a Node app. Its outgoing requests must go through aidrop.it's proxy: use Node 22.21 or newer with NODE_USE_ENV_PROXY=1.
The build cannot see Project secrets. The public Supabase URL and publishable key must be in the repository (Lovable keeps them in .env). Keep them there. Never put a service role or other secret key in frontend code. Row Level Security must stay on. If the server part needs a secret, ask me for it, store it with project_secret_set, list its name in required_secret_names and read it at run time. Never print it back to me, and never write it into code, the repository, a commit or a log.
When it runs, tell me the link, which kind of app it was, and exactly which sign-in addresses I must add in Lovable (Cloud > Users > Auth settings > Advanced > Redirect URLs) or in Supabase.
```
## What your agent does to move the Lovable site
1. Reads your code and checks which kind of Lovable app it is. Apps made from 13 May 2026 on include a small server part; older ones are plain website files.
2. Writes a short build recipe that fits aidrop.it's rules and saves it with your code.
3. Builds the app on aidrop.it and waits until it runs. A blank page or a failed build usually means the public backend values did not reach the build, so that is what it checks first.
4. Gives you the link and the sign-in addresses to add in Lovable.
## After it runs: two things only you can do
**Allow sign-in from the new address.** Lovable only lets users sign in from addresses it knows. In Lovable, open More, then Cloud, then Users, then Auth settings, expand Advanced, and add your new link (and later your domain) under Redirect URLs. With your own Supabase project, add them in its sign-in settings instead. Lovable's [sign-in settings guide](https://docs.lovable.dev/features/authentication) shows the screen.
**Connect your domain (optional, Pro plan).** Say "connect myapp.com to this site". Your agent tells you one record to add where you bought the domain, then switches the domain on. If the domain pointed to Lovable before, that record is replaced. Your Lovable copy keeps its lovable.app address.
Once the site runs here, you can also
[add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website):
a chat bubble that answers visitors from your own FAQ, with its AI key kept
out of your Lovable code.
## Check the moved site
- Open the link. The home page loads.
- Click through a few pages, then refresh one of them. It should not show "not found".
- Sign in with a test account. If it fails, check the sign-in addresses above.
- Add or change something. It also appears in Lovable, because the data is shared.
## When something goes wrong
| What you see | What to tell your agent |
| --- | --- |
| A blank white page | "The page is blank. Check that the public Supabase values reached the build." |
| "Not found" when you refresh a page | "Refreshing a page gives not found. Send unknown paths to the app." |
| Sign-in fails or sends you back to lovable.app | Add the new link in Lovable's sign-in settings, then try again. |
| A Lovable edit does not appear | "Rebuild the site from the latest code on GitHub." |
| The build keeps failing | "Read the build log, fix the cause and tell me what it was." |
## FAQ
### Can I host a Lovable app somewhere other than Lovable?
Yes. Lovable says you own your code and can host it wherever you choose. Older Lovable apps are plain website files that any host can serve. Apps made from 13 May 2026 on include a server part, so the host must run a small server. Your backend can stay on Lovable Cloud.
### Does my database move with the website?
No. The database, user accounts, file storage and backend functions stay on Lovable Cloud, and the moved website keeps using them. Moving that backend is a separate job, which Lovable's [hosting outside Lovable guide](https://docs.lovable.dev/tips-tricks/external-deployment-hosting) covers. Keep your Lovable account: it still runs your backend.
### Is it safe that the publishable key is in my code?
Yes, if your database's access rules are switched on. Supabase made the publishable key for browsers and says it is safe to show; the access rules decide what it can reach. The secret key skips every rule, so it must never be in website code. Your agent is told to keep it out.
### Is hosting outside Lovable cheaper?
For the website alone, often yes: $5 a month here at an aidrop.it address, or $20 with your own domain, against Lovable's Pro plan from $25 a month for a custom domain. But if you keep building in Lovable, you still pay for the Lovable plan you build on. The move is about owning where the site runs, not only the price.
### Can I keep building in Lovable after moving?
Yes. Lovable keeps syncing your edits to GitHub. On aidrop.it a new version goes live when your agent rebuilds, not on its own. So the habit is: edit in Lovable, then tell your agent "rebuild my site".
## Related
- [Put a landing page online](/playbooks/put-a-landing-page-online)
- [Move an app from Base44 or Replit](/playbooks/host-a-base44-or-replit-app)
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [Bring a repository you already have](/bring-your-repository)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Move an app from Base44 or Replit to your own hosting
Source: https://docs.aidrop.it/playbooks/host-a-base44-or-replit-app
> Take an app built in Base44 or Replit to hosting you control. Your AI agent moves the code and data; this page says honestly what comes along and what stays.
**From Replit, the whole app can move**: code, database and settings. A few
Replit-only services must be replaced. **From Base44, only the website part
leaves.** A Base44 export still depends on Base44's servers for its data, user
sign-in and backend logic, and keeps doing so unless your agent rebuilds them.
You built an app in [Base44](https://base44.com) or [Replit](https://replit.com)
and want it on hosting you control. Your AI coding agent (Claude Code, Codex or
Cursor) moves it to aidrop.it from one paragraph. A Base44 website runs on
Starter at $5 a month; a Replit app with a database needs Pro at $20 a month.
## What you will have at the end
- Your app at its own secure link, and on your own domain if you want.
- From Replit: your data in a database next to the app.
- From Base44: the website on your hosting, still using Base44 for data and sign-in.
## Words you will meet
- **Front end** is the part people see in the browser: pages, buttons, forms.
- **Backend** is the hidden part: the database, user accounts and server logic.
- **Database** is where the app keeps its records.
- **Secret** is a private value, like an API key. Replit keeps them in its Secrets tool; on aidrop.it your agent saves them as secrets in your project, never in the code.
- **Published app** is the live copy on Replit, with its own production database.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep it running, Starter at $5/month fits a Base44 website. A Replit app with a database, or your own domain, needs Pro at $20/month; Starter has no database. See the [pricing page](https://aidrop.it/pricing).
- **Base44:** the code on GitHub through Base44's [GitHub sync](https://docs.base44.com/developers/app-code/local-development/github).
- **Replit:** the code on GitHub or [downloaded as a zip](https://docs.replit.com/help/projects-and-files).
- Your agent connected to aidrop.it. See the [quickstart](/quickstart).
If what you built is a single page, such as a waitlist or a product page, it
is simpler to [put a landing page online](/playbooks/put-a-landing-page-online)
from fresh files. If your Replit app is a Python dashboard made with
Streamlit, [deploy a Streamlit app](/playbooks/deploy-a-streamlit-app) has
the exact steps.
## Say this to your agent
Pick the block for your platform and replace the parts in angle brackets before you paste.
For a Base44 app:
```text title="Say this to your agent (Base44)"
Move the front end of my Base44 app to aidrop.it. Code: GitHub (React + Vite, Base44 SDK). The backend (entities, sign-in, functions, integrations) stays on Base44.
Read aidrop.it's runtime rules and follow them. Serve the build as a static site; send unknown paths to index.html. The build cannot see Project secrets, so make sure the Base44 app ID and server address reach it from the repository (they are public IDs). Check that sign-in works from the new address.
Tell me the link, what still runs on Base44, and what moving each of those pieces would take.
```
For a Replit app:
```text title="Say this to your agent (Replit)"
Move my Replit app to aidrop.it. The code is on GitHub: (or in the zip at ). Read .replit for the run command and the dependency files for what it needs. Read aidrop.it's runtime rules before writing anything and follow them.
List every Replit-only piece (Replit Auth, App Storage, Replit Database, connectors, REPLIT_* variables) and your replacement for each before you change code.
aidrop.it apps cannot open PostgreSQL connections to outside databases (only web ports leave), so move the data. Check the Project's backing services and create PostgreSQL only after I confirm. Dump the production database from this machine with pg_dump, using the connection string I give you. aidrop.it's database has no public address: load small data with the database query tool in batches, or propose a one-off import if it is big.
Secrets: ask me for each value the app needs from Replit's Secrets tool, 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. Report the link, what you replaced and what is left.
```
## What your agent does during the move
1. Reads your code, lists what depends on the old platform, and asks before adding a database or replacing sign-in.
2. Builds the app on aidrop.it. Leftover Replit settings and missing Base44 IDs are the usual reasons a first build fails, so it checks those before anything else.
3. For Replit, moves your data into the new database and checks it arrived.
4. Gives you the link and a list of what was replaced and what stays.
## What does not come along
**From Base44**, the export is the front end. Base44's [backend overview](https://docs.base44.com/developers/backend/overview/features) lists its own database, sign-in, backend functions and integrations, which your website reaches through Base44's code library. Those keep running on Base44, so you keep your Base44 account. Moving everything means your agent rebuilds the backend: a real project, not a copy. Base44 can [export each data table](https://docs.base44.com/Building-your-app/Managing-your-app-data) as a spreadsheet for your agent to load. Sign-in does not come with it, so plan for users to set new passwords.
**From Replit**, these are Replit services, and your agent replaces them:
- Sign in with Replit (Replit Auth), which logs people in with Replit accounts. Your agent swaps in another sign-in service.
- App Storage for uploaded files. aidrop.it keeps no files for apps, so they go to a storage service or the database.
- Secret values. You copy each one from Replit's Secrets tool and paste it into the chat with your agent once, when it asks. The agent saves it as a secret in your aidrop.it project and never shows it again.
- Data in an app you never published. It sits in Replit's [development database](https://docs.replit.com/features/data-and-storage/connection-details), which only the app on Replit can reach. Ask Replit's Agent to export the tables to files first.
## Check the moved app
- Open the link. The home page loads, and refreshing a page works.
- Sign in with a test account.
- Open a page that shows your data. The records match the old app.
- Add something, restart the app from your agent, and check it is still there.
## When something goes wrong
| What you see | What to tell your agent |
| --- | --- |
| A blank page (Base44) | "The page is blank. Check the build received the Base44 app ID." |
| Sign-in sends you to Base44 and fails | "Sign-in fails from the new address. Find out what Base44 needs to allow it." |
| Database errors (Replit) | "Make sure the app reads the new database, not Replit's." |
| Uploaded files disappear after a restart | "Files saved on the app's disk vanish. Store them somewhere lasting." |
## FAQ
### Can I export my code from Base44?
Yes. Base44's GitHub sync copies your app's code to GitHub; it needs the Builder plan or higher, as of October 2026. You get the website's code. The data, sign-in and backend functions stay on Base44's servers, so the exported site keeps depending on Base44.
### How do I move a Replit app to another host?
Put the code on GitHub or download it as a zip. Copy each secret from Replit's Secrets tool to the new host by hand. Copy the production database with standard PostgreSQL tools into the new one. Replace Replit-only services such as Replit Auth and App Storage.
### Replit vs Base44: which is easier to leave?
Replit, for most apps. A Replit app is ordinary code plus a standard PostgreSQL database, so both can move. A Base44 backend is Base44's own service, so leaving fully means rebuilding it. On aidrop.it your agent does either move and tells you first what stays behind.
## Related
- [Host your Lovable app](/playbooks/host-a-lovable-app)
- [Put a landing page online](/playbooks/put-a-landing-page-online)
- [Deploy a Streamlit app](/playbooks/deploy-a-streamlit-app)
- [Bring a repository you already have](/bring-your-repository)
- [Taking your work with you](/taking-your-work-with-you)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Build a Telegram bot with Claude Code, running 24/7
Source: https://docs.aidrop.it/playbooks/telegram-bot-with-claude-code
> Build a Telegram bot with Claude Code and keep it answering 24/7 with your laptop closed. Paste one paragraph; your agent writes, deploys and checks it.
You can have a Telegram bot that answers around the clock, built and put online
by Claude Code, Codex or Cursor from one paragraph you paste. You create the
bot inside Telegram, give its key to your agent once, and your agent
does the rest: it writes the bot, puts it online and connects it to Telegram.
Plan on about 20 minutes, mostly waiting for the first build. Keeping it
online costs $5 a month on the Starter plan, after a free 7-day trial.
**This page builds a bot that runs on its own, 24/7.** It is not about
controlling Claude Code from Telegram. For that, Anthropic has a Telegram
[channel for Claude Code](https://code.claude.com/docs/en/channels), a
research preview that only answers while Claude Code runs on your computer.
If you want both, make two bots: one bot cannot serve both.
The bot lives on aidrop.it, not on your computer. Telegram passes every new
message straight to the bot's own web address, so nothing has to stay open on
your side. If you are a developer and want the technical side of that, read
our [Telegram webhook guide on the blog](https://aidrop.it/blog/deploy-a-telegram-bot/).
Not sure you need your own bot at all? A ready-made assistant may be enough;
[Grok vs your own bot](/playbooks/grok-vs-your-own-bot) compares the cost and
control of each. And if what you want is a personal AI assistant you chat with,
not a bot you write, you can [run OpenClaw instead of writing a bot](/playbooks/run-openclaw-in-the-cloud)
or run [Hermes Agent](/playbooks/run-hermes-agent-in-the-cloud).
## What you will have at the end
- A Telegram bot, found by its name, that replies to /start within a second or two.
- A bot that keeps answering when your laptop is closed and after every update.
- The bot's code saved in a repository, so your agent can change it later.
## Words you will meet
- **BotFather** — Telegram's own official bot that creates new bots for you.
- **Bot token** — the key Telegram gives your bot. Anyone who has it can act as your bot, so treat it like a password.
- **Webhook** — the web address Telegram calls each time someone writes to your bot.
- **Secret** — where the bot token lives: a private value in your aidrop.it project that the bot reads when it starts. It never appears in the bot's code.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep the bot running after that, Starter at $5/month is enough, because this bot needs no database.
- Your agent connected to aidrop.it. The [Quickstart](/quickstart) shows how.
- A Telegram account.
- A bot token. In Telegram, open [@BotFather](https://t.me/BotFather), send it /newbot, choose a name and a username ending in "bot", and copy the token it gives you ([Telegram's guide](https://core.telegram.org/bots/tutorial)).
Keep the token to yourself until your agent asks for it. Then paste it into
the chat with your agent once. The agent saves it as a secret in your aidrop.it
project, where only your bot can read it, and never shows it again or writes it
into the code. Under **Secrets** in your Project on the aidrop.it dashboard you
can check which secrets exist, by name only.
## Say this to your agent
```text title="Say this to your agent"
Build me a Telegram bot and run it on aidrop.it, 24/7. Use my existing aidrop.it Project, or create one called "Telegram bot" if I have none.
What it does: when someone sends /start in a private chat, it replies "Hello from my bot." It ignores everything else.
How it works:
- Use the official Telegram Bot API with a webhook, not polling.
- Protect the webhook with a random secret token and reject any request that does not carry it.
- The bot registers its own webhook when it starts, using its public aidrop.it address. After the first build, store that address as a Project secret and build again.
- Read aidrop.it's runtime rules before writing code and follow them. Outgoing requests must go through the proxy the platform sets; make sure your HTTP client uses it (Node's built-in fetch does not by default).
Secrets: before building, ask me for the bot token, and make up the webhook secret token yourself. 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.
Build it, check it runs, fix anything that fails, and tell me when I can send /start. Report the bot's address and what you checked.
```
## What your agent does to put the Telegram bot online
1. Picks your aidrop.it project, or creates one.
2. Asks you for the bot token and saves it as a secret, together with a webhook password it makes up itself.
3. Writes the bot, including a small "I'm alive" page that aidrop.it checks to know the bot is running.
4. Saves the code to a repository on aidrop.it and builds it there.
5. Follows the first build to the end. A bot that does not start usually has a missing secret or a wrong token, and the agent sorts that out with you before trying again.
6. Gives the bot its public web address, and the bot tells Telegram to deliver messages there.
## Check that your Telegram bot answers
- Your agent says the bot is running and gives you its address.
- Open the bot in Telegram and send /start. It answers "Hello from my bot."
- Close your laptop and message the bot from your phone. It still answers.
## When the bot does not answer
| What you see | What to tell your agent |
| --- | --- |
| The agent says the build is waiting for secrets | "Which secret names is the build waiting for?" Then give it the bot token again and say "Store it under that name and build again." |
| The build finished, but aidrop.it says the app is not running | "Read the logs, find why the bot does not start or its "I'm alive" page fails, fix it and build again." |
| The bot never answers /start | "The bot gets no messages or cannot reply. Check the webhook is set up and that the bot's outgoing requests can leave aidrop.it." |
| The bot crashes, saying it cannot write a file | "The app's disk is read-only. Write nothing to disk; keep anything lasting in a database." |
| The bot sometimes answers twice | "Telegram retried a slow reply. Answer Telegram at once and skip messages you already handled." |
## FAQ
### Should my Telegram bot use polling or a webhook?
Both are official. With polling, the bot keeps asking Telegram for new messages.
With a webhook, Telegram calls the bot whenever a message arrives, which suits a
bot living at a public web address. One bot cannot do both at once: while a
webhook is set, polling stops working
([Telegram Bot API](https://core.telegram.org/bots/api#getting-updates)).
### What do I do if my bot token leaks?
Open @BotFather and send it /token to get a new token for your bot
([Telegram docs](https://core.telegram.org/bots/features#botfather)). Give the
new token to your agent, ask it to store it in place of the old one, then ask it
to build the bot again so it uses the new key.
### Can Claude Code build an AI Telegram bot that answers with Claude?
Yes. Ask your agent to send each message to the Claude API and reply with the
answer. You will need an Anthropic API key, which your agent asks you for and saves as one more secret. Ask it to
answer Telegram at once and send the reply when the model is done.
### Can my bot send a message on its own, every morning?
Yes. A task that runs on a timetable is called a cron job; our page on
[what a cron job is](/playbooks/what-is-a-cron-job) explains how to write the
timetable. Ask your agent to add one to the bot, for example "send me the
weather at 8 every morning".
### Can I host a Telegram bot for free?
The Telegram Bot API costs nothing, and a webhook bot uses almost no computer
time while it waits. What you pay for is a server that is always reachable, so
Telegram can deliver each message the moment it is sent. On aidrop.it the
first 7 days are free; after that, Starter at $5 a month runs this bot. All
plans are on the [pricing page](https://aidrop.it/pricing).
## Related
- [Build a WhatsApp bot with the WhatsApp Cloud API](/playbooks/whatsapp-bot-cloud-api)
- [Host a Discord bot 24/7](/playbooks/host-a-discord-bot-24-7)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Build a WhatsApp bot with the WhatsApp Cloud API
Source: https://docs.aidrop.it/playbooks/whatsapp-bot-cloud-api
> Build a WhatsApp bot on Meta's official Cloud API and keep it online 24/7. Paste one paragraph; your AI agent writes, deploys and checks the bot.
You can have a WhatsApp bot that answers day and night, using Meta's official
**WhatsApp Cloud API**. You set up a free Meta developer app with a test
number, paste one paragraph into Claude Code, Codex or Cursor, and give the
agent a few keys when it asks. Your agent writes the bot and puts it online; you
paste its address into Meta's dashboard. Plan on about 30 minutes.
What it costs: hosting is $5 a month on the Starter plan, after a free 7-day
trial. On Meta's side, replies to people who wrote to you first are free, as of
October 2026; the [FAQ](#how-much-does-the-whatsapp-business-api-cost) below
says which messages Meta charges for.
The bot lives on aidrop.it, not on your phone or laptop. Meta passes each
message to the bot's web address; the bot answers through Meta.
**Use the official API, not a "WhatsApp Web" library.** Tools like
whatsapp-web.js or Baileys log in as an ordinary account through a QR code.
whatsapp-web.js [itself warns](https://github.com/pedroslopez/whatsapp-web.js)
that WhatsApp does not allow this, so your number can be blocked. The login also
lives on the app's disk, which aidrop.it wipes on restart, so you would rescan
after every update.
## What you will have at the end
- A WhatsApp number that replies to any message you send it, within seconds.
- A bot that answers with your laptop closed and after every update.
- The bot's code saved in a repository, so your agent can change it later.
## Words you will meet
- **WhatsApp Cloud API** — Meta's official way for a program to send and receive WhatsApp messages.
- **Access token** — the key your bot sends messages with. The first one Meta gives you is short-lived.
- **Webhook** — the web address Meta calls each time someone writes to your number.
- **Verify token** — a password you make up and give to both Meta and your bot.
- **App secret** — a key Meta uses to sign each message, so your bot can ignore fakes.
- **Secret** — where your four WhatsApp keys live: private values in your aidrop.it project that the bot reads when it starts, never written into its code.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep the bot running after that, Starter at $5/month is enough, because this bot needs no database.
- Your agent connected to aidrop.it, as in the [Quickstart](/quickstart).
- A Facebook account to sign in to [Meta for Developers](https://developers.facebook.com/).
- A Meta app, which holds your WhatsApp keys. Create it with the use case **Connect with customers through WhatsApp** and follow Meta's [Get Started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started). You get a free test number, its phone number ID and a temporary access token.
- Your own WhatsApp number on the test number's short list of allowed recipients.
Your agent will ask you for four values: the access token, the phone number
ID, the app secret (Meta's app dashboard, Settings, Basic) and a verify token
you make up. Paste each one into the chat with your agent once, when it asks.
The agent saves them as secrets in your aidrop.it project, where only your bot
can read them, and never shows them again or writes them into the code. Under
**Secrets** in your Project on the aidrop.it dashboard you can check which
secrets exist, by name only.
## Say this to your agent
```text title="Say this to your agent"
Build me a WhatsApp bot on the official WhatsApp Cloud API and run it on aidrop.it, 24/7. Use my existing aidrop.it Project, or create one called "WhatsApp bot" if I have none.
What it does: it replies "You said: " plus the text to every incoming text message. It ignores delivery statuses and other message types.
How it works:
- Answer Meta's webhook check (hub.mode, hub.verify_token, hub.challenge) using my verify token.
- Check the X-Hub-Signature-256 header on every incoming message against my app secret, over the raw body, and reject anything that does not match.
- Answer Meta right away; it retries unanswered messages.
- Do not use whatsapp-web.js, Baileys or any unofficial client.
- Read aidrop.it's runtime rules before writing code and follow them, including the outbound proxy.
Secrets: ask me for the access token, phone number ID, app secret and verify token, 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. Never log message text either.
Build it, check it runs, fix what fails. Then give me the webhook address to paste into Meta and say what you checked.
```
## What your agent does to put the WhatsApp bot online
1. Picks your aidrop.it project, or creates one.
2. Asks you for the four WhatsApp values and saves each one as a secret.
3. Writes the bot, plus a small "I'm alive" page aidrop.it checks to see it is running.
4. Saves the code to a repository on aidrop.it and builds it there.
5. Follows the build to the end. If the bot will not start, the usual cause is a missing or wrong value, and the agent tells you which one to give it again.
6. Gives you the webhook address for Meta.
Then you finish in Meta's app dashboard. Open the WhatsApp **Configuration**
panel (under Use cases, Customize, for apps made with the WhatsApp use case).
Paste the address into **Callback URL** and your made-up password into
**Verify token**, then save. Meta checks the address with your bot on the
spot ([Meta's webhook setup guide](https://developers.facebook.com/docs/graph-api/webhooks/getting-started)).
Last, subscribe to the **messages** field in the list that appears.
## Check that your WhatsApp bot replies
- Send "hi" from your phone to the test number. The bot answers "You said: hi".
- Close your laptop and send another message. It still answers.
- Try again the next day. If it went quiet, the temporary token expired: see the FAQ.
## When something goes wrong
| What you see | What to tell your agent |
| --- | --- |
| Meta says the callback URL could not be verified | "Meta's webhook check fails. Check the bot is running and answers the check with my verify token." |
| Your message arrives but no answer comes back | "The bot receives messages but cannot send. Read the logs and check its outgoing requests can leave aidrop.it." |
| The bot stops answering a few hours after setup | Make a permanent token (see the FAQ), give it to your agent, then say "Store it in place of the old one and build again." |
| The same answer arrives twice | "Meta re-sent a message. Answer Meta at once and skip messages you already handled." |
## FAQ
### How do I get a permanent WhatsApp Cloud API access token?
The token on the Get Started page is temporary: Meta says you will have to make
a new one every few hours. For one that lasts, create a **system user** in
Meta's Business settings, give it your app and WhatsApp account, and generate a
token with three permissions ticked: business_management,
whatsapp_business_management and whatsapp_business_messaging. Give it to your
agent, and ask it to store it in place of the temporary token and build again. Meta's
[access token guide](https://developers.facebook.com/docs/whatsapp/access-tokens)
shows each step.
### How much does the WhatsApp Business API cost?
As of October 2026, Meta charges per message, a model in place since July 1,
2025. Ordinary replies sent within 24 hours of a customer's last message are
free, and so are utility templates (order or account updates) sent in that
window. Marketing templates are always charged, and utility templates are
charged outside the window. Rates vary by country: see
[Meta's WhatsApp pricing page](https://developers.facebook.com/docs/whatsapp/pricing).
### Can I run a WhatsApp bot for free?
The messages can be free: a bot that only answers people who wrote first stays
inside Meta's free 24-hour window. The always-on server that receives Meta's
calls is the part that costs money. On aidrop.it the first 7 days are free;
after that, Starter at $5 a month runs this bot. All plans are on the
[pricing page](https://aidrop.it/pricing).
### Can I build the same bot for Discord or Telegram?
Yes, the steps are close. Discord bots work differently: they keep a live
connection open instead of waiting for calls, which is why
[hosting a Discord bot 24/7](/playbooks/host-a-discord-bot-24-7) has its own
page. If you are still choosing between a ready-made assistant and a bot of your
own, [Grok vs your own bot](/playbooks/grok-vs-your-own-bot) compares what each
really costs.
## Related
- [Build a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [All playbooks](/playbooks)
---
# Host a Discord bot 24/7 with your AI agent
Source: https://docs.aidrop.it/playbooks/host-a-discord-bot-24-7
> Keep a Discord bot online 24/7 without your computer. Paste one paragraph into Claude Code, Codex or Cursor; your agent writes, deploys and checks the bot.
You can have a Discord bot that stays online around the clock, even with your
computer switched off. You create the bot in Discord's Developer Portal, paste
one paragraph into Claude Code, Codex or Cursor, and give the agent the bot's
key when it asks. Your agent writes the bot, puts it online and tells you when to
try it. Plan on about 20 minutes.
Hosting it costs $5 a month on the Starter plan, after a free 7-day trial. Why
pay, when free hosts exist? A Discord bot sits on an open line to Discord and
never gets visitors, and free tiers are built to stop exactly that: Render's
free plan, for example, puts an app to sleep after 15 minutes without visits
and caps it at 750 hours a month ([Render's docs](https://render.com/docs/free),
as of October 2026). A sleeping bot shows as offline. On a paid plan it simply
keeps running.
There are two kinds of Discord bot, and it helps to pick before you start. A
**classic bot** stays connected to Discord, so it sees messages as they are
written and can react to them. A **slash-command bot** only answers commands
people type, like /ask. This page builds a classic bot, because that is what
most people mean; the slash-command kind is covered in the FAQ.
One honest limit: a bot here cannot join voice channels to talk or play music.
Voice needs a kind of connection that aidrop.it does not let out. Text works
fully.
## What you will have at the end
- A bot in your Discord server that shows as online and answers "!ping" with "Pong!".
- A bot that keeps running with your computer off and after every update.
- The bot's code saved in a repository, so your agent can change it later.
## Words you will meet
- **Developer Portal** — Discord's website where you create and configure bots.
- **Bot token** — the password of your bot. Anyone who has it can act as your bot.
- **Intent** — a permission switch in the Developer Portal. Your bot needs the one that lets it read the text of messages.
- **Invite link** — a link that adds your bot to a server you manage.
- **Secret** — where the bot token lives: a private value in your aidrop.it project that the bot reads when it starts, so the token never sits in the code.
- **Slash command** — a command that starts with /, which Discord shows in a menu as people type.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card. To keep the bot running after that, Starter at $5/month is enough, because this bot needs no database.
- Your agent connected to aidrop.it, as in the [Quickstart](/quickstart).
- A Discord account and a server where you can add bots.
- A bot. In the [Developer Portal](https://discord.com/developers/applications), click **New Application** and name it. In the **Bot** section, click **Reset Token** and copy the token; Discord shows it only once. On the same page, turn on the switch named **Message Content Intent**, so the bot can read what people write.
- The bot in your server. Under **OAuth2**, **URL Generator**, tick **bot** and the permissions to view channels, send messages and read message history. Open the link it makes and choose your server.
Keep the token to yourself until your agent asks for it. Then paste it into
the chat with your agent once. The agent saves it as a secret in your aidrop.it
project, where only your bot can read it, and never shows it again or writes it
into the code. Under **Secrets** in your Project on the aidrop.it dashboard you
can check which secrets exist, by name only.
## Say this to your agent
```text title="Say this to your agent"
Build me a Discord bot and run it on aidrop.it, 24/7. Use my existing aidrop.it Project, or create one called "Discord bot" if I have none.
What it does: it replies "Pong!" when someone writes "!ping" in a channel it can see. It uses the message content intent, which I have switched on in the Developer Portal.
How it works:
- Python with discord.py 2.x, as a normal Gateway bot. Do not use discord.js: its Gateway connection has no proxy option.
- Read aidrop.it's runtime rules before writing code and follow them. The bot can only reach the internet through the proxy in HTTPS_PROXY. discord.py does not read it on its own: pass it as proxy= to the Client, which routes both the Gateway connection and API calls through it.
- The bot must also serve a small health page on the platform's port, or aidrop.it treats it as not running. Run the web server and the bot in the same process.
- Log reconnects, never the token.
Secrets: ask me for the bot token, store it with project_secret_set under a clear name, and list that name in required_secret_names when you build. Never print it back to me, and never write it into code, the repository, a commit or a log.
Build it, check it runs and shows as online, fix anything that fails, and tell me when I can type !ping. Report what you checked.
```
## What your agent does to keep the Discord bot online
1. Picks your aidrop.it project, or creates one.
2. Asks you for the bot token and saves it as a secret.
3. Writes the bot, plus a small "I'm alive" page that aidrop.it checks to see it is running.
4. Saves the code to a repository on aidrop.it and builds it there.
5. Follows the build until the bot shows as online in Discord. If it does not connect, the agent reads the bot's log, which usually names a wrong token or a blocked connection, and fixes it.
6. Tells you the bot is online.
## Check that the bot stays online
- In your server's member list, the bot shows as online.
- Type !ping in a channel the bot can see. It answers "Pong!".
- Turn your computer off and try from your phone. It still answers.
## When the bot is offline or silent
| What you see | What to tell your agent |
| --- | --- |
| The build finished, but aidrop.it says the app is not running | "The bot needs a health page on the platform's port. Serve one next to the bot and build again." |
| The bot never shows as online | "The bot cannot reach Discord. Read the logs and make sure its connection to Discord can leave aidrop.it." |
| The bot is online but ignores !ping | Check that the switch named "Message Content Intent" is on in the Developer Portal, then tell the agent "The switch is on, restart the bot." |
| The logs say the token is invalid | Reset the token in the Developer Portal, give the new one to your agent, then say "Store it in place of the old one and build again." |
## FAQ
### What is a slash-command bot, and should I build one instead?
It is a bot that only answers commands like /ask. Discord sends each command
to the bot's web address and expects an answer within 3 seconds, or a "thinking"
reply first ([Discord docs](https://docs.discord.com/developers/interactions/receiving-and-responding)).
It needs no open line to Discord, so it is simpler to run. The trade-off: it
cannot read ordinary messages, see who is online or join voice. Pick it if
commands are all you need.
### Where do I find my Discord bot token?
In the Developer Portal, open your application, go to **Bot** and click
**Reset Token**. Discord shows the new token once, so copy it straight away.
If a token ever leaks, reset it at once. Then give the new one to your agent,
ask it to store it in place of the old one and build the bot again.
### Can I make a Discord AI bot that answers with Claude or ChatGPT?
Yes. Ask your agent to send each message, or each /ask command, to the AI
model's API and post the answer. You need an API key from the model's maker,
which your agent asks you for and saves as one more secret. The same idea works outside Discord, as an
[AI chatbot for your website](/playbooks/add-an-ai-chatbot-to-your-website).
If you are unsure whether to build a bot at all, [Grok vs your own bot](/playbooks/grok-vs-your-own-bot)
compares a ready-made assistant with one you own, cost included.
### Is there free Discord bot hosting that runs 24/7?
Discord charges nothing for bots. The catch is the open line: a classic bot is
offline the moment its connection stops, so it needs a server that never sleeps.
Free tiers sleep or run out of hours, as above. On aidrop.it the first 7 days
are free; after that, Starter at $5 a month keeps this bot online. All plans are
on the [pricing page](https://aidrop.it/pricing).
## Related
- [Build a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
- [Build a WhatsApp bot with the WhatsApp Cloud API](/playbooks/whatsapp-bot-cloud-api)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Grok vs your own bot: what a chatbot really costs
Source: https://docs.aidrop.it/playbooks/grok-vs-your-own-bot
> Grok subscription or your own AI chatbot? What each really costs a month, with xAI's current prices, a worked example, and what you control in each.
**Grok** is xAI's ready-made AI assistant: you pay a monthly fee and start
chatting in its app, on its website or on X. **Grok Bot** is a separate xAI
product, an AI teammate that works on its own cloud computer to finish tasks
for you; it comes with the SuperGrok plans. **Your own bot** is a program your
coding agent writes for you, which can use Grok's models or any other AI
behind it. Pick Grok when the assistant is for you and your team. Pick your
own bot when your customers should talk to it, in your channel, with your
rules.
In short: Grok costs a flat $30 a month for SuperGrok. A customer bot of your
own costs its AI usage, about $21 to $37 a month for 1,000 conversations in
the example below, plus hosting. Prices are xAI's, as of October 2026.
aidrop.it sells hosting for the "your own bot" option.
## What each option costs
### Grok, the subscription
Grok's plans on [xAI's price page](https://x.ai/pricing): a Free plan with
usage limits, SuperGrok at $30 a month, SuperGrok Plus at $100 a month, and
[Grok Business](https://x.ai/news/grok-business) at $30 per user a month.
### Your own bot: a worked example
Your own bot pays the AI model for each reply. xAI's
[API prices](https://docs.x.ai/developers/pricing) per million tokens: Grok 4.3
costs $1.25 for text it reads and $2.50 for text it writes; Grok 4.7 costs $2
and $6. xAI's pricing docs list no free API credits.
Each reply reads more than the customer's last message. The bot rereads its
instructions and the whole conversation so far, because it keeps the last 20
messages of every chat as memory. Our assumptions:
- 1,000 conversations a month, six customer messages in each.
- Instructions of about 1,500 tokens, customer messages of about 50, replies of about 250.
- So the sixth reply in a conversation reads about 3,000 tokens, and one conversation reads about 14,000 in total and writes 1,500.
- That is 14 million tokens read and 1.5 million written a month.
- On Grok 4.3: 14 × $1.25 + 1.5 × $2.50 = **about $21 a month**.
- On Grok 4.7: 14 × $2 + 1.5 × $6 = **about $37 a month**.
Longer conversations cost more, because every reply rereads all of them.
Text the model has just seen, such as the instructions, can be billed at a
lower "cached" rate ($0.20 per million on Grok 4.3), so bills often come in
under this.
Hosting comes on top. A bot that remembers conversations needs a database,
which on aidrop.it starts with Pro at $20 a month; a bot with no memory runs on
Starter at $5. All plans are on the [pricing page](https://aidrop.it/pricing).
## Words you will meet
- **Harness** — everything around the AI model: its instructions, tools,
memory, where people reach it, its limits, and the record of what it said.
The model is the engine; the harness is the rest of the car.
- **API** — a paid connection a program uses to talk to an AI model. You pay
for what you use, not a monthly fee.
- **Token** — a small piece of a word. AI companies charge per million
tokens. A thousand tokens is roughly 750 English words.
- **Database** — where a bot keeps past conversations.
## Side by side
| | Grok (subscription) | Your own bot |
| --- | --- | --- |
| Who talks to it | You and your team | Your customers |
| Price | Flat monthly fee | AI usage per message, plus flat hosting |
| Instructions and tools | What xAI ships | What you decide |
| Memory | Your chat history in Grok | Your own database |
| Where people reach it | Grok apps and site, and X | Telegram, WhatsApp, Discord, your website |
| AI model | Grok | Grok or another, switchable |
| Setup | Minutes | One paragraph to your coding agent, then a build |
## Who controls the bot's rules
With Grok, xAI builds the harness and you maintain nothing. You use it as
shipped, and you cannot put it in front of customers with your own rules,
tools and name.
With your own bot, every part is yours: the instructions, the tools, the
conversations in your database, and limits like "never promise a refund".
Someone has to build it, and that is your coding agent.
## Where each one can live
Grok lives where xAI puts it: its apps, its website and X. Grok Bot, described
in [xAI's Grok Bot docs](https://docs.x.ai/grok-bot/overview), works for you as
a teammate, not as a bot your customers message. Since May 2026 xAI also lets a
Grok subscription power [Hermes Agent](https://x.ai/news/grok-hermes), an
open-source personal agent that can chat over Telegram or WhatsApp. If a
personal agent is what you are after, you can also
[run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud).
Your own bot goes where your customers are, and it can switch models: start
on Grok, move elsewhere if price or quality changes.
## When Grok is the right choice
- The assistant is for you: writing, research, questions.
- You want it today, with nothing to maintain.
- Your team needs a shared plan. Grok Business promises no training on your
company's data.
## When your own bot is the right choice
- Customers talk to it in Telegram, WhatsApp or on your site, or in a community you [host a Discord bot 24/7](/playbooks/host-a-discord-bot-24-7) for.
- It must follow your rules and do things: find an order, save a lead.
- You want to keep the conversations and choose the model.
## Say this to your agent
```text title="Say this to your agent"
Build a customer-support bot as an aidrop.it Service in my Project (create a Project "Support bot" if I have none). Channel: Telegram, by webhook. Stack: your choice.
Read aidrop.it's runtime rules before writing code and follow them. Outbound calls go through the proxy in HTTPS_PROXY; make sure the HTTP client you use honours it.
Put the model behind ONE small interface (messages in, reply and optional tool calls out). First implementation: the xAI API, OpenAI-compatible, base URL https://api.x.ai/v1, key in XAI_API_KEY, model from LLM_MODEL (default grok-4.3). Another provider must mean one new file plus env vars.
Harness:
- System prompt in a repo file: answer only about my business, be brief, never promise refunds, offer a human.
- One tool: save_lead(name, contact, question) into the DB.
- Memory: last 20 messages per chat in PostgreSQL. Ask me before creating a database. Nothing on local disk.
- Limits: short replies, 30 messages per user per hour. Log conversations, never keys.
Secrets: ask me for XAI_API_KEY and TELEGRAM_BOT_TOKEN, and make up TELEGRAM_WEBHOOK_SECRET yourself. Store each one with project_secret_set under those names, and list them 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. Build, check it runs, fix from logs. Report the address, the model, and how to switch provider.
```
## What your agent does to build the support bot
1. Writes the bot and its instructions, and saves the code.
2. Asks you before adding a database for memory.
3. Builds it on aidrop.it and checks it answers on Telegram; a failed build usually means a missing key, and the agent asks you for it.
4. Gives you the link and tells you how to switch the AI model.
Full walkthroughs:
[Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code) and
[AI chatbot on your website](/playbooks/add-an-ai-chatbot-to-your-website).
## FAQ
### Is Grok free?
Yes, with limits. As of October 2026, xAI lists a Free plan and paid plans,
such as SuperGrok at $30 a month, for higher limits and more features. The API
that programs use is billed separately, per token, with no free credits listed
in xAI's pricing docs.
### Does xAI train on what my customers type?
For the API, xAI's [security FAQ](https://docs.x.ai/developers/faq/security)
says it never trains on your inputs or outputs without your explicit
permission. It keeps them 30 days for abuse checks, and offers a
zero-retention option. In the Grok apps you choose in settings whether your
chats are used for training, and Grok Business promises no training on your
data.
### What does it cost to run my own AI bot?
Two parts. The model is paid per use: about 1,000 support chats a month came
to roughly $21 to $37 on Grok in the example above. Hosting is a flat plan: on
aidrop.it, Pro at $20 a month for a bot that remembers conversations in a
database, or Starter at $5 for one that does not.
## Related
- [Build a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [Build a WhatsApp bot](/playbooks/whatsapp-bot-cloud-api)
- [Run Hermes Agent in the cloud](/playbooks/run-hermes-agent-in-the-cloud)
- [All playbooks](/playbooks)
---
# Put your AI agent online, running 24/7
Source: https://docs.aidrop.it/playbooks/put-your-ai-agent-online
> Put the AI agent your coding agent built online, running 24/7 with memory, a password and a spending cap. Claude Code, Codex or Cursor does the setup.
This page puts your own AI agent online: at its own web address, answering
around the clock, with memory, a password and a spending cap. You paste one
paragraph into your coding agent (Claude Code, Codex or Cursor), and it does
the building on aidrop.it. It needs a database, so after the free trial plan
on the Pro plan at $20 a month, plus what your AI provider bills for the model.
An **AI agent** is a program where an AI model decides the next step and uses
tools to finish a task, not just answer a question. A chatbot tells you how to
reschedule a booking; an agent looks up the booking, checks the calendar and
moves it.
## What you will have at the end
- Your agent at its own web address, answering around the clock.
- A simple chat page, plus a way for your website or other tools to call it.
- Conversations kept in a database, so a restart does not wipe them.
- A password in front of it, so strangers cannot run up your bill.
- A monthly spending limit at your AI provider as a second safety net.
## Words you will meet
- **API key**: a password from an AI company (Anthropic, OpenAI) that lets
your agent use its models. Every call is billed to you.
- **Agent SDK**: a ready-made toolkit for building agents, such as the
[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) or
the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/).
- **Access key**: the long password your agent asks for before it does
anything. You give it to the people and tools allowed to use the agent.
- **Secret**: where your model's API key and the access key are kept on
aidrop.it. The agent receives them when it starts; they never sit in its code.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a
7-day trial, no card. To keep the agent running, Pro at $20/month: it has
the database for the conversations. Starter has no database. Plans are on
the [pricing page](https://aidrop.it/pricing).
- Your coding agent connected to aidrop.it, as the
[Quickstart](/quickstart) shows.
- For the Claude Agent SDK, the 1 GB size, which starts at Pro. Anthropic's
[hosting guide](https://code.claude.com/docs/en/agent-sdk/hosting) names
1 GiB of memory per running agent as a starting point.
- An API key and a monthly spending limit at your provider. At Anthropic,
set the limit on a separate
[workspace](https://platform.claude.com/docs/en/manage-claude/workspaces);
the default one cannot have a limit. At OpenAI, set a
[project spend limit](https://developers.openai.com/api/docs/guides/spend-limits)
and switch on the hard limit, or calls continue past it.
## Say this to your agent
Replace the two parts in square brackets before you paste. In the first,
say in one sentence what your agent does and what it may touch, for example
"answers questions about my orders and may look them up in my shop". In the
second, name the toolkit it is built with; if you do not know, write "your
choice".
```text title="Say this to your agent"
Put my AI agent online as an aidrop.it Service. Read aidrop.it's runtime rules before writing anything and follow them.
What it does: [DESCRIBE THE AGENT AND ITS TOOLS].
Built with: [Claude Agent SDK / OpenAI Agents SDK / plain API calls].
- A small HTTP chat endpoint plus a minimal chat page, and a health endpoint that answers without calling the model.
- The address is public: require a long random access key on every request except health.
- Keep conversation history in the Project's PostgreSQL. Check what the Project already has first and ask me before creating a new instance. The app's disk is wiped on every restart, so nothing that must last may live in files.
- If you use the Claude Agent SDK: point its home and config folder at the temporary folder, and keep sessions in PostgreSQL through a SessionStore adapter. Size 1 GB.
- Cap each request: a maximum number of turns and of output tokens.
- All outbound calls go through the platform's HTTP proxy. Make sure the HTTP client honours it; Node's built-in fetch does not by default.
- Secrets: ask me for the model API key and the access key, 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.
Push it, build it, and tell me the address, the access key's secret name, and how to call it from my website.
```
## How your coding agent puts the agent online
1. Reads aidrop.it's rules, then writes the chat page, the address other
programs call, and the access key check.
2. Checks whether your project already has a database for the conversations,
and asks you before creating one.
3. Saves the code in a new repository on aidrop.it.
4. Asks you for the model's API key and the access key. Paste each one into
the chat once. Your coding agent saves them as secrets in your Project,
where only your agent can read them, and never shows them again or writes
them into the code. Under **Secrets** in your Project on the aidrop.it
dashboard you can check which secrets exist, by name only.
5. Builds it and waits until the "I'm alive" page answers without calling the
model. If the agent will not start, your coding agent reads the reason in
the log and tries again.
6. Gives you the address, the name of the access key, and a snippet for your
website.
## Check that your agent works online
- Open the address, enter the access key and give the agent a real task.
- Open it in a private window without the key. It refuses.
- Ask your coding agent to restart the app, then continue the chat. The agent
still remembers what you said.
- Your AI provider's usage page shows the calls you just made.
## Keep it safe and affordable
The address is open to the whole internet from the first deploy. Without
the access key, anyone who finds it can use your agent on your bill. Keep the
key long and random. If it leaks, make a new one, give it to your coding
agent and ask it to store it in place of the old one.
The provider's spending limit is the backstop: past it, the provider stops
answering and your agent shows an error instead of a bigger bill. More on
keys: [where do the secrets live](https://aidrop.it/blog/where-do-the-secrets-live/).
Your coding agent keeps changing this app after it is online. To make sure one bad
change cannot cost you the app or its memory, see
[how to stop your AI agent from deleting your project](/playbooks/stop-your-ai-agent-from-deleting-your-project).
aidrop.it takes daily snapshots. For an independent export, your coding agent copies the
conversations out whenever you ask; [taking your work with you](/taking-your-work-with-you)
lists what you can take and how.
## Other agents you can put online
You do not have to write the agent yourself. To run a ready-made assistant
you chat with from Telegram, [run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud)
or [run Hermes Agent in the cloud](/playbooks/run-hermes-agent-in-the-cloud),
which learns new skills as you use it.
If your agent should act on a timetable instead of when someone asks, start
with [what a cron job is and how to run one without a server](/playbooks/what-is-a-cron-job).
A [web scraper that runs on a schedule](/playbooks/run-a-web-scraper-on-a-schedule)
is a typical example. To let people talk to your agent in a Discord server,
see [host a Discord bot 24/7](/playbooks/host-a-discord-bot-24-7).
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
You do not need to understand the right-hand column; it is for your agent.
| What you see | What to tell your agent |
| --- | --- |
| The build is green but the app never starts | "Read the logs. The 'I'm alive' page must answer without calling the model." |
| Every answer is a timeout or connection error | "Make the model calls go through the platform's HTTP proxy." |
| It forgets the conversation after a restart | "Keep the chat history in the database, not in files." |
| The agent says it has no API key | "Which secret name does the app read the model key from? I will give you the key again; store it under that name and build again." |
| Strangers can use it | "Require the access key on every request." |
| The provider says the limit is reached | Nothing to fix. Raise the limit at the provider, or wait for next month. |
## FAQ
### How much does it cost to run an AI agent online?
Two bills. aidrop.it charges for the plan: Pro, $20 a month, has the database
your agent's memory needs. Your AI provider charges for every model call,
so that bill grows with every task the agent does. The spending limit at the
provider caps it.
### What is an AI agent platform?
A service that runs agents for you: it keeps them online, stores their keys
and memory, and shows what they did. Some build the agent in a visual
editor; others, like aidrop.it, host code you or your coding agent wrote.
### Do I need an agent SDK?
No. A simple agent is a loop: send the conversation to the model, run the
tool it asks for, send back the result, repeat. An SDK writes that loop for
you. The Claude Agent SDK gives you the same tools and loop that power
Claude Code, so it needs more memory than a plain loop: the 1 GB size.
### Where should my agent run?
Anywhere that stays on and keeps the conversations in a database rather than
on its own disk. On aidrop.it your coding agent builds it, stores its keys,
gives it a database and hands you the address, without you touching a server.
## Related
- [Add an AI chatbot to your website](/playbooks/add-an-ai-chatbot-to-your-website)
- [What is an MCP server](/playbooks/what-is-an-mcp-server)
- [Run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud)
- [Run Hermes Agent in the cloud](/playbooks/run-hermes-agent-in-the-cloud)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Run OpenClaw 24/7 in the cloud, without your Mac
Source: https://docs.aidrop.it/playbooks/run-openclaw-in-the-cloud
> Run OpenClaw 24/7 in the cloud while your Mac sleeps. Your AI coding agent sets it up on aidrop.it. What it costs, what a restart resets, other options.
[OpenClaw](https://github.com/openclaw/openclaw) is an open-source personal AI
assistant, under the MIT licence, that you talk to from chat apps such as
Telegram, WhatsApp or Discord. On a Mac it goes quiet whenever the laptop
sleeps. Here you paste one paragraph into your AI coding agent (Claude Code,
Codex or Cursor), and it moves OpenClaw to aidrop.it, where it answers you on
Telegram day and night.
Two facts decide whether this fits you:
- **Cost.** OpenClaw needs the 1 GB size, which starts at the Pro plan,
$20 a month. Your model provider bills its usage on top.
- **Memory.** The cloud copy starts fresh after every restart. It forgets your
chats and the notes it wrote for itself. What you keep in its setup files
comes back every time.
## What you will have at the end
- OpenClaw running in the cloud, whether your Mac is on or off.
- A Telegram bot that answers you and ignores everyone else.
- Your AI model key kept in your project's secrets, never in the code.
- The assistant's personality and standing notes saved with its code.
## Words you will meet
- **Bot token**: the password Telegram gives your bot. Whoever has it
controls the bot.
- **API key**: a password from an AI company (Anthropic, OpenAI, OpenRouter)
that lets OpenClaw use its models. Usage is billed to you.
- **Secret**: where aidrop.it keeps the bot token and the API key. OpenClaw
receives them when it starts, so they never appear in its settings files.
- **Restart**: the app is switched off and on again, for example when your
agent deploys a new version. This is the moment OpenClaw forgets.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a
7-day trial, no card. To keep OpenClaw running, Pro at $20/month for the
1 GB size; the 512 MB size on the trial and Starter is likely too small for
it. Plans are on the [pricing page](https://aidrop.it/pricing).
- Your coding agent connected to aidrop.it, as the [Quickstart](/quickstart)
shows.
- An API key from a model provider. A Claude or ChatGPT subscription login
does not fit: it is saved on the app's disk and lost at the next restart.
- A Telegram bot from [@BotFather](https://t.me/BotFather) and your numeric
Telegram user ID. OpenClaw's
[Telegram guide](https://docs.openclaw.ai/channels/telegram) shows how to
find it.
## Say this to your agent
Replace the two parts in square brackets before you paste: your numeric
Telegram user ID, and the model provider and model you want, for example
"Anthropic, Claude Sonnet".
```text title="Say this to your agent"
Set up OpenClaw (https://github.com/openclaw/openclaw) as an aidrop.it Service so it runs 24/7 and I talk to it on Telegram. Read aidrop.it's runtime rules before writing anything and follow them.
- Build on the official image ghcr.io/openclaw/openclaw, pinned to a release tag, with our own small Dockerfile and start script.
- Telegram only. Allowlist my numeric user ID [MY TELEGRAM ID]; no pairing, nobody else may talk to it.
- Model: [PROVIDER AND MODEL], with an API key, not a subscription login.
- The disk is read-only and wiped on restart. Keep openclaw.json and the workspace notes (AGENTS.md, SOUL.md, USER.md, MEMORY.md) in the repo, copy them into the temporary folder at start, and point OpenClaw's state and workspace there.
- Gateway: listen on all interfaces on the platform port, token auth, health check on /healthz.
- Outbound traffic must go through the platform's HTTP proxy. Set OpenClaw's own proxy URL from it so every client uses it.
- Secrets: ask me for the model API key and the Telegram bot token, and make up a long random gateway token yourself. 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.
- Size: 1 GB.
Push it, build it, and tell me the address, whether the bot answers, and the names of the secrets it uses.
```
## How your agent moves OpenClaw to the cloud
1. Reads aidrop.it's rules for how apps run there.
2. Writes a small setup: the OpenClaw version, your settings, the assistant's
notes and a start-up script that copies the notes into place.
3. Saves the code in a new repository on aidrop.it.
4. Asks you for the bot token and the model key. Paste each one into the
chat once. The agent saves them as secrets in your Project, where only
OpenClaw can read them, and never shows them again or writes them into the
code. Under **Secrets** in your Project on the aidrop.it dashboard you can
check which secrets exist, by name only.
5. Builds it and waits until OpenClaw reports it is up. If OpenClaw stops at
start-up, the agent reads why in the log, fixes the setup and builds again.
6. Tells you the address and asks you to message your bot.
## Check that OpenClaw answers from the cloud
- Your agent says the app is running.
- You message your bot on Telegram and it answers.
- A friend messages the bot and gets no answer.
- You close your laptop, message again, and it still answers.
## What survives a restart
The app has no permanent disk here. What it writes while running sits in a
small temporary folder that is emptied on every restart
([why your app has nowhere to write](https://aidrop.it/blog/your-app-has-nowhere-to-write/)).
- **Kept:** your settings, the notes saved with the code, your keys and the
Telegram connection.
- **Lost:** chat history, notes the assistant wrote itself, skills or plugins
installed from the chat, and approvals you gave it.
To make something permanent, ask your agent to add it to the saved notes and
deploy again.
Skip WhatsApp here. OpenClaw links WhatsApp by scanning a QR code, like
WhatsApp Web, and keeps that link on disk. You would scan again after every
restart, with no screen to show the code on. Discord works, because it uses a
token like Telegram; if you would rather build a Discord bot of your own, see
[host a Discord bot 24/7](/playbooks/host-a-discord-bot-24-7).
## Other ways to run OpenClaw
- **A small rented server.** Usually the cheapest option, and it keeps its
disk, so OpenClaw remembers everything across restarts. You install it,
update it and keep the server secure yourself.
- **A managed OpenClaw host.** Several companies run OpenClaw for you.
Compare what each keeps after a restart and what it charges.
- **aidrop.it.** Your coding agent does the setup, the setup stays in your own
repository, and OpenClaw runs next to your other apps. The price of that is
the restart reset above.
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
You do not need to understand the right-hand column; it is for your agent.
| What you see | What to tell your agent |
| --- | --- |
| The app keeps stopping after the build | "Read the logs and fix start-up. OpenClaw may only write to the temporary folder." |
| The bot never answers | "Check the logs for Telegram errors. Telegram traffic must use the platform proxy." |
| The bot replies with a pairing code | "Allow only my Telegram user ID." |
| The bot says the model or key is wrong | "Check the model name. I will give you the API key again; store it under the same name and build again." |
| It forgot what I told it yesterday | "Add this to the saved notes and deploy again." |
| It stops and the log says out of memory | "Move it to the 2 GB size." |
## FAQ
### Can OpenClaw run without my Mac?
Yes. The part of OpenClaw that connects your chats to the AI model runs on
any Linux server or container, and your chat apps talk to that copy. Without
a permanent disk it forgets chats after a restart. A server with its own disk
keeps everything, but you look after that server yourself.
### What is the difference between n8n and OpenClaw?
n8n is a workflow tool: you draw fixed steps, and it runs them the same way
every time. OpenClaw is a chat assistant: you ask in plain words and the AI
model decides the steps. Pick n8n for repeatable automations
([self-host n8n](/playbooks/self-host-n8n)) and OpenClaw for an assistant you
talk to. If all you need is one task on a timetable, such as a morning
report, a plain scheduled job is simpler: see
[what a cron job is and how to run one without a server](/playbooks/what-is-a-cron-job).
### Can I use Ollama with OpenClaw in the cloud?
Not the Ollama on your Mac. A cloud server cannot reach a model running on
your laptop, and the laptop would have to stay on anyway. Use a hosted model
provider's API key. Your own model in the cloud needs a graphics card, which
a small container does not have.
### Does OpenClaw need Docker?
No. OpenClaw's [Docker setup](https://docs.openclaw.ai/install/docker) is
optional, and its [sandbox](https://docs.openclaw.ai/gateway/sandboxing),
which runs tools in separate containers, is off by default. On aidrop.it the
whole assistant runs in one container, so the sandbox stays off.
## Related
- [Run Hermes Agent in the cloud](/playbooks/run-hermes-agent-in-the-cloud)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Hermes Agent cloud hosting: run it 24/7
Source: https://docs.aidrop.it/playbooks/run-hermes-agent-in-the-cloud
> Run Nous Research's Hermes Agent 24/7 on aidrop.it for $20 a month, set up by your AI coding agent. What a restart resets and how to keep what it learns.
[Hermes Agent](https://github.com/NousResearch/hermes-agent) is a free,
open-source AI assistant from Nous Research, under the MIT licence. You chat
with it in Telegram, Discord or a terminal, and it learns as you go: it
remembers you and writes itself new skills. This page keeps it answering when
your computer is off. You paste one paragraph into your AI coding agent
(Claude Code, Codex or Cursor), and the agent sets Hermes up on aidrop.it.
Before you start:
- **It costs $20 a month.** Hermes needs the 1 GB size, which starts at the
Pro plan. Your model provider bills its usage on top.
- **A restart resets its learning.** New skills and notes are lost on every
restart unless you copy them into its setup or connect a memory service.
The next section shows what that means.
## What Hermes keeps after a restart, and what it relearns
The app has no permanent disk here. What Hermes writes while running sits in
a small temporary folder that is emptied on every restart
([why your app has nowhere to write](https://aidrop.it/blog/your-app-has-nowhere-to-write/)).
- **Kept:** the settings, personality and skills saved with its code, your
keys, the Telegram connection, and whatever a memory service holds.
- **Lost:** chat history, its own memory notes, new skills it wrote, and
scheduled jobs created from the chat.
Two ways to keep more. To keep a new skill, ask your coding agent to copy it
into the repository and deploy again. To keep what Hermes learns about you,
connect a memory service such as Honcho or Mem0; it holds facts about you,
but not skills.
## What you will have at the end
- Hermes running in the cloud around the clock.
- A Telegram bot that answers you and nobody else.
- Its personality, your profile and the skills you chose saved with its code.
- Your model key stored on aidrop.it, out of the code.
## Words you will meet
- **Bot token**: the password Telegram gives your bot.
- **API key**: a password from an AI company that lets Hermes use its
models. Usage is billed to you.
- **Skill**: a recipe Hermes saves after a task, so it can repeat it.
- **Memory service**: an outside service that keeps what Hermes learns about
you, so a restart does not erase it.
- **Secret**: how aidrop.it stores the bot token, the model key and the
memory service key, and hands them to Hermes at start.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a
7-day trial, no card. To keep Hermes running, Pro at $20/month for the
1 GB size; the 512 MB size on the trial and Starter is likely too small for
Hermes. Plans are on the [pricing page](https://aidrop.it/pricing).
- Your coding agent connected to aidrop.it, as the [Quickstart](/quickstart)
shows.
- An API key from a model provider, such as Anthropic or OpenRouter. A
browser login (Nous Portal, a Claude subscription) does not fit: it is
saved on the app's disk and lost at the next restart.
- A Telegram bot from [@BotFather](https://t.me/BotFather) and your numeric
Telegram user ID. See the
[Hermes Telegram guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram).
- Optional: an account with a memory service that Hermes supports. See its
[memory providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers).
## Say this to your agent
Replace the parts in square brackets before you paste: your numeric Telegram
user ID, and the model provider and model. Delete the last bracket if you
have no memory service.
```text title="Say this to your agent"
Set up Hermes Agent (https://github.com/NousResearch/hermes-agent) as an aidrop.it Service so it runs 24/7 and I talk to it on Telegram. Read aidrop.it's runtime rules before writing anything and follow them.
- Build on the official image nousresearch/hermes-agent, pinned to a version tag. Its entrypoint starts s6 as root and switches user, which aidrop.it does not allow: override it, run as the image's non-root hermes user, and start "hermes gateway run --no-supervise" directly.
- The disk is read-only and wiped on restart. Keep config.yaml, SOUL.md, my USER.md and any skills or cron jobs I want to keep in the repo; copy them into a Hermes home in the temporary folder at start.
- Telegram only, allowed users: [MY TELEGRAM ID].
- Model: [PROVIDER AND MODEL], with an API key, no browser login.
- Enable the Hermes API server on all interfaces on the platform port and use /health as the health check. It can run tools, so protect it with a long random API server key.
- Outbound traffic goes through the platform's HTTP proxy; confirm the Telegram adapter and model calls use it.
- Secrets: ask me for the model key and the Telegram bot token [and my memory service key], and make up the long random API server key yourself. 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.
- Size: 1 GB.
Push it, build it, and tell me the address, whether the bot answers, and the names of the secrets it uses.
```
## How your agent sets up Hermes
1. Reads aidrop.it's rules and writes a small setup on top of the official
Hermes package: your settings, its personality file, the skills to keep,
a start-up script.
2. Saves the code in a new repository on aidrop.it.
3. Asks you for the bot token, the model key and, if you use one, the memory
service key. Paste each one into the chat once. The agent saves them as
secrets in your Project, where only Hermes can read them, and never shows
them again or writes them into the code. Under **Secrets** in your Project
on the aidrop.it dashboard you can check which secrets exist, by name only.
4. Builds it and waits for Hermes's health page. If Hermes refuses to start,
the agent reads the reason in the log and changes the start-up script.
5. Tells you the address and asks you to message your bot.
## Check that Hermes answers
- Your agent says the app is running.
- You message your bot on Telegram and it answers.
- A friend messages the bot and gets no answer.
- You turn your computer off and the bot still answers.
## Other ways to run Hermes
- **Hermes Cloud.** Nous Research runs Hermes for you on
[Hermes Cloud](https://portal.nousresearch.com/cloud), with memory that
persists. Choose it if you want Hermes's learning kept with no extra setup.
Choose aidrop.it if you want the setup in a repository you own, your own
model key, and Hermes next to your other apps in one account.
- **Your own small server.** Hermes's docs say a $5-a-month virtual server is
plenty for it (as of October 2026). It keeps its disk, so nothing is lost
on restart, but you install, update and secure it yourself.
- **No Hermes at all.** If you only want a bot that answers questions, a
ready-made assistant may do. [Grok vs your own bot](/playbooks/grok-vs-your-own-bot)
compares the two.
Skip WhatsApp on aidrop.it. Hermes pairs with WhatsApp like WhatsApp Web,
through a QR code in a terminal, and the pairing is lost on every restart. The
[Hermes WhatsApp guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp)
also warns that this unofficial route carries a risk of account restrictions.
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
You do not need to understand the right-hand column; it is for your agent.
| What you see | What to tell your agent |
| --- | --- |
| The app stops right after start | "Read the logs. Hermes must start as its own user and write only to the temporary folder." |
| The build is green but the app is never ready | "Turn on the Hermes API server on the platform port and check its health page." |
| The bot never answers | "Check the logs for Telegram errors. If the bot token is wrong, ask me for it again and store it under the same name." |
| It forgot a skill it learned | "Save that skill in the repository and deploy again." |
| It forgot what I told it about myself | "Connect my memory service, or add this to USER.md and deploy again." |
| It runs out of memory | "Move it to the 2 GB size." |
## FAQ
### Where are the Hermes Agent GitHub and docs?
The code is at github.com/NousResearch/hermes-agent, under the MIT licence.
The docs are at hermes-agent.nousresearch.com/docs and cover installing,
Docker, and connecting chat apps.
### Can Hermes Agent use Claude?
Yes. For an always-on copy, use an Anthropic API key, or an OpenRouter key
that reaches Claude. Hermes can also sign in with a Claude Max plan, but its
docs say that route needs extra usage credits on top of the plan, and in the
cloud the login is lost on restart.
### Can I move from OpenClaw to Hermes?
Yes. Hermes has a migration command that imports an OpenClaw setup: its
personality and memory notes, skills, model settings and chat connections.
Both are open-source assistants you reach from chat
apps; Hermes is built around learning skills and memories as you use it. See
[run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud) to compare.
### Does Hermes Agent need a graphics card?
No. Hermes's docs say Hermes itself is lightweight; the thinking happens at
your model provider, which you reach with an API key. That is why it runs in
a small container, and why the provider's bill, not the server, grows with
use.
## Related
- [Run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# What is an MCP server? A plain-English guide
Source: https://docs.aidrop.it/playbooks/what-is-an-mcp-server
> What MCP and MCP servers are, in plain words: how to add one to Claude Code or Cursor, how to stay safe, and how your agent deploys apps through one.
MCP, the Model Context Protocol, is an open standard that lets an AI app such
as Claude Code or Cursor use outside services: read your GitHub issues, click
through a website, or put your code online. An MCP server is the service on
the other end. It offers the AI a list of actions it may take, once you
approve it. This page explains both in plain words, shows how to add one
safely, and shows how aidrop.it's server lets your agent deploy what it builds
in the same conversation. Trying aidrop.it is free for 7 days; keeping an app
online starts at $5 a month.
## What you will have at the end
- A clear picture of MCP, MCP servers and tools.
- The steps to add a server to Claude Code or Cursor, and to take access back.
- If you want, your agent connected to aidrop.it, ready to put apps online.
## Words you will meet
- **AI app**: the program you chat with, such as Claude Code, Cursor, Claude or ChatGPT. MCP calls it the host.
- **MCP server**: a plug-in service that gives the AI app new abilities. It runs on your computer (local) or on the internet (remote).
- **Tool**: one action a server offers, like "create an issue" or "build my app". The AI decides when to use it; many apps ask you first.
- **Sign-in screen**: a browser page where you approve what a remote server may do, such as only look or also make changes, instead of copying a password.
## How it works
Your AI app connects to each server you added and asks what tools it has.
When the model decides a tool would help, the app calls it and passes the
result back into the conversation. A remote server is reached by its web
address, and you sign in once in your browser. A local server runs on your
own computer. The
[official MCP architecture overview](https://modelcontextprotocol.io/docs/learn/architecture)
has the details. Well-known servers include
[GitHub](https://github.com/github/github-mcp-server) for issues and code,
Microsoft's [Playwright](https://github.com/microsoft/playwright-mcp) for
clicking through web pages, [Sentry](https://mcp.sentry.dev/) for error
reports, and [Notion](https://developers.notion.com/docs/mcp) for your notes.
## Adding a server
**In Claude Code**, you add a server by its address with one command from
[Claude Code's MCP guide](https://code.claude.com/docs/en/mcp), then open the
MCP menu inside Claude Code and sign in. aidrop.it installs as a plugin
instead; the [Quickstart](/quickstart) has the two lines to paste.
**In Cursor**, open Cursor's settings, choose MCP and add a new server
([Cursor's MCP guide](https://cursor.com/docs/context/mcp)). Name it aidrop
and paste this address: https://aidrop.it/mcp. If Cursor opens a settings
file instead of a form, ask Cursor's agent to add a server named aidrop with
that address for you. Then click the login link next to the server and
approve the sign-in.
## Staying safe
An MCP server acts as you, so adding one is like handing someone a key.
- **Connect only servers you trust**, published by the service's own maker.
- **Approve only what you need.** Read-only access is enough for many jobs.
- **Keep confirmations on** for anything that changes or deletes.
- **Be wary of hidden instructions** in pages or documents the AI reads. Give your agent a password or key only when the task needs it, and only once, so it can store it.
- **Take access back** when you are done: remove the server from your AI app and revoke it on the service's side.
For an agent that changes a live app, the roles, confirmations and backups that keep a mistake from becoming a loss are in [how to stop your AI agent from deleting your project](/playbooks/stop-your-ai-agent-from-deleting-your-project).
## Example: how your agent deploys through aidrop.it
Connected to aidrop.it, your agent does the whole job in one conversation. It
creates a project, saves the code in a repository, builds it and starts it.
If the app does not run, it reads the error log, fixes the code and builds
again. Then it gives you the link. It can also stop the app, go back to an
earlier version, connect your domain and create a database. The whole path
from first build to rollback is in
[the life of an app on aidrop.it](/service-lifecycle). aidrop.it never
writes code itself; your agent writes it on your computer. Teammates and
their roles are managed in the dashboard, not by the agent.
The sign-in screen asks you to pick your Team and approve two permissions:
to see your apps, and to build and run them. In each project the agent can
do what your own role allows. It is told to ask you before deleting
anything, and most deletions need an explicit confirmation. A Team admin can
see and take back every connection on the Connected apps page, found under
Management in the dashboard's menu. Every tool the agent can use is listed in
[the full MCP reference](/mcp), and
[What is an MCP deployment platform?](https://aidrop.it/blog/what-is-an-mcp-deployment-platform/)
explains the idea at more length.
The "agent" here is the coding agent you chat with. If you want an AI agent
that runs by itself around the clock, answering people or doing tasks,
[put your AI agent online](/playbooks/put-your-ai-agent-online).
## Say this to your agent
```text title="Say this to your agent"
Use the aidrop.it MCP server to put this project online.
List my aidrop.it projects first and use the right one, or create one if I have none. Read aidrop.it's runtime rules before changing code, and follow them. If the app needs a database, check whether the project has one and ask me before creating it.
Tell me before the first deploy that the link will be public. Save the code to an aidrop.it repository, build it, check that it runs, fix it if it does not, and give me the link.
Secrets: ask me for each password or key the app 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.
Report back: the link, what you built, and anything I still need to do.
```
## Check that aidrop.it is connected
- In your AI app's MCP list, aidrop.it shows as connected.
- Ask your agent "Which aidrop.it projects do I have?" It lists them.
## When the connection fails
| What you see | What to tell your agent |
| --- | --- |
| The server shows as not connected | No need to ask: open your app's MCP settings and sign in again. |
| The sign-in page never opens | Use an app that supports signing in to remote servers, such as Claude Code, Codex or Cursor. |
| The agent says it has no aidrop.it tools | "Reconnect the aidrop.it server and list my projects again." |
## FAQ
### What is the difference between MCP and an API?
An API is a door into one service, built for programmers, and every service's
door is different. MCP is a shared plug shape for AI apps: any app that
speaks MCP can use any MCP server without custom code. Many MCP servers are
built on a service's API and turn its actions into tools an AI understands.
### Is MCP only for Claude?
No. Anthropic introduced MCP as an open standard, and many AI apps now use
it, including Claude Code, Claude, Cursor, VS Code and ChatGPT. A remote
server can work in all of them, though each app adds it its own way.
### Are MCP servers safe to use?
As safe as the service behind them and the access you grant. A server can do
whatever your approved permissions allow, as you. Use official servers,
approve the least access that does the job, keep confirmations on for
changes, and revoke access you no longer use.
### What is an MCP deployment platform?
It is a hosting service your AI agent runs directly through MCP, instead of
you clicking through a dashboard. aidrop.it is one: the agent creates the
project, builds the code, reads the errors and gives you the link, all in the
conversation where it wrote the app. To try it,
[start free](https://app.aidrop.it/register): a 7-day trial, no card; after
that, Starter costs $5 a month.
## Related
- [The full MCP reference](/mcp)
- [Quickstart](/quickstart)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Put your AI-built landing page online](/playbooks/put-a-landing-page-online)
- [All playbooks](/playbooks)
---
# Before you delete
Source: https://docs.aidrop.it/playbooks/stop-your-ai-agent-from-deleting-your-project
> Use explicit approvals, code history and independent exports before risky changes. Learn what daily snapshots do and what to check before deleting data.
aidrop.it takes daily snapshots. Before a risky change, also keep the running
version of your app and an independent database export. A snapshot schedule
does not mean an agent can undo every deletion or restore any point in time.
This guide helps you review a proposed change before your agent runs it.
For the export commands and their limits, see [Taking your work with you](/taking-your-work-with-you).
## Set the rules before a change
Tell your agent what it may change and which actions need your explicit
approval. Name destructive operations directly: deleting a Project, Service,
repository or database; force-pushing code; dropping tables; and deleting rows.
A rule in a repository helps the agent follow your intent, but does not replace
access controls or an export you have tested.
Connect through your own Team membership and review the permissions that
membership grants. The [MCP reference](/mcp) explains the connection and tool
permissions. Do not give an agent more access just to avoid an approval step.
## Keep a way back for the application
Record the Service's current version before deploying a change. If a new
application version fails, use the [Service lifecycle](/service-lifecycle)
guide to check the available versions and roll back to a known working one.
Keep an independent clone of code you need before deleting a repository.
Application rollback and database recovery are separate operations. Starting
an older image does not reverse a schema migration or put deleted rows back.
Check the database change before approving the deployment.
## Daily snapshots and independent exports
We take daily snapshots. For an independent copy, your agent can export a small
database over MCP or run a `pg_dump` job inside the Project and send the result
to storage you control. Test restoring that export into an isolated database
before relying on it for a migration.
Do not infer a seven-day retention window, a trash folder or a self-service
restore command from the daily snapshot schedule. Before a recovery action,
confirm the available snapshot and recovery steps with support. Keep new writes
stopped if they could overwrite evidence or make the damage worse.
## Review a deletion before approving it
A deletion confirmation should name the exact resource and the data it removes.
Check that your export is complete and usable before approving a database
deletion. Treat removal of a Project or repository as a separate action from
stopping a running application.
If something has already been deleted, stop further destructive work and record
the resource, time and last known working version. Contact support about the
available recovery options. Do not ask an agent to recreate or overwrite the
resource before you know what recovery requires.
## A prompt for your agent
Paste this into your connected coding agent. It asks for a review before any
change and does not assume there is a snapshot-management tool.
```text title="Say this to your agent"
Review this aidrop.it Project before we change it. Do not mutate or delete anything.
1. List the Services, databases and repositories involved in the proposed change.
2. Record each Service's current version and available application rollback path.
3. Identify destructive operations and explain which data or history they remove.
4. Propose an independent database export to storage I control and an isolated restore test.
5. State any recovery information you cannot verify, including snapshot availability and restore steps.
6. Wait for my approval of the exact change and export plan before proceeding.
```
## FAQ
### Can I undo a deletion?
No such guarantee follows from a snapshot schedule. Check the available
snapshot and recovery steps before relying on it. Keep an independent export
before deleting data you need.
### Does rolling back my app restore its database?
No. Application versions and database contents are separate. A database
migration needs its own recovery plan.
### Does aidrop.it take snapshots?
Yes, we take daily snapshots. Your agent can also make independent database
exports to storage you control.
### Are written rules enough?
A written rule helps an agent follow your instructions. Also review its
permissions, require explicit approval for destructive actions and test your
independent exports.
## Related
- [Taking your work with you](/taking-your-work-with-you)
- [Service lifecycle](/service-lifecycle)
- [MCP tool reference](/mcp)
- [All playbooks](/playbooks)
---
# What is a cron job, and how to run one without a server
Source: https://docs.aidrop.it/playbooks/what-is-a-cron-job
> A cron job is a task a computer runs on a timetable. Learn to read cron schedules, then have your AI agent run your job 24/7 on aidrop.it, no server needed.
A cron job is a task a computer runs by itself on a timetable: every morning at
9, every 15 minutes, every Monday. The name comes from cron, a program on Linux
and macOS that keeps a list of such tasks and starts each one on time. To run
one without a server or a laptop left on, have your AI agent build a small
always-on app that keeps its own timetable, and put it on aidrop.it. It takes
about 20 minutes. To keep a record of every run, plan on the Pro plan at
$20 a month after the free trial; a job that keeps no record fits Starter at
$5 a month.
## How to read a cron schedule
A cron job has two parts: when it runs, and what it does. The "when" is a
**cron expression**: five values separated by spaces. In order, they are the
minute, the hour, the day of the month, the month and the day of the week. A
star means "any", `*/n` means "every n", and `1-5` is a range.
Two catches trip people up. First, if you set both a day of the month and a day
of the week, the job runs when either one matches: `0 9 1 * 1` runs on the 1st
and on every Monday
([crontab manual](https://man7.org/linux/man-pages/man5/crontab.5.html)).
Second, servers usually keep UTC time, which is London's winter time. "9:00"
means 9:00 UTC unless the job is told your time zone.
## Cron schedule cheat sheet
| Cron expression | What it means |
| --- | --- |
| `* * * * *` | Every minute |
| `*/5 * * * *` | Every 5 minutes |
| `*/15 * * * *` | Every 15 minutes |
| `0 * * * *` | Every hour, on the hour |
| `0 */6 * * *` | Every 6 hours: midnight, 6:00, 12:00 and 18:00 |
| `0 0 * * *` | Every day at midnight |
| `0 9 * * *` | Every day at 9:00 in the morning |
| `30 8 * * 1-5` | At 8:30 in the morning, Monday to Friday |
| `0 9 * * 1` | Every Monday at 9:00 |
| `0 18 * * 0` | Every Sunday at 6 in the evening (0 and 7 both mean Sunday) |
| `0 0 1 * *` | At midnight on the first day of every month |
| `0 0 1 1 *` | Once a year, at midnight on 1 January |
To check an expression you wrote, paste it into
[crontab.guru](https://crontab.guru), which reads it back in plain words.
## What you will have at the end
- Your task running on its timetable, around the clock, with your laptop closed.
- A record of every run: when it started, whether it worked, and what went wrong if not.
- A message to you, by email or in Slack, when a run fails.
- The code in a repository, so your agent can change the task or the timetable later.
## Words you will meet
- **Scheduler** — the part of the app that watches the clock and starts the task on time. It does the job cron does on a server.
- **Always-on app** — a small program that keeps running on aidrop.it, day and night, and carries your job inside it.
- **"I'm alive" page** — a tiny web page aidrop.it opens to see the app is still running. Even a job with no website needs one.
- **Database** — where the app notes each run, so the record survives restarts.
- **Secret** — a key your job needs, such as the link alerts are sent to. You give it to your agent once, and the agent saves it in your aidrop.it project instead of in the code.
## How scheduled jobs work on aidrop.it
aidrop.it has no separate "scheduled jobs" feature. Your job runs inside an
always-on app, deployed like any other app, which keeps its own timetable.
What that means for you:
- Exactly one copy runs, so the same run never happens twice.
- A run due while the app restarts or updates can be missed. The fix: the app notes each finished run in its database and, when it starts, runs any it missed.
- The app's own disk is wiped on every restart. Anything worth keeping goes in the database.
- The app is on all the time, so it takes up its size all the time.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card, with a database. To keep the job running with a record of every run, Pro at $20/month. Starter at $5/month has no database; it can run a job that keeps no record and cannot catch up a missed run. Plans are on the [pricing page](https://aidrop.it/pricing).
- Your agent connected to aidrop.it. The [Quickstart](/quickstart) shows how.
- Keys for the services your task uses. For alerts, an email service such as [Resend](https://resend.com) or a Slack incoming webhook; old-style email sending does not work on aidrop.it. Alerts can go to Telegram too: [build a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code) first.
## Say this to your agent
Replace the part in square brackets before you paste: say what the job does
and when, in your own words and your own time zone.
```text title="Say this to your agent"
Build me a scheduled job and run it on aidrop.it. Use my existing aidrop.it Project, or create one called "Scheduled jobs" if I have none.
The job: [SAY WHAT AND WHEN, e.g. "every weekday at 8:30 am New York time, fetch yesterday's orders from my store's API and post a summary to Slack"].
- aidrop.it has no cron feature. Build one always-on app with an in-process scheduler (node-cron, APScheduler, or supercronic for shell commands) plus a small HTTP health endpoint. Read aidrop.it's runtime rules first, follow them.
- Set my time zone in the scheduler explicitly; do not rely on the server clock's zone.
- Never start a run while the previous one is still going.
- Record every run in the Project's PostgreSQL: start, end, status, error. On startup, if a run was missed, run once.
- If a run fails, alert me over HTTPS (email API or Slack webhook). SMTP does not work on aidrop.it.
- Secrets: ask me for each key the job needs, such as the alert link, 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.
Build it, check it runs, do one test run, then tell me the schedule in plain words and when the next run is due.
```
## What your agent builds for your scheduled job
1. Picks your project, checks for a database, and asks you before creating one.
2. Asks you for the keys it needs, such as the Slack link for alerts, and saves each one as a secret in your project. It never shows them again or writes them into the code.
3. Writes the app: the task, the timetable in your time zone, the run record and the "I'm alive" page.
4. Saves the code to a repository on aidrop.it, builds it and checks the scheduler started. If it did not, the agent reads the log, fixes the app and builds again.
5. Does one test run and tells you when the next real one is due.
## Check that your job runs on time
- The next run time your agent reports matches what you wanted, in your time zone.
- The test run did its job: the message arrived, or the report appeared.
- Ask your agent "show me the last five runs". It reads them from the database.
- Ask your agent to make one test run fail on purpose. The alert reaches you.
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
| What you see | What to tell your agent |
| --- | --- |
| The job runs hours early or late | "Schedule it in my time zone," and name your city. |
| A run was skipped during an update | "On startup, check the last successful run and catch up if one was missed." |
| aidrop.it says the app is not running, though the job works | "Add a small 'I'm alive' page that answers quickly, and build again." |
| The same run happened twice | "Make sure only one scheduler starts, and skip a run while the last one is going." |
| Failure emails never arrive | "Send alerts through an email service's web API, not SMTP." |
## FAQ
### What is the difference between cron, a cron job and a crontab?
Cron is the program that keeps time and starts tasks. A cron job is one task in
its list: a schedule plus a command. A crontab, short for "cron table", is the
file that holds the list, one job per line. People say "cron job" for any
scheduled task, even when no cron program is involved.
### How do I write a cron expression for every 5 minutes?
Write `*/5 * * * *`. The first value is the minute, and `*/5` means "every
fifth minute"; the stars mean any hour, day, month and weekday. The cheat
sheet above lists the other common schedules.
### Can I run a cron job for free?
Often, with limits. GitHub Actions runs workflows on a cron schedule, but its
[documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule)
says runs can be delayed at busy times, especially at the start of each hour,
and some may be dropped. The shortest gap is 5 minutes, and in public
repositories schedules switch off after 60 days with no activity (as of
October 2026). For jobs where a late run does no harm, that is often enough.
### Do I need my own server to run a cron job?
No. The job needs a computer that is always on, not one of your own. On
aidrop.it your AI agent builds the job as a small always-on app, deploys it and
checks it runs. You describe the task and timetable in plain words; the agent
turns them into a cron expression.
## Related
- [Run a web scraper on a schedule](/playbooks/run-a-web-scraper-on-a-schedule)
- [Self-host n8n without managing a server](/playbooks/self-host-n8n)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Run a web scraper on a schedule, without your laptop
Source: https://docs.aidrop.it/playbooks/run-a-web-scraper-on-a-schedule
> Your AI agent builds a web scraper that runs on a timetable, saves each find to a table and alerts you when it breaks, running 24/7 on aidrop.it.
A web scraper is a small program that visits web pages and copies out the facts
you care about: prices, job listings, new posts. Your AI agent, such as Claude
Code, Codex or Cursor, writes one from a paragraph you paste and puts it online
on aidrop.it, where it runs on a timetable with your laptop closed. It needs a
database, so after the 7-day free trial plan on Pro at $20 a month.
What you get is a table that grows with every run, for example:
| Found at | Page | Item | Price |
| --- | --- | --- | --- |
| 1 Oct, 07:00 | example.com/sale | Desk lamp | $24.00 |
| 1 Oct, 07:00 | example.com/sale | Office chair | $129.00 |
| 2 Oct, 07:00 | example.com/sale | Desk lamp | $19.50 |
You can ask your agent for it as a spreadsheet at any time. And when a run
fails, or a page suddenly yields nothing, you get a message.
## What you will have at the end
- A scraper that checks your chosen pages on schedule, around the clock.
- Everything it collects, saved in a database with the time and the page it came from.
- An alert by email or Slack when a run fails or finds nothing.
- The code in a repository, so your agent can change what it collects later.
## Words you will meet
- **Scraper** — a program that reads web pages for you and writes down what it finds.
- **Headless browser** — a real web browser running without a screen, for pages that only show their content after their scripts run.
- **robots.txt** — a public file where a website says which pages automated visitors should leave alone.
- **Database** — the table above lives here. aidrop.it runs it next to your scraper.
- **Secret** — where the key for your alerts, such as an email service key, is saved on aidrop.it, out of the scraper's code. You give it to your agent once, and the agent saves it.
## Two ways to read a page
Most pages can be read the simple way: the scraper downloads the page and picks
out the parts it needs. This is fast and fits the smallest size aidrop.it
offers.
Some pages are nearly empty until the browser runs their scripts, as on many
shops and dashboards. For those, the scraper drives a headless browser. It
works, but it is slower and needs much more memory: plan for the 1 GB size,
which starts at the Pro plan. Your agent tries the simple way first and
switches only if the page comes back empty. Playwright's own team says its
browser image is
[not recommended for visiting untrusted websites](https://playwright.dev/docs/docker),
so keep the browser for sites you know.
## How often to run it
Run it as often as the page really changes, and no more.
- **Once a day** suits most prices, listings and news pages. Pick a quiet hour, such as early morning.
- **Every hour** only for things that move fast and where an hour matters to you, such as a limited stock alert.
- **Once a week** for slow pages, such as a competitor's pricing page.
More runs mean more load on someone else's website and a bigger chance of
being blocked. The timetable works as on the
[cron job page](/playbooks/what-is-a-cron-job): the scraper is one always-on
app with its own clock, and a run due during a restart is caught up when the
app starts again.
## How not to get blocked: scrape politely
- Read the site's [robots.txt](https://www.rfc-editor.org/rfc/rfc9309.html) and its terms. If the site offers an official API or data export, use that instead.
- Slow down. Wait a few seconds between pages, fetch only the pages you need, and do not fetch the same page twice in one run.
- Say who you are. The scraper should name you and a contact address in every request.
- Skip personal data you do not need. Privacy laws may apply to it.
- If a site blocks you or shows a "prove you are human" check, stop. Do not try to get around it.
aidrop.it logs where each of your app's outgoing requests goes.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card, with a database. To keep the scraper running, Pro at $20/month; it also has the larger size that pages needing a headless browser use. Starter has no database to keep the results in. Plans are on the [pricing page](https://aidrop.it/pricing).
- Your agent connected to aidrop.it. The [Quickstart](/quickstart) shows how.
- The pages to watch, what to collect from each, and how often.
- Somewhere for alerts: an email service such as [Resend](https://resend.com), or a Slack incoming webhook. For alerts in Telegram, [build a Telegram bot with Claude Code](/playbooks/telegram-bot-with-claude-code) first.
## Say this to your agent
Replace the two parts in square brackets before you paste: what to collect
from which pages, and how often.
```text title="Say this to your agent"
Build me a web scraper that runs on a schedule on aidrop.it. Use my existing aidrop.it Project, or create one called "Scraper" if I have none.
What to collect: [PAGES AND FIELDS, e.g. "name and price of each product on https://example.com/sale"].
How often: [WHEN, e.g. "every day at 7 am London time"].
- Python. Plain HTTP first (httpx with selectolax or BeautifulSoup). Use Playwright with headless Chromium only if the data is missing from the raw HTML. Then use the official Playwright image pinned to the library's version, run it as its non-root user, and pass the HTTPS_PROXY value to Playwright's proxy launch option.
- Read aidrop.it's runtime rules first and follow them. One always-on app with an in-process scheduler (APScheduler) and a small HTTP health endpoint. Schedule in my time zone.
- Be polite: obey robots.txt, a few seconds between requests, a User-Agent with my name and a contact address. Stop on 403, 429 or a CAPTCHA and alert me; never work around them.
- Save results in the Project's PostgreSQL with the time and source URL, plus one row per run (status, items, error). On startup, run once if a scheduled run was missed.
- Alert me over HTTPS (email API or Slack webhook) when a run fails or finds nothing. Secrets: ask me for each key the alerts need, 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.
Build it, check it runs, do one test run, then show me the first results and when the next run is due.
```
## How your agent builds the scraper
1. Picks your project, checks for a database, and asks you before creating one.
2. Looks at your pages and picks the simple way or the headless browser.
3. Asks you for the keys the alerts need and saves each one as a secret in your project. It never shows them again or writes them into the code.
4. Writes the scraper, its timetable, the results table and a small "I'm alive" page that aidrop.it checks.
5. Builds it on aidrop.it. If the scraper does not start, the agent reads the log, fixes it and builds again.
6. Does one test run and shows you the first rows of your table.
## Check that the scraper collects the right data
- The first results match what you see on the site yourself.
- The next run time your agent reports matches what you asked for.
- After the next scheduled run, ask your agent "show me the last runs". Each says how many items it found.
- Ask for the results as a spreadsheet file. It opens in Excel or Google Sheets.
To look at the results as charts in your browser instead of a spreadsheet,
your agent can add a small dashboard next to the scraper: see
[deploy a Streamlit app](/playbooks/deploy-a-streamlit-app).
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
| What you see | What to tell your agent |
| --- | --- |
| Runs finish, but find nothing the page clearly shows | "This page fills in with scripts. Use the headless browser for it." |
| The site answers "Access denied" or asks you to prove you are human | The site does not want automated visitors. Ask your agent whether it has an official API; if not, stop. |
| The values are wrong after the site's redesign | "The page layout changed. Update what the scraper looks for." |
| The browser crashes or runs out of memory | "Move to the next size up and open one page at a time." |
| aidrop.it says the app is not running | "Add a small 'I'm alive' page that answers quickly, and build again." |
## FAQ
### Is web scraping legal?
It depends on where you are, what you collect and the site's terms. Collecting
public facts such as prices is common. Trouble usually starts with copying
copyrighted content, collecting personal data, or getting around logins and
blocks. Read the site's terms first, prefer an official API, and ask a lawyer
when the stakes are real.
### What is the best language for a web scraper?
Python is the most common choice. It has simple tools for picking parts out of
a page, such as [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/),
and [Playwright](https://playwright.dev/python/) for pages that need a real
browser. JavaScript works as well. When an agent writes the code, the language
matters less than scraping politely.
### Can AI build a web scraper for me?
Yes. An AI coding agent can write the scraper, test it on your pages and fix it
when a site changes its layout. On aidrop.it the same agent also puts it
online, sets up the database next to it and checks it runs, so the scraper
keeps working after you close the chat.
## Related
- [What is a cron job, and how to run one without a server](/playbooks/what-is-a-cron-job)
- [Self-host n8n without managing a server](/playbooks/self-host-n8n)
- [Deploy a Streamlit app](/playbooks/deploy-a-streamlit-app)
- [Taking your work with you](/taking-your-work-with-you)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)
---
# Self-host n8n without managing a server
Source: https://docs.aidrop.it/playbooks/self-host-n8n
> Self-host n8n without managing a server: your AI agent sets up the free community edition with a database on aidrop.it. Costs, licence and setup.
You can self-host n8n without renting or looking after a server. Paste one
paragraph into Claude Code, Codex or Cursor, and it sets up n8n's free
community edition on aidrop.it, with a database so nothing is lost, then hands
you a link. After the 7-day free trial it costs $20 a month on the Pro plan.
**Is that allowed?** n8n's
[licence FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq)
says: "If workflows are only created or modified by you or people in your
organization, you can use n8n under the Community license for free." This is
not legal advice.
## n8n Cloud or self-hosted
| | n8n Cloud | Self-hosted n8n on aidrop.it |
| --- | --- | --- |
| Who runs it | n8n | Your coding agent sets it up; aidrop.it runs it |
| Price | From €20 a month, billed yearly, for 2,500 workflow runs a month (as of October 2026, [n8n pricing](https://n8n.io/pricing/)) | $20 a month for the Pro plan; n8n does not count runs, your plan's memory is the limit |
| Licence | n8n Cloud's own terms | The free Sustainable Use License, quoted above |
| Updates | n8n does them | You ask your agent |
| Your data | On n8n's servers | In your database on aidrop.it. aidrop.it takes daily snapshots; your agent can also make independent exports |
## What you will have at the end
- The n8n editor at its own web address, open from any browser.
- Your workflows, run history and saved logins kept in a database, so they survive restarts and updates.
- Webhook links that other apps, such as a form or a payment tool, can call to start a workflow.
- The setup saved in a repository, so your agent can update n8n later.
## Words you will meet
- **Workflow** — a chain of steps in n8n, like "when a form is filled in, add a row to a sheet and post in Slack".
- **Webhook** — a web address n8n gives a workflow. When another app visits it, the workflow starts.
- **Database** — where n8n keeps your workflows and run history. aidrop.it runs one next to n8n for you.
- **Encryption key** — a long password n8n uses to lock the logins you save for other apps. Lose it and those logins cannot be opened again.
- **Secret** — where the encryption key lives on aidrop.it: given by you to your agent once, saved by the agent, handed to n8n at every start, never written into the setup.
## What you need
- An aidrop.it account — [start free](https://app.aidrop.it/register): a 7-day trial, no card, which includes a database. To keep n8n running, Pro at $20/month. Starter has no database, and n8n without one forgets everything at every restart. Plans are on the [pricing page](https://aidrop.it/pricing).
- Your agent connected to aidrop.it. The [Quickstart](/quickstart) shows how.
- Enough memory. How much n8n needs depends on how much data your workflows move; n8n explains this in its guide to [fixing memory issues](https://docs.n8n.io/deploy/host-n8n/configure-n8n/scaling/fix-memory-issues). The trial's size is fine for trying n8n. For daily use, pick the 1 GB size, which starts at Pro.
- A long random password from your password manager, for the encryption key. Keep it there: it is the only copy you will have.
## Say this to your agent
```text title="Say this to your agent"
Set up self-hosted n8n for me on aidrop.it. Use my existing aidrop.it Project, or create one called "n8n" if I have none.
- Use the official n8n Docker image, pinned to the current stable version. It already runs as the "node" user; keep it. Read aidrop.it's runtime rules first and follow them.
- Storage: PostgreSQL, never SQLite. Reuse the Project's PostgreSQL with a new database, or ask me before creating one.
- n8n cannot read one connection URL. Add a small start script that splits DATABASE_URL into n8n's database settings, makes n8n listen on 0.0.0.0 on the platform's PORT, then starts it.
- The disk is wiped on every restart: point n8n's user folder and HOME at /tmp and keep binary data in the database.
- n8n must read N8N_ENCRYPTION_KEY from a Project secret, or saved credentials break after a restart. Secrets: ask me for the encryption key, store it with project_secret_set under that name, and list it in required_secret_names when you build. Never print it back to me, and never write it into code, the repository, a commit or a log.
- Health check: /healthz. Use the 1 GB size if my plan has it.
- After the first build, set n8n's public editor and webhook URL to the Service address (https, one proxy in front) and build again. SMTP email cannot leave aidrop.it; leave it off.
Build it, check it runs, fix anything that fails. Then give me the address and tell me to create the owner account at once.
```
## How your agent sets up n8n
1. Picks your project and checks for a database. It asks you before creating one.
2. Asks you for your encryption key. You paste it into the chat once, and the agent saves it as a secret in your project. It never shows the key again or writes it into the setup.
3. Writes a short setup: the official n8n plus a start-up step that tells n8n where its database is.
4. Saves it to a repository on aidrop.it and builds it there.
5. Waits for n8n's "I'm alive" page. If n8n cannot reach its database or stops at start, the agent reads the log, fixes the setup and builds again.
6. Tells n8n its public address, so the webhook links it shows are right, and gives you the link.
**Claim your n8n the moment you get the link.** The address is open to the
whole internet from the first minute, and the first visitor creates n8n's
owner account. Open it at once and create yours. For no gap at all, ask your
agent to have n8n create the owner from secrets you give it, which n8n
[supports from version 2.17](https://docs.n8n.io/deploy/host-n8n/configure-n8n/manage-settings-using-environment-variables).
## Check that your n8n works
- The link opens n8n and asks you to set up the owner account.
- A small workflow that fetches any web page runs without errors.
- A Webhook step shows a link that starts with your n8n address, not "localhost".
- Ask your agent to restart n8n. Your workflow and saved logins are still there.
## When something goes wrong
Find what you see on the left and paste the right-hand text to your agent.
You do not need to understand the right-hand column; it is for your agent.
| What you see | What to tell your agent |
| --- | --- |
| Workflows vanish after a restart | "n8n is not using PostgreSQL. Fix its database settings and build again." |
| Saved logins stop working after a restart | "The encryption key is missing or changed. I will give you the key from my password manager again; store it under the same name and build again." |
| Webhook links show "localhost" | "Set n8n's public editor and webhook URL to the Service address." |
| A schedule runs at the wrong hour | "Set n8n's time zone to mine," and name your city. |
| "Connection lost" or out-of-memory errors | "Move n8n to the next size up." Also split big jobs into smaller batches. |
| An email or mailbox step never connects | Old-style email ports are blocked here. Send mail through a web service such as Resend or Postmark. |
| Community nodes are gone after a restart | "Have n8n reinstall my community nodes at every start." |
aidrop.it takes daily snapshots. Ask your agent for an independent copy of
the database now and then; [taking your work with you](/taking-your-work-with-you)
explains the options. And a scheduled run due during a restart is skipped,
unless your agent turns on n8n's
[durable scheduler](https://docs.n8n.io/deploy/host-n8n/configure-n8n/durable-scheduler).
## When n8n is not the right tool
n8n shines when you want to draw and change automations yourself. If your
job is to collect prices or listings from websites on a timetable, a
[web scraper that runs on a schedule](/playbooks/run-a-web-scraper-on-a-schedule),
written by your agent, is often simpler. If you want an assistant you ask in
plain words rather than fixed steps,
[run OpenClaw in the cloud](/playbooks/run-openclaw-in-the-cloud) instead.
## FAQ
### Is self-hosted n8n free?
The community edition costs nothing when only you and people in your
organization build the workflows, under n8n's Sustainable Use License. You
pay only for where it runs: on aidrop.it, $20 a month for Pro. A few
features, such as single sign-on, need a paid n8n license key.
### Can I build n8n automations for my clients?
Yes, with limits. n8n's
[license FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq)
allows building automations for clients on your own instance, and charging
for that work, as long as clients cannot create or edit workflows themselves.
Letting clients build their own workflows needs a commercial agreement with
n8n. This is not legal advice.
### How do I host n8n without managing a server?
Pay for n8n Cloud, or let your AI agent do the install on a platform made for
it. On aidrop.it the agent writes the setup, builds it and checks it runs, and
the database sits next to n8n in the same project. The setup stays in your own
repository, so you can move it elsewhere later.
## Related
- [What is a cron job, and how to run one without a server](/playbooks/what-is-a-cron-job)
- [Put your AI agent online](/playbooks/put-your-ai-agent-online)
- [Taking your work with you](/taking-your-work-with-you)
- [Quickstart](/quickstart)
- [All playbooks](/playbooks)