# zdeploy > zdeploy hosts apps people build with AI: a live HTTPS address on servers in Europe, with sign-in, email, scheduled jobs, storage, AI models and a Postgres database for the app to switch on as it needs them. ## If a person sent you here They want you to build their app and put it live on zdeploy. You do all of it. Ask the person for two things: their email, and the 6-digit code we send to it. The one other thing you may need from them is a provider key, if the app calls an AI model (see the services below). Never ask them to paste a key into the chat: get them a key link. A few settings have no API yet, and only the person can change them, in the console at https://zdeploy.tech/apps: a sign-in redirect URI other than the one zdeploy registers, Google or LinkedIn sign-in, a sender address of their own for email (the senders API takes the app key, which only the running app holds), replacing a secret the person set themselves, and turning auto-update off. If the app needs one, tell the person exactly what to set. Each app starts a 2-week free trial when it is created, with no card; after that it is €20 a month per app. An account can have 3 apps on a free trial at once. An app holds its slot until it is paid for or deleted, at most 21 days. With every slot in use, create_app answers 402 and says so: tell the person, who can add a card in the console at https://zdeploy.tech/apps or delete a trial app they no longer need. How it goes: 1. Sign up with the person's email. 2. Create the app. zdeploy gives it an address and a private git repo that starts from a working template. The template builds and goes live by itself: within minutes the address shows a placeholder page saying the app is being built. Show the person. 3. Clone the repo and build the app on the template. 4. Push to main. zdeploy builds and scans each push. 5. When the build says built, check the status: a built push usually deploys itself. Call deploy only if it has not (step 6). The person's app replaces the placeholder. zdeploy has two sides. Keep them apart: - The control plane sets things up ON zdeploy: the account, the app, its repo, secrets, builds, deploys, logs. Call it with the HTTP steps below, or with our MCP (same actions as tools). - The service API is what the app's OWN CODE calls at runtime: sign-in, email, jobs and the rest. See step 4. Every response is JSON unless its endpoint's docs say otherwise (image bytes, file downloads), and every failed request answers 4xx or 5xx with an `error` string saying what to change (some add fields, such as `success: false`). Two answers are not failures: a URL check that finds a URL unsafe, or cannot run, answers `200` with `safe: false` (plus an `error` string when it could not run: treat it as unsafe), and a chat stream that fails after it has started just ends (its page says how to tell). Control-plane calls wrap success in `{ "data": ... }`. Service calls do not share one shape: each endpoint's docs show its exact success body. Every endpoint is also at https://zdeploy.tech/openapi.json (OpenAPI 3.1), for generating a client, except sign-in's standard OpenID Connect routes, which https://zdeploy.tech/.well-known/openid-configuration describes. ## After a pause: the code from the inbox Your credentials pause when the account has had no calls for a while (the person sets how long; 2 hours unless they changed it). The next call answers 401 with `"error":"idle"`, and `details` says which inbox a code went to. Ask the person for that code, then send it with the same credential: curl -s -X POST https://zdeploy.tech/api/v1/signup/revalidate -H 'Authorization: Bearer ' -H 'Content-Type: application/json' -d '{"code":"123456"}' Every credential the account holds works again; none is replaced. Only the git push credential is not restored: if a push is refused after a pause, call `git/credentials` (step 3) for a new remote. ## 1. Sign up curl -s -X POST https://zdeploy.tech/api/v1/signup/start -H 'Content-Type: application/json' -d '{"email":"PERSON@EXAMPLE.COM"}' Ask the person for the code from the email (it lasts 10 minutes), then: curl -s -X POST https://zdeploy.tech/api/v1/signup/verify -H 'Content-Type: application/json' -d '{"email":"PERSON@EXAMPLE.COM","code":"123456"}' `data.credential` (zdacc_...) is the account credential. It is shown once: keep it for the rest of this work. An existing account signs in the same way. ## 2. Create the app curl -s -X POST https://zdeploy.tech/api/v1/apps/create -H 'Authorization: Bearer zdacc_...' -H 'Content-Type: application/json' -d '{"name":"my-app","stack":"hono-drizzle","needs":["postgres"]}' The sign-up code covers this first app, for 15 minutes. Every app after it needs the person's OK again: ask for a code to the account's inbox, ask the person for it, and send it as `"code"`: curl -s -X POST https://zdeploy.tech/api/v1/apps/create/code -H 'Authorization: Bearer zdacc_...' curl -s -X POST https://zdeploy.tech/api/v1/apps/create -H 'Authorization: Bearer zdacc_...' -H 'Content-Type: application/json' -d '{"name":"my-other-app","stack":"hono-drizzle","needs":["postgres"],"code":"123456"}' `stack` is the template the repo starts from: - `hono-drizzle` (the default): a Hono web service or API on Node, with Drizzle and Postgres. - `nextjs-drizzle`: a Next.js app (App Router) with Drizzle and Postgres. - `any`: any language (Python, Go, Rust, ...). The repo starts with a placeholder Dockerfile; you replace it with your stack's. The first two use Postgres, so pass `"needs":["postgres"]`. With `any`, pass `"postgres"` only if the app needs a database. Add `"redis"` if the app needs a cache or queue. The response (`data`) has: - `url`: the app's address. Tell the person. - `deployToken` (zda_...): the credential for building, deploying and setting up this app. Shown once: keep it. The app's own key for zdeploy's services is not in the response: zdeploy gives it to the running app (step 4), never to you. - `signIn`: the app's sign-in client. `issuer` and `clientId` reach the running app as `ZDEPLOY_AUTH_ISSUER` and `ZDEPLOY_AUTH_CLIENT_ID`; `redirectUri` is the one callback zdeploy registered (`$ZDEPLOY_APP_URL/api/auth/callback/zdeploy`: build it from that variable, never hard-code the host); `authEventsUrl` is where zdeploy sends auth events (step 4). - `git.pushRemote`: the repo's git remote with your push credential in it. Shown once. Use it to clone; never print it to the person or commit it. - `steps` and `next`: what zdeploy is still setting up, and what to do next. Setup ends by deploying the template's first build: its `build` and `deploy` lines stay pending until that build is done (a few minutes). To run a prebuilt image instead of a repo, send `"image":"registry/name:tag","port":3000` in place of `stack`, then skip to step 6. ## 3. Get the code The repo is made in the background. Check the status until its setup lines show `repo: done` and `code: done`: curl -s https://zdeploy.tech/api/v1/deploy/status -H 'Authorization: Bearer zda_...' Then clone it and read `AGENTS.md` at its root before you change anything: git clone '' my-app `git.pushRemote` is null when the account already had a git credential (its second app on). Then, or when you lost the remote or push from a new place, this issues a new credential and returns a remote for every app in the account. The old credential stops working, so update any clone with `git remote set-url origin `: curl -s -X POST https://zdeploy.tech/api/v1/git/credentials -H 'Authorization: Bearer zdacc_...' ## 4. Build the app Build on the template; do not start over. Its `AGENTS.md` says where things go. The rules zdeploy enforces: - Listen on the port in $PORT, and keep `GET /healthz` answering 200 once the app can serve. - The image is built from the Dockerfile at the repo root. - Database migrations run each time the container starts (the node templates do this already; with `any`, your Dockerfile must). Commit new migration files with the code; never run them by hand. - Do not edit `.gitea/workflows`, `.github/workflows`, `.gitleaks.toml` or `.gitleaksignore`. A push that touches them is rejected. - No secrets in the repo: a secrets scan of the full history fails the build. Store them with `deploy/env` (step 6). - A HIGH or CRITICAL vulnerability in the image fails the build. Keep dependencies current. - Never log in to zdeploy's image registry or push images to it (`docker login`): each push to main is built and pushed for you, and zdeploy pulls the image itself. A registry login on the person's computer only adds keychain prompts. When it runs on zdeploy, the app already has these environment variables. Do not put them in the repo, a `.env` or the Dockerfile: - ZDEPLOY_URL, ZDEPLOY_API_KEY: every service call goes to $ZDEPLOY_URL with the header `Authorization: Bearer $ZDEPLOY_API_KEY` - ZDEPLOY_AUTH_ISSUER, ZDEPLOY_AUTH_CLIENT_ID: sign-in, as an OpenID Connect public client with PKCE (no client secret) - ZDEPLOY_APP_URL: the app's own public https address, for redirect URIs, links in email and cron URLs. Do not store your own APP_URL. - DATABASE_URL (with postgres), PORT - REDIS_URL and REDIS_KEY_PREFIX (with redis): every key and channel name must start with REDIS_KEY_PREFIX (for BullMQ, pass it as the queue `prefix`), or Redis refuses it The node templates have a client for zdeploy's services at `src/lib/zdeploy.ts` (`zd`): email, file storage, AI models, memory, jobs, crons and sign-in. Use it. You can read it before the app exists, at https://zdeploy.tech/sdk/zdeploy.ts: it is the API reference for `zd`, every method with its typed arguments and result. Semantic search and your own vectors are Memory (its page below). The client may also have search and vector methods: they are not documented and are not offered for new apps, so do not use them; semantic search is Memory (`zd.remember`, `zd.recall`). With `any` there is no client: call the endpoints on the pages below over HTTP. Do not add another provider for something zdeploy offers. An AI call goes on the person's own provider bill, so do not put one behind a route anyone can call without signing in. Switch on each service the app uses before you write code for it. A new app has sign-in, AI models and abuse control on. Every other service is off, and its endpoints answer 403 until you switch it on with the deploy credential: curl -s -X POST https://zdeploy.tech/api/v1/services/enable -H 'Authorization: Bearer zda_...' -H 'Content-Type: application/json' -d '{"service":"email"}' `service` is one of the seven you can switch: auth, email, maas, memory, storage, jobs, verify. The service starts on the included tier; the response says what that covers and its price. The eighth, abuse control, is always on and free: there is nothing to switch. `GET https://zdeploy.tech/api/v1/services` with the same credential lists every service: on or off, tier, usage and limit. AI models are on, but chat, images and vision call providers with the person's own key, and answer 403 for a provider that has none. Pick the provider by what the app does: vision, and reading images into Memory, need an OpenAI key; image generation needs OpenAI or Google; chat takes any provider. A key link collects one provider's key, so ask for one link per provider the app needs. A new link cancels only the earlier unused link for the same provider. The model picked on the last saved link becomes the app's default. A key link is a secret: give it only to the person. To get one, ask zdeploy for a key link and give the person its `url`: curl -s -X POST https://zdeploy.tech/api/v1/maas/key-link -H 'Authorization: Bearer zda_...' -H 'Content-Type: application/json' -d '{"provider":"anthropic"}' On that page they paste the key, zdeploy tests it, and they pick the app's model. The key never passes through you. Poll `GET https://zdeploy.tech/api/v1/maas/key-link/` with the same credential until `status` is `done`; it then names the model, which is now the app's default. The link lasts 30 minutes; `provider` is optional. While the free trial runs and the app has no provider key at all, zdeploy provides models so you can build before the key arrives. The allowance is counted per account (the person who signed up), across all their trial apps, so another trial app adds nothing. Each kind has a daily allowance (rolling 24 hours) and a trial total; whichever runs out first stops it. Chat: 10 calls and 50,000 tokens a day, at most 140 calls and 700,000 tokens over the trial. Each free chat call: a prompt of at most 16,000 tokens, `max_tokens` at most 2,000 (that is the default when you send none), and no `web_fetch` or `web_search` tools, no `contextCompression`, no image or video input. Past one of these it answers 400 naming the limit. Images: 1 a day, at most 14 over the trial. Whatever model you ask for, the free one answers, and the `X-Zdeploy-Free-Use` header names it and what is left: `remaining` (calls today), `trial-remaining`, and for chat `tokens-remaining`. Past a daily limit it answers 429 naming the limit, with `Retry-After`; past a trial total, 429 saying it does not reset. When free use is used up platform-wide it answers 503 for everyone for a while. Vision is not covered. Adding any provider key ends free use for that app: its AI calls then go on the person's own provider bill. Embeddings need no key. The provider bills the person directly; zdeploy does not resell tokens. Before writing code for a service, read its page. Each has the exact endpoints, a first call that works, and the mistakes to avoid. Several pages are long (over 40,000 characters). If your fetch tool cuts pages short, add `?outline` to a page's URL for its headings, then fetch one section at a time with the link the outline gives for each heading (`?endpoint=` for an endpoint, `?section=` for anything else, such as Gotchas). Where a feature lives: search by meaning, your own vectors and claims are Memory; chat, embeddings, image generation and vision are AI models; file uploads are Storage; scheduled and one-off calls are Jobs; email checks are Verify; rate limits and URL checks are Abuse control. - Auth: https://zdeploy.tech/docs/auth.md - Email: https://zdeploy.tech/docs/email.md - AI models: https://zdeploy.tech/docs/maas.md - Memory: https://zdeploy.tech/docs/memory.md - Storage: https://zdeploy.tech/docs/storage.md - Jobs: https://zdeploy.tech/docs/jobs.md - Verify: https://zdeploy.tech/docs/verify.md - Abuse control: https://zdeploy.tech/docs/abuse.md The API describes itself: GET an endpoint that is only POST (`https://zdeploy.tech/api/v1/email/send`, say) and it answers with its own docs as markdown. An endpoint whose GET does real work, such as `GET https://zdeploy.tech/api/v1/services`, does that work instead; its docs are on its service page. `GET https://zdeploy.tech/api/v1` lists every page; the setup steps above, in full, are at https://zdeploy.tech/api/v1/control. Memory is search by meaning: send it readable text and it splits every document into passages for you (`zd.remember`, `zd.recall`), and search returns only passages close enough to answer: an empty result means not covered. Whole files go to storage. Memory cannot search encrypted text. If the app needs people to sign in, use the client: `zd.signInUrl`, `zd.finishSignIn` and `zd.verifyAuthEvent`. The template has none of the routes: add the four on the Auth page (sign-in, callback, `POST /api/auth-events` and sign-out). Sign-in is done when all four are served, `SESSION_SECRET` is set with `deploy/env`, your session is a signed httpOnly cookie, an auth event signs that person's other sessions out, and you dedupe events on their `id`. The redirect URI zdeploy registered is `signIn.redirectUri` from step 2. An app with sign-in MUST serve `POST /api/auth-events`. zdeploy registered that path for the app as `signIn.authEventsUrl` in step 2, so serving it is all you do. Until it is served, every auth event fails: after about two days of retries zdeploy blocks that user, and until then a stolen email change leaves the attacker signed in. Sign-in alone is not enough. Every webhook zdeploy sends is an RS256 JWT signed with the key at the issuer's JWKS, and its header `typ` names the purpose: `zdeploy-auth-event+jwt` for auth events, `zdeploy-job+jwt` for job calls, `zdeploy-webhook+jwt` for Memory and Verify. Check the one your endpoint expects: `zd.verifyAuthEvent`, `zd.verifyJobCall` and `zd.verifyWebhook` do it for you. To try sign-in, call `POST https://zdeploy.tech/api/v1/auth/test-user` with your deploy credential (`Authorization: Bearer zda_...`): it returns a throwaway `@test.invalid` user and a code, and `DELETE` on the same URL removes them. ## 5. Push, and wait for the build git add -A && git commit -m "..." && git push origin main Each push to main is built: secrets scan, image, vulnerability scan. Once the app is live, a built push deploys itself, unless the person turned auto-update off. Check the status every few seconds and read `data.build.state`: - `queued` or `building`: check again. - `built`: a live app is deploying it already; watch `data.phase` (step 6). Otherwise deploy it. - `failed`: `data.build.failedStep` names the step and `data.build.log` holds the end of its log. Fix the cause and push again. - `cancelled`: push again. - `no_code`: nothing is on main yet. - `unknown`: zdeploy cannot see the build right now. Deploy still works and runs the latest image of main. ## 6. Deploy and watch curl -s -X POST https://zdeploy.tech/api/v1/deploy/deploy -H 'Authorization: Bearer zda_...' It runs the build of the latest commit on main, and is refused (409, with the reason) until that build is built or while another deploy runs. Then check the status every few seconds until `data.phase` is `live` or `deploy_failed`. If it failed, the deploy events say why; the app's own output is under source app: curl -s 'https://zdeploy.tech/api/v1/deploy/logs?source=deploy' -H 'Authorization: Bearer zda_...' curl -s 'https://zdeploy.tech/api/v1/deploy/logs?source=app' -H 'Authorization: Bearer zda_...' Each later change is the same: push and wait for built. A live app with auto-update on deploys it by itself; `deploy/deploy` is for when it does not. Also with the zda_ credential: POST https://zdeploy.tech/api/v1/deploy/env `{"name":"NAME","value":"..."}` stores a secret, or replaces one you set earlier (send it again to fix a typo), and DELETE https://zdeploy.tech/api/v1/deploy/env `{"name":"NAME"}` removes one you set. A secret the person set in the console answers 409: ask them; POST https://zdeploy.tech/api/v1/deploy/services `{"service":"redis"}` adds Postgres or Redis. Both apply on the next deploy. You never hold the app key, so you cannot call the services from your shell. Test them with your deploy credential instead: `POST https://zdeploy.tech/api/v1/deploy/selftest` (`Authorization: Bearer zda_...`, no body) checks, as your app, every service that is switched on, and returns `{ data: { ok, results: [{ service, ok, detail, skipped? }] } }`. It sends no mail, calls no model and uses no quota. A result with `skipped: true` was not checked; jobs is checked only once the app is live. ## If zdeploy gets in your way, report it When something on zdeploy's side blocks you (an error you cannot fix, a step that does not work as written here, wrong docs), report it, then tell the person you did. It works with either credential or none, so a failed sign-up can be reported too. Never put credentials, keys or the person's secrets in it. curl -s -X POST https://zdeploy.tech/api/v1/report -H 'Content-Type: application/json' -d '{"doing":"what you were trying to do","happened":"what happened instead","expected":"what you expected","error":"the exact error text"}' `doing` and `happened` are required. The response has the report's id. ## Our MCP server, if you prefer tools The same actions as tools, at https://zdeploy.tech/mcp (streamable HTTP). It needs no account to start. claude mcp add --transport http zdeploy https://zdeploy.tech/mcp - With no credential: start_signup, verify_code. verify_code returns the command to reconnect with the account credential. - With the account credential: request_code, create_app, list_apps, git_credentials. create_app needs a code from request_code, bar the first app after sign-up. create_app returns `mcp.install`, the command to add the app's own server. - With the app's deploy credential (the `mcp.install` command from create_app): get_status, deploy, get_logs, set_env, unset_env, add_service, service_enable, service_disable. - With the account or deploy credential: revalidate, for the code after a pause. - With any of them: report_problem. Adding or reconnecting an MCP server may need your client restarted. If yours cannot do that mid-task, use the HTTP calls: they do the same. ## Links - Docs: https://zdeploy.tech/docs - Terms: https://zdeploy.tech/terms - Privacy: https://zdeploy.tech/privacy