Apps and deployments
Deploy a repo to a URL, with previews, live editing, bindings, secrets, schedules, logs and traffic.
An app is a repo deployed to a URL. In the API it's a Project: it builds the repo, serves it, and carries what the running code needs, from databases and buckets bound by name to secrets, schedules and domains. Every branch can deploy to a preview URL of its own; the production branch serves at the app's own URL.
Create an app
Name it in your code: from_name with create_if_missing=True creates the app the first time it's used and finds it every time after, setting the fields you pass (its repo, budget, deploy_on_push) each time. The same goes for the repo it deploys.
import noclick
repo = noclick.Repo.from_name("booking", create_if_missing=True)
app = noclick.Project.from_name("booking", repo=repo, create_if_missing=True)
print(app.url) # https://booking.noclick.siteNoClick reads the repo to choose how to build it (nextjs, remix, astro, vite, or static for plain files); pass framework= to choose yourself (Frameworks says which Next.js releases build, and what a site of files can't serve). The production branch is the repo's default branch unless you pass production_branch=. An existing app whose repo, runtime, framework or production branch differ from what your code says is updated to match.
Where it runs
Every deployment runs where its commit says, on one of two runtimes behind the same URL. An app's runtime is auto unless you pass one, and NoClick reads each commit it deploys and follows it literally, never rewriting code to fit. The first row that matches decides, so what the repo declares (a wrangler config, a Dockerfile) wins over what NoClick infers: a Next.js app that ships a Dockerfile runs in a container. It reads them in the app's folder: the repo's root, or the folder its noclick.json names as root.
| The commit has | It runs on |
|---|---|
A wrangler.jsonc (or wrangler.toml) naming its worker's main or its own build.command (The app's own build) | edge, from that config |
A Dockerfile | container, built from it as it's written |
A static site generator no build runs: its config beside its language's file (MkDocs or Sphinx with a requirements.txt, Jekyll with a Gemfile), or Hugo's (hugo.toml) unless its package.json installs Hugo (hugo-extended), or Jekyll's _config.yml with no Gemfile or package.json (a GitHub Pages site) whose pages use Jekyll's templates (a _layouts/ or _includes/ folder, front matter or Liquid in a page, an index.md home page) | nowhere: the deployment fails, saying to build the site into public/ (Jekyll's own into _site/), commit it and name it in a wrangler.jsonc ({"assets": {"directory": "public"}}, which then serves it, and which sign-in keeps when it adds its worker), or add a Dockerfile. A site of plain pages keeping _config.yml only for a Pages theme is served as its files |
| A JavaScript framework (Next.js, React Router, Astro, Vite, and those the build knows: SvelteKit, Create React App, Angular, Vue CLI, Gatsby, Docusaurus, VitePress, Eleventy, Hexo, Expo, Nuxt) | edge, but one with a Node server of its own (Express, react-router-serve, SvelteKit's node build) runs in a container |
A JavaScript framework beside a server in another language (a Vite app with a requirements.txt, go.mod or composer.json) | nowhere: NoClick won't guess which one the app is, and the deployment fails naming both. Pin runtime="edge" to serve only the site, framework="python" to run only a Python server, or add a Dockerfile |
A server in another language (Python, Go, Ruby, Java, PHP), or a Node server: a start script that runs anything but a preview of the site, a file server or a framework's development server (vite preview, serve, http-server, ng serve, gatsby develop, docusaurus start, vitepress dev, eleventy --serve, hexo server, expo start; those sites are built by their build script and served as files) | container, built by buildpacks |
| Only files | edge, served as they are |
On the edge the app's server code runs in isolates near its visitors, and its static files are served from everywhere. A container runs the server in the app's region, listening on 0.0.0.0 at the port in PORT and scaling to nothing while no one visits. That port is the app's PORT setting when it has one (a number), else the one its Dockerfile EXPOSEs, else 8080. K_SERVICE, K_REVISION and K_CONFIGURATION are the container runtime's own, so an app can't set them. A Python app without a Procfile starts on the app its code makes, under the server its requirements name: a Django project's wsgi, or a Flask or FastAPI app in a module at the root (app.py, main.py…), under gunicorn or waitress, uvicorn or hypercorn; one naming no server is refused saying which to add. Every container starts with NODE_ENV=production and FLASK_DEBUG=0, and a Python app's with DEBUG=False, unless the app sets them. A container that never starts fails its deployment with the last lines it printed, and its logs(kind="runtime") reads them.
Every request reaches a container through NoClick's front door, which tells it how the visitor reached it: X-Forwarded-Host, X-Forwarded-Proto and X-Forwarded-For, and the same in one Forwarded header. A framework builds URLs on the app's own host (redirects, url_for(_external=True), a sign-in's callback) and accepts its forms only once it trusts them: Django with USE_X_FORWARDED_HOST = True and SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https"), the app's host in ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS; Flask with app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1); Express with app.set("trust proxy", true). A redirect or cookie that names the address it runs at behind the front door reaches the visitor naming the app's own host instead. A visitor's requests go back to the instance that served them while it runs (on a cookie its host sets), which Socket.IO's long polling needs.
A container's disk is its memory: what it writes there is gone when it stops (after about 15 idle minutes, and at each release), and each instance it scales to has its own. Keep data in a bound database (a Postgres one arrives as DATABASE_URL, for its ORM) or bucket; a deploy whose code keeps SQLite or saves uploads to disk says so in its warning. Buildpacks install a Python app's requirements.txt, or its pyproject.toml with Poetry or uv, never a Pipfile alone (export one: pipenv requirements > requirements.txt), and a Node app's dependencies without its devDependencies, so a start script running tsx needs it in dependencies, and one running bun needs a bun.lock: a deploy is refused saying which before anything builds. A Dockerfile is built with BuildKit (RUN --mount, COPY --chmod; heredocs under a # syntax=docker/dockerfile:1 line). Each deployment names the runtime it ran on and why:
deployment = app.deploy().wait()
print(deployment.runtime, deployment.runtime_reason) # container the app's own Dockerfile describes its server, built as it's writtenA cookie an app sets for the whole apps domain (Domain=noclick.site) is kept for the app's own host alone, so a sign-in that names it works and no app reads another's. A commit that moves the app to the other runtime is released there, and the app's URL follows it; the release before it stays where it ran, so promoting it is a rollback like any other. runtime="edge" or runtime="container" pins the app whatever its commits have (an agent can force a container for a long job), and a framework= names its runtime too (python runs in a container). A runtime that isn't available in the app's region fails the deployment, saying why, before anything builds. Apps created before auto keep the runtime they were made with until app.update(runtime="auto").
app = noclick.Project.from_name("reports", runtime="container", framework="python", create_if_missing=True)Describe how your code runs in the standard formats, never one of NoClick's own. On the edge, a wrangler.jsonc naming its worker's main makes any repo a server app, whatever its framework, a plain site included. NoClick bundles the worker from that config and serves its assets.directory beside it as wrangler deploy does (an assets table naming no directory serves the folder the build made, as a site with no worker is published, handed to wrangler as --assets; with no build script, that fails the deploy): files first, so the worker answers only paths no file does, unless assets.run_worker_first runs it first (true for every request, or paths such as ["/api/*", "!/api/docs/*"]), honoring the folder's .assetsignore and assets.not_found_handling, html_handling and binding; it installs dependencies only when the repo has a package.json, from the lockfile of the package manager its packageManager names, else the first of pnpm-lock.yaml, yarn.lock, package-lock.json and Bun's, exactly as locked (a lockfile that doesn't match package.json fails the deploy: install and commit it again). A Next.js app needs nothing more than Next.js's own shape: NoClick builds it with OpenNext, and for each of the next.config, open-next.config.ts and wrangler config the repo doesn't have, the build uses OpenNext's default (your repo stays as it is); one the repo has is used as it is. The worker reaches the app's databases, storage, email and secrets through the SDK, never Cloudflare's own storage or account settings, which NoClick doesn't provide: a config binding them (d1_databases, kv_namespaces, r2_buckets, queues, ai, services and the rest), naming triggers.crons, or setting vars the app has no setting of fails the build, naming each and what to use instead (a binding, a schedule). Wrangler bundles the worker at the date and flags it runs with: the config's, with Node.js compatibility added (its second version for a date before 2024-09-23), and where the config names no compatibility_date, the one the app's first build used, kept from then on; a date still to come fails the build. Every module wrangler emits ships, typed by the config's own rules (a .sql file as text), and a worker with no default export, the service-worker format, fails the build. _redirects and _headers at the root of the files are applied as Cloudflare applies them, never served as files. Code that bundles but fails when a request runs it (child_process, reading the repo's files, native addons, Prisma without a driver adapter) is named in the deploy's build_warnings. In a container, NoClick builds the repo with its own Dockerfile (framework="docker") or, without one, with buildpacks, as a python or node app when it detects one.
Those files are the app's deployment script: a wrangler.jsonc naming what it builds, runs or serves (its main, its assets.directory), or a Dockerfile, which every deploy runs as written. A commit with code to build (a package.json, or a server language's file) and no script deploys as NoClick reads it, from the table above. When the first deploy of one of your account's own apps to production ran that way (it went live, or failed as the app's own), NoClick hands the app's coding agent the script to write itself: once an app, checked by a real build in the agent's own sandbox, charged to the agent's budget as any of its jobs, and named in that deploy's result or error as coding_job (operation_id, agent_id, for: script). It does so only for an account with NoClick's assistant, which ships what the agent pushed. Setting the app's framework or runtime instead overrides what its code is: leave them unset.
create makes an app outright and raises noclick.Conflict if the name is taken. Without repo=, it makes a new, empty repo of the same name for the app:
app = noclick.Project.create("status-page", framework="astro", user="acme")Created inside as_user (or with user=), an app belongs to that user, and what it spends counts toward their spend cap. budget_usd_per_month gives the app a budget of its own, so one busy app can't spend all of it:
with noclick.as_user("user_42"):
app = noclick.Project.from_name("booking", budget_usd_per_month=25, create_if_missing=True)The budget is a field like the rest: from_name sets the one you pass every time it runs, and left out it's never changed. An app with code always has one, so None raises noclick.InvalidRequest: raise it instead. app.update(budget_usd_per_month=50) changes it from anywhere. Limits and billing says what it covers and what happens when it runs out.
region= places the app's server code near a region, for good (your account's default, else us-east): put it with the database it binds, so its queries stay short. Its static files are served from everywhere. The region says where the code runs, not where data stays; residency belongs to the database and bucket the app binds.
The app's own build
When the repo says how it builds, NoClick runs exactly that, with no guess of its own; the deployment's runtime_reason names the file ("the app's own wrangler.jsonc ...", "the app's own Dockerfile ..."), and the build log names the script it ran.
On the edge, a wrangler config's build.command is the build, as wrangler deploy runs it: in a shell, from the config's folder (or its build.cwd), with the app's plain settings and NODE_ENV=production. Nothing of NoClick's own for the app's framework runs (no build script of package.json, no OpenNext defaults, no Expo export), and what the config names is published: its worker (main, bundled by wrangler at its date and flags), else its assets.directory, served by its not_found_handling, html_handling and .assetsignore. Where NoClick differs from wrangler deploy: it installs the dependencies first, from the lockfile (wrangler expects a machine that already has), unless one of the command's steps installs them itself (npm ci && npm run build), which then runs as an install runs, with no NODE_ENV; it serves a 404.html for a path no file answers when the config names no not_found_handling (wrangler's default answers nothing); and a config with a build.command naming neither main nor assets.directory fails the deploy, as wrangler refuses it.
// wrangler.jsonc
{
"build": { "command": "npm run build:site" },
"assets": { "directory": "./dist", "not_found_handling": "single-page-application" }
}A field NoClick can't honour fails the build naming it, never dropped: Cloudflare's own bindings and crons (above), routes/route (add the app's domains instead), tail_consumers, a compliance_region other than public, and limits.cpu_ms past 30,000 (one up to it is the worker's own CPU limit). The fields that name or tune a Worker on a Cloudflare account of its own (name, account_id, workers_dev, preview_urls, observability, dev, env) aren't needed, since NoClick gives the app its addresses and keeps its logs; placement, upload_source_maps and logpush are noted in the build log, NoClick placing the worker near the app's region and keeping its logs itself; a field NoClick doesn't know is a build_warnings entry. A site of files is released at its config's compatibility_date and flags too.
In a container, a Dockerfile is the build, built as it's written (BuildKit), its EXPOSE the port the app is sent requests on.
noclick.json
What no standard file says goes in a noclick.json at the repo's root: the app's folder in a monorepo, the Node.js its edge build runs on, and the settings its build needs.
{
"root": "apps/web",
"node": 24,
"build_env": ["VITE_SUPABASE_URL", "VITE_SUPABASE_ANON_KEY"]
}root: the app's folder, from the repo's root. Its install, its build, its wrangler config orDockerfileand where it runs are all read there, and every failure names it. An app without a lockfile of its own installs at the nearest folder above it that's the root of a workspace holding the app's folder (itspnpm-workspace.yaml'spackages, or itspackage.json'sworkspaces) with a lockfile, as the workspace installs, and its own wrangler or OpenNext is the one Node finds from its folder, one the workspace hoisted to its root included; a container is built with the folder as its context. Sign-in is added in the folder too, the lockfile it updates being the one the app installs from. A live session runs the app there too: its dev server in the folder, its dependencies installed where a build installs them.node: the Node.js major an edge build runs on,22(the default),24or26; any other fails the deploy naming those. A container'sDockerfile(itsFROM) orpackage.json'sengines.nodenames its own, sonodethere fails the deploy. A live session runs its dev server, its install and its end's build on the same Node.js.build_env: setting names the build needs. A deploy fails before it builds naming each the app doesn't set as a plain setting (or in a committed.envfile), or has only as a secret, which never reaches a build: never built in asundefined.
Any other key fails the deploy naming it: how the app builds and runs is its wrangler config's or Dockerfile's. Its schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "noclick.json",
"description": "How NoClick builds an app where no standard file says it, at the repository's root. How the app builds and runs is its own wrangler config's (build.command, main, assets) or Dockerfile's.",
"type": "object",
"properties": {
"$schema": {
"type": "string"
},
"root": {
"type": "string",
"pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$)).+$",
"description": "The app's folder in the repository, from its root (\"apps/web\"): its install, build, wrangler config or Dockerfile, and where it runs are read from there. An app without its own lockfile installs with the nearest workspace above it that has one. A container is built with that folder as its context."
},
"node": {
"enum": [
22,
24,
26,
"22",
"24",
"26"
],
"description": "The Node.js major an edge build runs on (22 unless named). A container's Dockerfile or package.json engines.node names its own."
},
"build_env": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
},
"description": "The settings the build needs (VITE_SUPABASE_URL): a deploy is refused naming each the app doesn't set as a plain setting (or in a committed .env file) before anything builds, never built in as undefined."
}
},
"additionalProperties": false
}Size a container
A container runs each instance at 1 vCPU and 512 MiB, up to 10 at once, with CPU only while a request is open, 5 minutes a request, and none while nobody visits. The app's container settings change that:
| Setting | What it does | Raise it when |
|---|---|---|
cpu | vCPUs per instance: 1, 2, 4, 6 or 8, or 0.5 to 0.99 (which answers one request at a time per instance) | requests wait on computation |
memory | MiB per instance, from 512: up to 1024 under 1 vCPU, 4096 at 1, 8192 at 2, 32768 at 8 | it runs out of memory: an ML model, a headless browser |
min_instances | instances kept running while production serves it, 0 to 3 | its first visitor after a quiet spell waits seconds for one to start |
max_instances | the most at once, 1 to 10 | lower it to cap what a flood costs |
cpu_always | CPU between requests too, each instance billed from start to stop; 1 vCPU or more | its code works with no request open: a bot, a queue worker, a loop on a timer |
request_timeout_s | how long a request may stay open, 1 to 3600 seconds | a socket or a stream is cut at 5 minutes |
A bot that must always run needs cpu_always and a min_instances of 1: an idle instance otherwise stops about 15 minutes after its last request. It still listens on 0.0.0.0:$PORT (a health page will do), or it never starts. Settings left out keep their value; container=None resets them. min_instances applies at once, to the release production serves, so lowering it stops what it costs then and there; the others apply from the next deploy or promote, since each release runs at the settings it was released with. The answer's notes say which applied when. Only the release production serves keeps instances warm; previews, paused apps and apps in the trash keep none.
app = noclick.Project.from_name("ticket-bot")
app.update(container={"cpu_always": True, "min_instances": 1})
print(app.container.idle_usd_per_month, app.container.note)
app.deploy().wait()
classifier = noclick.Project.create("classifier", repo=repo, runtime="container",
container={"cpu": 2, "memory": 8192}, budget_usd_per_month=40)A setting past its bound raises noclick.InvalidRequest naming it (container.memory: "4 vCPU takes 2048 to 16384 MiB of memory"), and so do warm instances whose idle cost alone passes the app's budget_usd_per_month: keep fewer warm, or raise the budget with them.
What a size costs
Each instance costs what NoClick's provider charges for its vCPUs and memory, by the second, nothing added:
| A vCPU, an hour | A GiB of memory, an hour | |
|---|---|---|
| Answering requests (CPU only during requests), plus $0.40 a million requests | $0.0864 ($0.12096 in ap) | $0.009 ($0.0126 in ap) |
| A warm instance with nothing to answer | $0.009 ($0.0126 in ap) | $0.009 ($0.0126 in ap) |
With cpu_always: every second an instance runs, warm or not, and no per-request fee | $0.0648 ($0.07776 in ap) | $0.0072 ($0.00864 in ap) |
app.container.idle_usd_per_month is what its warm instances cost a month with nothing calling it: about $9.86 for one at the defaults, $49.93 with cpu_always. An estimate takes the same container settings.
Frameworks
Unless the app names a framework, each build reads it from the commit's package.json: next builds as nextjs, React Router in framework mode (@react-router/dev) or Remix (@remix-run/dev, @remix-run/react) as remix, astro as astro, vite as vite, and anything else, or no package.json, as static. react-router or react-router-dom alone is a library a client-side app routes with, so a Vite app using it builds as vite. A framework or site generator the build knows decides before a vite the app lists only for its tests or Storybook: Create React App (react-scripts), Angular, Vue CLI, Gatsby, Docusaurus, VitePress, Eleventy, Hexo, Expo and Nuxt build as static, SvelteKit (@sveltejs/kit) as vite (unless the build script runs vite and the tool isn't on Vite: an app moved to Vite with react-scripts left behind builds as vite). The framework is the app's, never one deploy's: deploy takes none. Change it on the app, and it applies from the next deploy; None goes back to reading it from each commit. A framework the app names always decides; when the commit's code builds as another, the deployment's runtime_reason and its build log say so, with the fix.
app = noclick.Project.from_name("booking")
app.update(framework="nextjs")
app.deploy().wait()Next.js releases. NoClick builds Next.js with OpenNext 1.20.12, which builds Next.js 16 from 16.4.1 on: put "next": "^16.4.1" in package.json. It builds Next.js 15 from 15.5.28 only until 21 October 2026, when the Next.js team stops supporting 15, and no release of 14 or older. A deploy whose package.json asks for a release it doesn't build fails before anything builds, naming the releases it does; one whose lockfile installs such a release stops right after installing, before the Next.js build. When an upgrade fixes it (an older release), its error and the deployment carry fix, {"kind": "next_upgrade", "found": "^15.3.0", "needed": "^16.4.1"}, and its next_step hands the upgrade to the app's coding agent (POST /v1/projects/{id}/live/changes with the title "Upgrade Next.js to 16"), which runs Next.js's upgrade codemods, updates the lockfile, builds and fixes what they leave, then pushes; deploy again once the preview of its work is good. Or make it yourself: npx @next/codemod@latest upgrade 16 --yes, commit, then npx @next/codemod@latest next-async-request-api .; take out the export const instant = false the upgrade writes into pages and layouts (it fails the build unless the app turns on cacheComponents), and keep a middleware.ts it renames to proxy.ts as middleware.ts, since OpenNext runs a Node.js proxy on Cloudflare only experimentally. A static export (output: "export" in next.config) is built by next build alone, never OpenNext, whatever its release, and published from out/ as a site of files. OpenNext keeps ISR's cache and next/image's optimization in Cloudflare resources NoClick doesn't provide, so an app that revalidates pages, or uses next/image without images: { unoptimized: true }, gets a build_warnings entry saying so.
What a site of files publishes. static serves plain files as they are: the repo's public/ folder, or its root when it has no public/ folder or keeps an index.html there. The root is published only when it's a site: it has an index.html (one with no package.json, a ZIP and a README say, is served as it is without one), and none of a server's code (a server language's project file or source such as requirements.txt, Cargo.toml or a .php file; a .py file is the site's own when a page loads PyScript or Pyodide; a Dockerfile anywhere, code in a server/, backend/, api/ or functions/ folder, a server.js, the file the start script runs); otherwise the deploy fails naming what's there: put the site's pages in public/, or run the server from a Dockerfile at the root or a wrangler.jsonc naming its main. One whose package.json has a build script publishes only what its build made, the first of dist/, build/, out/ and .output/public the build wrote or changed, never the repo itself with its source and package.json, nor one of those folders committed and left as it was; a build that made none of them fails the deploy. vite and astro publish the dist/ folder their build makes. A tool the build knows publishes where its build leaves the site: Create React App's and Docusaurus's build/, Gatsby's and Hexo's public/, Eleventy's _site/, VitePress's .vitepress/dist in the folder it builds, Vue CLI's dist/, Angular's outputPath in angular.json (its browser/ folder on Angular's application builder), SvelteKit's adapter-static pages folder (build/), and Expo's web build, which NoClick makes with expo export --platform web into dist/ unless the build script runs expo export (an output flag in the build script, --output, --out-dir, moves it). A single-page app (Create React App, Angular, Vue CLI, Expo's single page, SvelteKit with a fallback page, any app routing with react-router) answers a path no file is with its index.html, unless it has a 404.html; a Vite app's always does. For every one of them, a wrangler.jsonc naming no main declares the folder instead, and how it's served, as Cloudflare reads it: {"assets": {"directory": "./www", "not_found_handling": "single-page-application"}}; so does a Cloudflare Pages config's pages_build_output_dir. What a build publishes this way must be a site, or the deploy fails saying why and what to change: it has an index.html, the page at /; it holds no server code anyone could download (a server/ folder of it, or the file the start script runs); and the build made no server beside it that nothing would run (Nitro's .output/server, which Nuxt and TanStack Start build unless told to build for Cloudflare, or a dist/server); and its page loads its files from the site's root, never from under a base path made for GitHub Pages (Vite's base: '/repo/', Create React App's homepage), which would show a blank page: remove it. A public/ folder of plain files with no build is served as it is, a home page or not.
What a site's files are. Whatever folder a site is published from, its .assetsignore leaves files out, read exactly as git reads a .gitignore (**/x.map matches at the top too). Nothing whose name starts with a dot (.env, .git/) is ever published but the .well-known/ folder at its top (app links, security.txt; an apple-app-site-association is served as JSON), and neither is node_modules, package.json, a lockfile, a wrangler config or a database's journal (-wal, -shm), whatever .assetsignore says. A database file (.sqlite, .sqlite3, .db) is published only when one of the site's own published .js or .html files names it (a sql.js site fetching its data), else left out, the build log naming it. Source maps (*.map) are left out too, unless .assetsignore keeps them with the line !*.map (for Vite or Astro, in public/.assetsignore, which the build copies into dist/). A link is published as what it leads to, only when that's a file the same folder publishes; one leading elsewhere fails the deploy naming it, and so does a file that holds Git LFS's pointer in place of its content, or a Cloudflare Pages _worker.js (build such an app for Workers: Astro's @astrojs/cloudflare with a wrangler.jsonc naming its main). A build may publish 20,000 files, each at most 25 MB: past either, it fails naming the largest files, or where most are; large media goes to a public bucket, loaded from its URL.
What a build can't serve. A deploy fails before anything installs, saying what to change, when its code is built for somewhere else: a SvelteKit app on any adapter but @sveltejs/adapter-static (a site of files) or @sveltejs/adapter-cloudflare (rendered on the server; before 8, which builds for Cloudflare Pages unless a wrangler config names its worker, the build gives its own copy of the app a wrangler.jsonc naming .svelte-kit/cloudflare/_worker.js as its main, keeping the settings of a config the repo has, and says so in its log), or on @sveltejs/adapter-node with no start script (with "start": "node build" it runs in a container); an Expo app with no web support (react-native-web, react-dom) or web.output "server"; a Cloudflare Pages config with Pages Functions in functions/, which NoClick doesn't run (move them into a worker named as main); an app on @cloudflare/next-on-pages (NoClick builds Next.js with OpenNext); and a repo with no package.json at its root but an app in a folder of it (client/, frontend/), since NoClick builds from the root: name that folder as root in a noclick.json, or add a root package.json whose build builds it, or a Dockerfile. An app whose wrangler config names its own build.command meets none of these but the Pages Functions one: its command builds it as its framework would. Create React App stops on its lint warnings because builds set CI: fix them, or set DISABLE_ESLINT_PLUGIN to true in the app's settings.
A site of files runs no code. Neither static nor vite runs an API route, so a pages/api/* file or an app/**/route.ts handler would never answer, and neither would another host's functions (Vercel's api/, Netlify's netlify/functions/, Cloudflare Pages' functions/): a deploy that has one fails before it builds, naming each. Build the app as nextjs to serve them, or answer them from a worker of the app's own, a wrangler.jsonc naming its main (Where it runs).
Deploy
deploy builds the production branch at its head and returns an operation. Once the build is ready, the app's URL serves it:
app = noclick.Project.from_name("booking")
deployment = app.deploy().wait()
print(deployment.status, deployment.url, deployment.commit)A Deployment goes queued, building, then ready, failed or canceled. Pass commit= to deploy an earlier commit rather than the head. app.production is the deployment serving the URL now, and app.deployments() lists them all, newest first.
Every deployment (a site of files, a worker, a Next.js app, a container) is asked for its home page and the app's check paths as soon as its URL serves it (seconds, at most 90 while the route to it changes everywhere), with plain requests and no browser. The home page is also asked as a phone's browser asks for it (a server can answer a phone otherwise), and a production release's at each of the app's own domains. Its home page must answer 2xx (a redirect on its own address is followed), and each script and stylesheet it names on its own address must load as one: a 404, or a script answered with the page's HTML (a build's base path set for another address), shows a blank page. When the home page answers anything else, sends visitors to another site (a sign-in service that doesn't know this address), or a file it names doesn't load; when another page answers 500 or more, a check path answers other than it asks, or nothing answers, the deployment stays live (nothing is rolled back), but the operation's result carries a warning saying what answered, with the error the app logged, and a next_step saying what to fix: it's live, not working. A site of files in public/ with no index.html gets the warning too, though it may mean to serve only its files; then there's nothing to fix. noclick deploy prints both and exits 1. A container release that would replace what production serves is asked first, at production's own address with its requests sent to it alone: one that fails isn't put live, its deployment fails saying what answered, and production keeps serving the release before it. An app whose / doesn't answer 2xx by design (an API's 404, a sign-in wall's 401) names what it answers in its check paths ({"path": "/", "status": 401}). Read the app's runtime log (Logs and usage) when the step says so, fix the cause and deploy again. Only when an answer that failed didn't come from this release (its route still changing) does the step say to check again in a minute first. When the app's static files answer every path asked (a site in public/ with a worker behind /api/, asked only for /), its code is also asked at /.noclick/, where no file is: any answer below 500 shows it runs, and a crash there is the warning. When even that path can't reach its code, the result's code_unchecked says so: add one of its code's routes to the app's check paths.
Preview a branch
Deploy any other branch and it gets a URL of its own, while production keeps serving what it did:
app = noclick.Project.from_name("booking")
repo = noclick.Repo.from_name("booking")
repo.commit({"app/routes/book.tsx": "export default function Book() { return null; }\n"},
message="Try the new booking form", branch="new-form")
preview = app.deploy(branch="new-form").wait()
print(preview.url) # https://new-form--booking.noclick.siteA preview's hostname is one DNS label, <branch>--<app>. A branch that's already lowercase letters, digits and -, and fits, is used as it is; any other is lowercased, with /, _ and anything else a hostname can't hold turned into -, shortened to fit, and given a short hash of its name, so two branches never share a URL: feature/New_Form serves at feature-new-form-7cb00e--booking.noclick.site. preview.url is where it serves; read it rather than building the name yourself. A branch's newest preview serves for 30 days after its deploy; after that its URL says the preview expired until the branch deploys again.
When you're happy with it (check it first), promote makes that build production without building it again, released with production's secrets:
preview.promote().wait()Every promote bookmarks production's databases just before production switches, so undoing it (promoted.undo(), see Undo) restores them with the release before, taking back what was written to them since. Nothing is lost for good: each database's restore keeps what it held just before in the trash for 30 days, as a database copy. The promote's operation says what the undo takes back before you undo it (undo_rewinds, undoRewinds in TypeScript), and the undo's result says it again (warning), naming each copy and how it goes back (copies: undo that database's restore, or restore the copy from the trash). So an agent undoes a promote without asking anyone, as it deletes to the trash.
A preview gets the secrets set for previews (see Keep secrets), so it can use a test key where production uses a live one, and its own data: see A preview's own data.
Who opens a preview
A preview is public: anyone with its URL opens it, and everything it answers tells search engines not to list it. To keep an app's previews to the people you hand a link, set preview_access to link. Production is always public. An app whose previews run in containers (a Python or Go server, a Dockerfile) can't be set to link yet: a container also answers anyone at its own address on the container host, so a link couldn't be the only way in. Setting it is refused saying so, and works once NoClick turns on front-door-only containers. A preview of a link app whose commit would run in a container isn't built, saying the same.
app = noclick.Project.from_name("booking")
app.update(preview_access="link")
preview = app.deploy(branch="new-form").wait()
print(preview.preview_link) # https://new-form--booking.noclick.site/?preview=p2~...
another = app.preview_link(branch="new-form", expires_in=24 * 3600) # one good for a day
app.revoke_preview_links() # every link made before now stops opening its previewsA preview's deploy answers its link beside its URL (preview_link), and preview_link() (POST /v1/projects/{id}/previews/link) makes another, for a branch or the newest preview, good for 7 days unless you ask for between 5 minutes and 30 days. The browser that opens a link keeps a cookie for that preview alone and lands on the same page without the token; anyone opening the preview without one is told it's private and to ask the app's owner for its link. A link lasts until it expires, unless you stop every link made so far: revoke_preview_links() (revokePreviewLinks(), POST /v1/projects/{id}/previews/links/revoke) turns away each one, and the cookie it left in a browser, within 30 seconds, while links made after open the previews as before. Use it when a link reached someone who shouldn't have it. NoClick's own checks of a preview (a deploy's look at its home page, check) still get in.
What calls a preview without a person's browser is turned away too: a webhook's sender, an OAuth provider sending someone back to the app's sign-in callback, a payment service's notification. When a preview has to receive one, leave its path open with preview_public_paths: up to 10 paths of up to 80 characters, each exact (/auth/) or everything under one (/api/). A path left open is open to anyone, so its code should check what calls it, a webhook's signature say.
app.update(preview_public_paths=["/api/webhooks/*", "/auth/callback"])Over MCP, resources_save with "settings": {"preview_access": "link"} sets it on an app, api_call with projects_previews_link makes a link, and api_call with projects_previews_links_revoke stops every link made before.
A preview's own data
Each branch is an environment of its own. Its code names the same bindings and the same from_name names as production's, and reaches its own copy of each one, so nothing a preview writes ever reaches production's data. Promoting deploys the code, never the preview's data.
A copy is made the first time the branch writes to the resource. Until then the preview reads production's as it is now, read-only, so a branch that only reads costs nothing:
| Resource | What the branch gets |
|---|---|
| Postgres database | a copy-on-write branch of production's data, at its first write (or its first writable connection URL: a container preview's DATABASE_URL, at its deploy) |
| SQLite database | production's schema and migrations, none of its rows, at its first write; its rows too when the code asks (below) |
| Bucket | an overlay, at its first write: what the branch writes and deletes is its own, and every other file reads through from production's |
| Dict | a copy of its keys, the first time the branch uses it |
| Queue | an empty queue of its own, the first time the branch uses it, so production's messages are never taken |
Migrations follow the same rule: a preview's code migrates its copy, and production's database changes when production's code runs the migration, after you promote. Each copy is an ordinary resource you can list and open, named after the original and the branch (orders.new-form-3f9a1c), billed for what it stores and does like any other. A Postgres copy is a branch of production's database, which shares its storage until either changes: a database and its branches include 25 together, and each branch past that costs $1.50 a month, by the hour it exists, on top of its compute and storage. Copies of the other kinds cost only what they store and do.
A SQLite copy starts with the schema alone, so once the branch writes, it no longer sees production's rows. Give previews something to show in one of two ways:
# Sample rows: db/seed.sql, beside db/migrations/, runs once on the branch's fresh copy.
db = noclick.Database.from_name("orders", create_if_missing=True)
db.migrate("db/migrations/")
# Or production's rows themselves, copied at the branch's first write.
db = noclick.Database.from_name("orders", create_if_missing=True, branch_data="copy")A seed runs after the migrations, in their transaction, on a branch's database that holds none of production's data (a SQLite copy without its rows, or a database only the branch has, of either engine). It runs once, shows in migrate's applied and the ledger as (seed), and never runs in production; pass seed= to name another file. branch_data="copy" copies production's rows from one moment's read while production keeps serving, for a database of up to 200,000 rows and 16 MB (past that the write that makes the copy raises noclick.QuotaExceeded, and a seed is the way). Asked for after the branch's copy was made without them, that copy goes to the trash and the branch's next write makes one with them. Rows copied are billed like rows written. A Postgres copy always holds production's data, so neither changes it.
A branch's copies go to the trash 72 hours after its last deploy, visit to its preview URL or call from its code, when the branch is deleted, and with the app; the next deploy starts it fresh. An account keeps at most 50 branches' environments, and a new one past that retires the one idle longest. A preview's deploy says all this in its operation's preview_data and the deployment's (preview.preview_data), naming what the app binds: never give a person a preview to keep real data in.
To have an app's previews use production's resources from the start, create it with preview_resources="shared" (Project.create, or settings in MCP's resources_save). Apps made before branched previews share production's resources with their previews until you switch them:
app = noclick.Project.from_name("booking")
app.update(preview_resources="branch") # or "shared": previews use production's
print(app.preview_resources)What a preview reaches
A preview's code reaches nobody real. Each deployment's credential says which environment it runs in, and everything with an effect outside NoClick reads it:
| Production | A preview | |
|---|---|---|
| goes to anyone | goes to you and the members of your workspaces; every other copy is kept in the preview's outbox, never sent or charged | |
| Connections | read and write | read; a write is refused unless the connection is marked a test account |
| Payments | the live key | the key set for previews, such as a test one |
| Agents | talks to them in the app's threads | reads the app's threads; starts no turn, since an agent acts for real |
| Anything else that reaches someone (an inbox's mail, a browser, a webhook test) | as your own code would | refused |
| Calls and texts | not the app's to make | not the app's to make |
Read what a preview would have sent with app.email.messages(environment="preview"). Promoting a preview releases it with production's credential, so the same build then reaches everyone.
Check it works
A build that's ready isn't one that works. check loads pages of a deployment where it serves (its preview URL, or the app's URL in production) in a browser, one after another, and says what each showed:
preview = app.deploy(branch="new-form").wait()
checked = preview.check(["/", "/book"]).wait()
print(checked.passed)
for page in checked.paths:
print(page.path, page.status, page.load_ms, page.problem)
for error in page.console_errors:
print(" ", error["kind"], error["message"])
print(" ", page.screenshot["url"])A path is a page of the app, never an anchor (/#menu): the paths load one after another in one tab, where a jump to an anchor of the open page never finishes loading. A path fails when it answers 400 or more, doesn't finish loading within 30 seconds, a script on it throws and nothing catches it, or a picture it shows doesn't: each file its <img> elements name (src and every srcset candidate) is loaded and decoded as the browser shows it, so a missing file, or text committed in an image's place, fails it, named in the path's broken_images. On a site of files (no server code, and not a single-page app), a page the deployment has no file for isn't loaded at all: it fails with missing_from_deployment true, since a browser would only show the host's 404. Other console errors (a console.error, another file that failed to load) are reported without failing it. So is each address the page shows (a mailto: link or its text) whose domain takes no mail, with no MX record: it's named in the path's undeliverable_emails. Each screenshot is kept as one of the account's files, so the chat can show it. The check runs in a browser billed at its provider's price, by the second, and the deployment keeps its latest outcome as last_check.
Give it the site's brief and a model looks at the screenshots too, against NoClick's design rubric: POST /v1/deployments/{id}/check with {"paths": ["/"], "review": {"brief": "A booking page for Le Comptoir, a bistro in Lyon"}} (MCP: deployments_check). The result's review scores the pages 1-5 on whether they belong to the business, the first screen, type, colour, images, the phone, finish and what reads as generated, and lists the issues to fix, each with where it is; passed is true when every score is 4 or more. It's one call to a small model that reads images, billed as AI usage at the model's price and counted in the check's cost_usd; a review that couldn't answer says why in review.error and leaves the check as it was. An app's screens, which people use rather than read, take the app rubric instead: "review": {"brief": "A study library for one pilot", "rubric": "app"} scores each screen's task, forms, empty and loading states, density, tap targets, type, navigation and finish, and lists no claims.
A page its scripts render after it loads (one that asks the app who's signed in, then draws) is judged too early unless the check waits for it: wait_for takes a CSS selector, and each page is judged once an element matching it shows, up to 20 seconds after it loads (a page it never shows on fails). settle_ms watches each page longer before its screenshot (1,000 by default, at most 10,000), and its console errors until then count. A page behind a sign-in is checked signed in: headers go with each request the pages make to the deployment's own address, never to another site, and cookies are set on that address alone:
import os
checked = preview.check(
["/library"], wait_for="main#docs",
cookies=[{"name": "session", "value": os.environ["TEST_USER_SESSION"]}],
review={"brief": "A study library for one pilot", "rubric": "app"},
).wait()
print(checked.review.scores, [issue["fix"] for issue in checked.review.issues])They're secrets: kept sealed only until the check runs, never in its result, its log or its operation, which names them by name alone.
Without paths it loads the app's check_paths, else its home page. Set them, and they gate every promote:
app.update(check_paths=["/", "/book"])
preview.promote().wait() # checked first: raises noclick.OperationFailed if a path failsA check path is a page, loaded in a browser, or what a plain request must answer: {"path": "/api/health", "status": 200} passes on that status alone (without one, on any below 400), and "json": True asks for a JSON body too. Name your code's routes this way: a page the app's files serve never runs its code, so a check of / alone passes a worker that fails every API call (the check's code_unchecked says so). A request is no page, so it has no screenshot, console errors or review, and a check of requests alone opens no browser. check takes them too, and Project.create takes the app's from the start:
app.update(check_paths=["/", {"path": "/api/health", "status": 200}, {"path": "/api/bookings", "json": True}])A promote checks the release where it serves before production switches to it, then again at the app's URL once its route there has settled, since production runs it with production's secrets and bindings; one that fails either isn't promoted (production goes back to what it served before), and the operation's error carries the check. promote(force=True) puts it live without the checks. A rollback to an earlier release (which no URL serves now) is checked once production serves it. Whatever the app's check_paths, every promote and rollback then asks its home page as a deploy does, once production serves it: one that answers wrong stays live, and its deployment's warning says what answered. A deployment's serves names each URL it answers now: a promoted preview serves production and its branch's preview alike, while its environment stays the one it was built for. A promote releases the build it has, never building again, so what its build read of the app's settings (a VITE_ or NEXT_PUBLIC_ value put in its pages) stays as it was: when a setting changed since, the promote's settings_changed names it, and deploying production again builds with the settings as they are.
requests() says how a deployment's real traffic went, from NoClick's record of each request it answered, its static files included: how many in the last 24 hours (or since since=, up to 7 days back), by status, the error rate (answers of 500 or more, and requests never answered) and the slowest routes:
outcomes = app.production.requests()
print(outcomes.requests, outcomes.error_rate, outcomes.by_status) # 1204 0.0025 {'200': 1180, '404': 21, '500': 3}
for route in outcomes.slowest_routes:
print(route.method, route.path, route.p95_ms)It reads the newest 2,000 requests; past that sampled is True, as it is when a very busy app's record is a sample, each request in it counted for the ones it stands for. On the edge runtime a request's time runs until the app's answer begins.
When a build fails
A failed build fails the operation with noclick.OperationFailed, whose deployment_id names the deployment. Its build log says why, and the error's next_step what to change. Production keeps serving the last good deployment. A commit that can't build as it's written fails before anything builds or is charged, its error saying what to change: a framework app with no package.json, a Next.js release OpenNext doesn't build, or API routes on a site of files (Frameworks); a public value the code reads that the build would write in as undefined (Plain settings); an .npmrc or .yarnrc.yml reading a private registry's token that the app has neither as a setting nor as a secret, or that a container's Dockerfile never mounts (Keep secrets); a setting a noclick.json's build_env names that the app doesn't set; or a dependency fetched from git over SSH, which a build has no key for. A deploy that went live says what its build warned of in its result's build_warnings.
Every failure says whose it is, as the deployment's failure and the error's: app (its code, settings or config: a failed install or build, a refusal at publish), limit (one of the app's limits: the build's time or memory, the size of its source or what it publishes) or platform, NoClick's own (its build machine ending, its build tooling crashing, a host failing). A platform failure has platform_error set and an error_id, NoClick is alerted, and the deploy isn't charged: changing the app won't fix it, so don't work around it in the app; tell whoever the app is for, with the error_id. A failure a known change fixes says which as fix, on the error and the deployment, by its kind: next_upgrade, an older Next.js to upgrade (Next.js releases). A commit that can't build as it's written fails before anything builds or is charged, its error saying what to change: a framework app with no package.json, a Next.js release OpenNext doesn't build, or API routes on a site of files (Frameworks).
A production deploy of one of your account's own apps that failed as the app's own (never platform or limit), started by you or NoClick's assistant (a deploy or a push), of an app with a coding agent, goes to that agent with its error and its build log's last lines (on an account with NoClick's assistant), to fix its deployment script or its code in its own sandbox, check with a real build, and push: the error's coding_job (for: fix) names that job, and NoClick's assistant ships its fix as it ends, so its next_step says not to fix it yourself. At most two such jobs go to it in a row, counted since a release last served production; the next failure is told to the account's owner instead (the error says owner_told), once until a release serves production again.
app = noclick.Project.from_name("booking")
try:
app.deploy().wait()
except noclick.OperationFailed as failed:
broken = noclick.Deployment.get(failed.deployment_id)
print(broken.error)
for line in broken.logs(kind="build"):
print(line.message)cancel() stops a deployment that's still queued or building.
Roll back
rollback serves an earlier deployment again without rebuilding, live within a minute. It's released again first with the app's settings, secrets and bindings as they are now, so a key you revoked or rotated since never comes back with it, and a container gets new database logins (a second or two for a site; a container starts a new revision, which can take a minute):
app = noclick.Project.from_name("booking")
earlier = [d for d in app.deployments(branch="main") if d.status == "ready" and not d.production]
app.rollback(to=earlier[0]).wait()Rollback without a build covers the app's last 10 production deployments. One older than that was retired; rolling back to it builds its commit again with today's settings and secrets, the operation's wait() gives the new deployment, and its rebuilt says so. An app with check_paths checks the release once production serves it, a rebuilt one too, and goes back if it fails (Check it works). Every rollback asks its home page once it serves, and its warning says what answered wrong. A rollback to a release from before one of the app's Durable Object classes parks the class, its data kept (parked).
Deploy on push
deploy_on_push makes a push deploy by itself, whether it's a git push or a commit through the API: with production, every push to the production branch deploys it; with all, a push to any other branch deploys a preview of it too. It's off until you set it, so only deploy() deploys.
app = noclick.Project.from_name("booking", deploy_on_push="production", create_if_missing=True)
repo = noclick.Repo.from_name("booking")
repo.commit({"app/routes/book.tsx": "export default function Book() { return null; }\n"},
message="Simpler booking form")
latest = app.deployments(limit=1)[0]
print(latest.started_by, latest.status) # push queuedA deployment a push started says so in started_by; one deploy() started says deploy. Each push deploys its commit once, however often it's reported, and deploy() of a commit a push is already deploying gives that deployment's operation rather than building it twice. A push NoClick can't deploy, because the app's budget is used up or your account already has 4 builds going, is a failed deployment whose error says why, with a deployment.failed event, so nothing a push asked for disappears quietly. A deleted branch deploys nothing.
Live editing
Live editing lets you change an app while someone watches it. Its site runs from a dev server, and each change you make shows in the pages they have open within a second, swapped in place where the code allows, the way Vite's hot reload does it: a game keeps running, and a form keeps what was typed. When the session ends, NoClick builds what you changed, checks it where production serves, and deploys it only if both pass. Everyone else sees production as it was until then.
Turn it on
Live editing works for your account's own apps (not your users' apps) built with Vite 5.1 or later (on Vite 5, apps without a worker: a session runs a worker on Cloudflare's Vite plugin, which needs Vite 6), React Router 7 or 8 apps on the Cloudflare Vite plugin (as React Router's Cloudflare template makes them) and Astro 5, 6 or 7 sites included, Next.js apps (App Router or Pages Router, on a Next.js release NoClick builds: 16.4.1 or later), or made of files whose package.json asks for no Vite of its own, or that have none (a site with a worker, say: NoClick runs those on Vite itself, the worker's dependencies installed; a build step of their own runs only when the session ends, which builds and checks what ships, so a session shows their source), whose previews get their own data (preview_resources="branch", what new apps start with). React Router apps on the older template (cloudflareDevProxy) and Remix apps (move them to React Router 7 on its Cloudflare template), apps made with a tool that runs a dev server of its own rather than Vite (Create React App, Angular, Vue CLI, Nuxt, Gatsby and the like: their deploys build them as they are), sites whose pages run scripts only their build makes, apps that run in a container, and apps whose framework setting isn't what their code builds as (a session runs the code while the build follows the setting: set it to what the code is, or to null), can't be edited live yet. Neither can a site of files with no build whose pages load what only Vite makes runnable: TypeScript or JSX, CSS or JSON imported from a module, an import naming no file (./util for ./util.js) or import.meta.env. Production serves such a site's files as they are, so those leave its page blank there; write them as modules a browser runs as they are, or make it a Vite app.
A Next.js app runs on its own next dev: a client component's edit swaps with the page's state (Fast Refresh), and a server component's, or a module it imports, refreshes the page's server components in place, keeping its state. A route handler's or server action's code applies from the next request. A page that was away while edits were made reloads once when it's back, and so does one where Fast Refresh can't apply the update (a client module exporting more than components). While you edit, it's Next.js's dev server answering, so pages render fresh on every request (no ISR or static pages) and images use Next.js's own optimizer; the session's end builds the commit with OpenNext exactly as a deploy does, and checks that build before it goes live.
Such an app has its live_editing switch on from its first production release, and NoClick's coding agent edits it live. Turn it on yourself for an app released before, or off to keep it from being edited live:
app = noclick.Project.from_name("larkspur")
app.update(live_editing=True)
status = app.live.status()
print(status.enabled, status.supported) # True TrueAn app it can't run on is refused with noclick.Conflict, saying what to change, and status.unsupported_reason says the same before you try. Turning the switch off ends the open session and deploys what it changed.
Start a session
import time
app = noclick.Project.from_name("larkspur")
session = app.live.start(wait=True)
print(session.enter_url) # send it now: the page waits while the session starts
while session.state == "warming":
time.sleep(5)
session = app.live.status().session or session
print(session.state) # livestart returns the app's open session, or starts one. It answers while the session starts (state is warming); wait=True waits for it to be live, up to 60 seconds, and answers it as it stands then. A start can take a few minutes, so a session can still come back warming: read it again with status() until it's live, as above. A session checks out the app's code from its noclick-live branch, made from the production branch the first time and kept between sessions.
The session's code runs as a preview: it writes to its own copies of the app's databases, buckets, dicts and queues, never production's, and session.data lists them. A database's copy starts with production's data (a SQLite database's up to 200,000 rows or 16 MiB; past that, its schema alone). refresh_data=True makes the copies again from production's. It reads the app's preview secrets, while its end deploys with production's: when the two don't name the same secrets, the agent editing it hears which as the session starts, once until that changes.
What a viewer sees
enter_url opens the app in live mode. Send it to the person you're editing for: whoever opens it sees the app at its own address, served from the session, on that device, and each change you make shows there as you make it. The link works any number of times for 2 hours, and live mode lasts 12 hours on each device that opened it, renewed while they keep coming back. A viewer can change nothing, and everyone else, search engines included, sees production.
Each page a viewer sees from the session carries a small bar, in the corner the app keeps for NoClick's badge, saying "Live editing: you're seeing unpublished changes". Its "See the published site" shows them production for five minutes, or until another session starts. What a viewer sends the app, an upload of any size included, reaches the session's code.
While the session starts, the page says "Starting your live preview…" and refreshes itself until it's live, and a page the dev server is still building (Next.js builds each page the first time it's opened, which takes a minute or two on a session's machine) says "Compiling your live preview…" and refreshes itself until it's ready. Outside a session, live mode shows production, and when a session's end deploys, the open pages reload into the new release. enter_link makes another link:
app = noclick.Project.from_name("larkspur")
link = app.live.enter_link()
print(link.url, link.expires_at)Edit in a session
exec runs a bash command in the session's container, in the site's working tree (/site), and starts a session when none is open. Each file a command writes is committed to the noclick-live branch by itself: you never commit, push or deploy. The result says what Vite did in the open pages with each batch of files the command changed:
app = noclick.Project.from_name("larkspur")
result = app.live.exec("sed -i 's/Score/Points/' src/render.js")
print(result.ok, result.stdout)
for edit in result.vite:
print(edit.outcome, edit.files) # hot ['src/render.js']outcome | What happened in the open pages |
|---|---|
hot | It swapped in place. applied counts the pages that took it, and its errors say what threw as it ran. |
reload | The page reloaded and lost its state. reload says why (reason) and lists the imports from the changed file up to the page (chain). |
error | It doesn't compile, and the page shows Vite's error overlay. error has its message, file and loc. |
none | Nothing imports the file. |
A session runs the app's own dev server alone, serving from the app's folder (the repo's root, or the root its noclick.json names, on the Node.js it names), while a command's working tree is the whole repo (/site): a server.proxy in its Vite config to a server of its own, a base path, and a dev script that runs a server around Vite (an Express server hosting it) don't work in a session, nor once deployed. Answer those requests from the app's worker instead. The agent editing the app is told once a session which of these its app has. Files git ignores (.env, .env.local) aren't committed, so they don't survive a restart of the session's container and are never deployed: put their values in the app's secrets or settings. The agent editing it is told which files a restart dropped. The app's dependencies are held in the session's memory, so an app whose node_modules doesn't fit can't be edited live, and its install says so.
A change to what the dev server reads as it starts (package.json, a lockfile or the package manager's settings, a Vite, framework or wrangler config) restarts it once the change is pushed, its dependencies installed again from the tree as a build installs them, and open pages reload. A session keeps and restores installed dependencies by everything an install reads (the lockfile, the package manager's settings such as .npmrc, and what package.json depends on and runs as it installs), so a change pushed to any of those outside a session is installed afresh when the next one starts, while an edit to another script restores what's installed. One that fails to install or start is told to the agent editing the app, with the dev server's last lines, and the session goes on as it was. A change that makes the app run another way (a site of files gaining a Vite config) runs that way from the next session. A change to noclick.json's root or node restarts the dev server where the app is now, but a move from the repo's root into a folder, or from Node 22 onto another Node.js, runs there from the next session; the session's end builds a commit that moved the app since the session started in a fresh build, which installs from the commit.
A command answers within its request, so it runs for at most 90 seconds (timeout_s, 90 by default), and one sent while the session is still starting, or deploying what was edited, doesn't run: it raises noclick.Conflict, whose state is warming or ending. background=True returns an operation at once instead, which waits for a starting session, then runs the command for up to 600 seconds. Use it for a command that takes longer than a request allows, like an install, and for a session's first command:
app = noclick.Project.from_name("larkspur")
installed = app.live.exec("npm install canvas-confetti", background=True, timeout_s=300).wait()
print(installed.ok, [edit.outcome for edit in installed.vite])An account runs at most 4 background commands at once. Cancelling one stops its wait for the session, not a command already sent, which runs until its timeout_s.
A change swaps in place when a module between it and the page accepts its own update (import.meta.hot.accept()). One that reaches the page through no such module reloads it, as does a change to index.html, vite.config.js or the dependencies. So keep code in small modules, keep state outside the code that changes, and have each module take back what it starts (import.meta.hot.dispose). session.readiness names what in the code keeps an edit from swapping in place.
edits reads the session's edits, oldest first, whoever made them. Pass last_seq back as after to read only the newer ones:
app = noclick.Project.from_name("larkspur")
edits = app.live.edits()
for edit in edits:
print(edit.seq, edit.outcome, edit.files)
newer = app.live.edits(after=edits.last_seq)Your NoClick agents edit live from their own turns: an agent with NoClick itself in its tools that starts a session is attached to it, and its shell runs in /site from its next command. That takes an agent on the sdk, claude_code or codex harness, with no network limit.
While a session is open, a production deploy is refused with noclick.Conflict, since the session's end deploys what it changed. A preview deploy works.
End a session
A session ends by itself about 11 minutes after the last page in live mode was closed or hidden and the last command ran, 15 minutes after its last edit or command even with pages open (a page left open isn't work; a take-over holds it, and so does an agent's turn working in its container), or after 12 hours in all. Its end deploys what changed, unless the last edit Vite saw failed (the work may be unfinished: it stops without deploying, and the agent editing it hears what's left), the open pages reload into it at once, and the next edit starts a session again, which a page shows from its next reload. end ends it now:
app = noclick.Project.from_name("larkspur")
ended = app.live.end().wait()
print(ended.outcome, ended.deployment_id) # deployed, and the release serving nowEnding is an operation. It commits what the session changed, with anything pushed to the production branch meanwhile merged in, builds it, and checks the build where production serves: its home page, judged as a deploy judges it (2xx, its scripts and stylesheets loading, never sent to another site), and the app's check paths. Only when both pass does the app's URL serve it and the production branch move to its commit. Its outcome is deployed, no_changes (nothing was changed), stopped (it ended without deploying) or aborted (a change came in as it ended, and the session is live again). Undoing the operation (undo()) puts back the release before, with the databases as they were, as undoing a promote does.
A build or check that fails leaves production serving what it did, and keeps the edits on noclick-live for the next session. wait() raises noclick.OperationFailed, saying why:
app = noclick.Project.from_name("larkspur")
try:
app.live.end().wait()
except noclick.OperationFailed as failed:
print(failed) # production is unchangedWhen the production branch changed during the session in a way that conflicts with its edits, the end fails saying so and the session stays open: resolve the conflict in /site (git status shows it), then end it again. end(deploy=False) stops a session without deploying, its edits kept on its branch.
An end builds with the session's own installed dependencies, so when they changed during the session and weren't installed again since (package.json, a lockfile or the package manager's settings, or something installed without being saved), the end installs them from its commit first, as a build installs them, then builds and deploys; its log says so. An install that fails ends it without deploying, saying why with the install's last lines (its error's reason is withheld), and stops the session, its edits kept: fix them and start a new session, which installs from the committed lockfile as a build does, refusing one that doesn't match package.json. So does a change to package.json's dependencies without its lockfile: commit package.json and the lockfile an install writes together. A site of files whose pages now load what only Vite runs (above) isn't deployed either: the end fails and the session stays open to change it back.
An end builds in the session's container, beside its dev server, exactly as a deploy of its commit builds: the app's own build.command, in the folder and on the Node.js its noclick.json names, the scripts run by the package manager of the folder it installs from. A commit whose noclick.json moved the app since the session started, or whose build.command installs the dependencies itself, builds on NoClick's build machines instead, which install from the commit. An app whose last two ends that built in the container ran out of memory builds its ends on NoClick's build machines from then on, as a deploy builds them, until what its dependencies install from changes (its lockfile, the package manager's settings or what package.json depends on): then one end tries the container again, and if it runs out of memory too, the ends after it go back to the build machines. Each end's log says where it builds and why.
Once production serves the release, its branch is moved to the release's commit; a push the branch refuses is asked for again for about a minute and a half, and if it still doesn't land, the agent editing it hears so: until the branch holds the edits, a deploy of it would go out without them.
What a session costs
A session runs on a container with half a vCPU, 4 GiB of memory and 8 GB of disk, billed by the minute at what it costs NoClick, with nothing added. It stops costing when the session ends:
| What | Price |
|---|---|
| The container's memory and disk, while it runs | $0.0000025 a GiB-second and $0.00000007 a GB-second: about $0.038 an hour |
| Its CPU, only what it uses | $0.000020 a vCPU-second |
| The object that runs the session, while it's awake | $0.0000125 a GB-second at 128 MB (about $0.0056 an hour), and $0.15 a million requests |
| A request a page in live mode makes | $1.30 a million |
| Saving and restoring its files | $4.50 a million writes, $0.36 a million reads |
| What sessions keep for the next one (installed dependencies, the source) | $0.015 a GB-month, charged by the day |
A session using a tenth of its CPU comes to about 4.7 cents an hour. It's attributed to the app, so it counts toward the app's monthly budget and its user's cap. A start is refused once the budget or your balance is used up, and an open session ends without deploying, its edits kept on its branch, when your account runs out of funds or reaches its spending cap, or the app is paused or deleted. An account has at most 3 sessions open at once, and 24 session-hours a day.
Give the app its data
A binding gives the running app a resource under a name. Bind a database, a bucket, a dict, a queue, a secret or a connection:
app = noclick.Project.from_name("booking")
app.bind("DB", noclick.Database.from_name("booking-db", create_if_missing=True))
app.bind("FILES", noclick.Bucket.from_name("uploads", create_if_missing=True))
app.bind("SEEN", noclick.Dict.from_name("processed-orders", create_if_missing=True))
app.bind("JOBS", noclick.Queue.from_name("webhook-buffer", create_if_missing=True))
app.bind("SHIPPING", noclick.Secret.from_name("shipping"))
app.bind("CRM", noclick.Connection.from_name("hubspot"))
app.deploy()The deployed code finds each one in its environment under its name: DB to query, FILES to read and write files, SEEN and JOBS to use the dict and the queue, and CRM to call the connected account, with tokens NoClick keeps fresh and never hands to the code. A secret is the exception: each of its keys arrives as a variable of its own, under the key's own name (a secret holding SHIPPING_API_KEY is read as SHIPPING_API_KEY, whatever it's bound as), and each binding's variables names what the code reads. The app's environment holds a name once: see when names clash. Binding a name again points it at something else, and unbind takes it away; the resource itself is never deleted. Every resource lists the apps that bind it in used_by, a connection and an agent included. An agent binds the same way.
for binding in app.bindings():
print(binding.name, binding.kind, binding.resource_name) # DB database booking-db
app.unbind("CRM")Bindings, secrets and removals take effect at the next deployment.
A container's DATABASE_URL
In a container, each Postgres database the app binds also arrives as a connection URL, for an ORM or a driver that speaks Postgres's own protocol: DATABASE_URL for the one it binds, or, when it binds several (or sets a DATABASE_URL of its own), <binding>_URL for each (DB_URL, ANALYTICS_URL). Each release logs in as a login of its own, which reads and writes as the app's code does and works for as long as the release can serve:
| What happens | Its login |
|---|---|
| A rollback, a promote, or restoring the app from the trash | the release is released again with a new one, and the one before ends |
| The release retires (out of the rollback window, a preview replaced or past its days), the app goes to the trash or is deleted, the database goes to the trash | it ends |
| The database is paused (its account out of funds) | it's kept, and works again once the database does |
| The database is restored to an earlier moment | it's made again, so the release keeps working |
A preview's URL reaches what its code reaches: its branch's own copy, made as it deploys (see A preview's own data), or production's database for an app with preview_resources="shared". A SQLite database has no connection URL: the code reaches it through the SDK. The deploy's (and promote's) databases says where each binding's URL went, and how the code reaches a SQLite one; the deployment's variables names everything each of its releases was given, never a value. Don't copy one of these URLs into a setting or secret: it's refused there, and a release finding one of the app's values holding a NoClick connection URL fails, saying which to delete.
The frameworks read it as it is. Django, with dj-database-url in requirements.txt, and a Node server with node-postgres:
# settings.py
import dj_database_url
DATABASES = {"default": dj_database_url.config(conn_max_age=600, ssl_require=True)}Rails reads DATABASE_URL for production on its own; to say so in config/database.yml:
production:
adapter: postgresql
url: <%= ENV["DATABASE_URL"] %>Prisma names it in schema.prisma, and prisma migrate deploy (in the container's start command, before the server) migrates with it:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}Tables made this way belong to the database as any other, so the SDK, migrate and agents' tools read and change them too.
For state many requests share and must agree on (a chat room, a document edited together, one user's live feed), an app can also run Durable Objects of its own: objects its code addresses by name, each with its own storage, alarms and WebSockets, kept from one release to the next.
Reach them from the app's code
Inside the running app, noclick.Project.current() is the app itself. NoClick puts the deployment's own credential in its environment (NOCLICK_DEPLOYMENT_TOKEN), so the app's code holds no key and the client signs in as the app. Each binding is then one call away by its name:
app = noclick.Project.current()
db = app.database("DB")
rows = db.query("select id, starts_at from bookings where day = ?", ["2026-10-02"])
app.bucket("FILES").put("invoices/1042.pdf", b"%PDF-...")
app.queue("JOBS").put({"booking": 1042, "send": "reminder"})
crm = app.connection("CRM")
app.email.send(to="ana@example.com", subject="Your booking", text="See you Friday at 3pm.")database, bucket, dict, queue, connection and agent each return the resource bound under that name: an unbound name raises noclick.NotFound, and one bound to another kind raises noclick.InvalidRequest naming it. Outside a deployment, current() raises noclick.Unauthenticated; pass client= to act with a key of your own instead.
The rest of the SDK signs in the same way, with nothing to configure: noclick.AI, noclick.Agent, noclick.Connection, noclick.Channel and every other call without client= act as the app too. An app that sets NOCLICK_API_KEY itself has those calls use that key instead, while current() still acts as the app.
What the app's code can do
The deployment's credential is a key of the app's user (your account's, for an account app), so the app's code uses the whole SDK as that user: it makes agents and talks to them, makes databases and queries them, buckets, dicts, queues, inboxes, sandboxes, browsers and repos, calls noclick.AI, and reads and writes its user's other resources by id. Who may make the app do what is its own code's to decide, as on any server you write: NoClick doesn't hold its calls for anyone to approve, except a purchase in a person's name (below). The credential lives only in the release's server-side environment (a build never sees it, so no framework can put it in a page), and every deployment gets a new one.
helper = noclick.Agent.from_name("helper", instructions="Answer in French.", tools=["search"],
create_if_missing=True)
reply = helper.message("Bonjour !", conversation="visitor-91c2")| The app's code | Can | Can't |
|---|---|---|
| What its code made | everything: use it, change it, delete it | |
| What's bound to the app | write its data, clearing or rewinding it included (dict.clear(), a queue's clear, a database's restore) | rename it, reconfigure it or delete it: that stays with whoever made it |
| Its user's other resources | read them, write their data (rows, files, keys, messages), talk to their agents, run their connections | clear their data, change what they are, or delete them |
| Purchases | buy a phone number or a domain, and renew its own, within what's left of its budget (below) | buy in a preview; accept terms for a person; file documents, move numbers in from a carrier or register a business to text; turn on a domain's auto-renew; use quotes |
| What bills after its request | place and answer calls and send texts on a number its code bought, run and build automations, host MCP servers, open channels and workspaces, run machines, issue cards: each counts toward the app's budget and waits on it before it runs (below) | reach the account's automations and workspaces it didn't make (they're the account's, not its user's), or publish an automation's app |
| Its user's activity | read that user's events, webhooks and usage, the files its own code uploaded, and its own requests and operations | change any of it; read another user's, another app's requests, operations and files, or the account's caps, tool calls, approvals, trash and policy |
| Another app | reach it, its deployments, or anything its code made, by id, by name or named in a call's arguments; what its code made never shows in a list | |
| Another user | reach anything of theirs, or act for them: NoClick-User is refused, a list's user_id names only the app's own user, and an account app doesn't manage the account's users | |
| Its own app | read it (logs, usage, deployments), set its settings, schedules and subscriptions, send its email | change what it is, deploy it, or delete it |
| People | tell you, the owner, something (Human.owner().notify), from production, within its budget and your account's daily email cap | ask anyone, ask for an approval, reach anyone but you, or notify from a preview |
| Credentials and limits | mint, rotate or revoke keys, grants or sessions; mint a bucket's S3 credentials (it uploads in parts instead); set or raise any cap or budget, its own included; change policy; answer approvals; read raw tokens or set secrets' values (a secret bound to the app still reaches its environment) |
An agent the app's code makes can't be given the noclick tool (your account's API) or the agents tools, nor be woken by your account's events, and the app's code never talks to an agent that holds the noclick tool, nor puts one behind an inbox or a number it sets up: the site's visitors, or whoever mails or calls, would then be driving your account. Another app's connection or volume, or anything its code made that from_name would find, is out of reach by name as it is by id. The one person such an agent may reach is you, the owner, to notify and ask ({"human": {"owner": true}, "tools": ["notify", "ask"]}, an account app's agent only), at most 10 times a day; past that its tool answers that it reached the limit. A refused call raises noclick.PermissionDenied, or noclick.NotFound for what another app made.
Telling you something, such as each new signup, is one call from the app's code, as from your own: it reaches you by email, or on the app you text NoClick on. Asking you, or anyone, takes an agent's human tool.
noclick.Human.owner().notify("Ana (ana@example.com) joined the waitlist.")What it buys
A purchase from the app's code charges now what it costs now (a number's first month and any setup, a domain's term), and that must fit what's left of the app's budget this month, or the call raises noclick.SpendCapExceeded naming what's left in remaining_usd. What it buys is the app's own: its code manages and releases it, and each renewal counts toward the app's budget in the month it renews. A number whose renewal the budget can't cover keeps working for 48 hours while NoClick emails you that the app's budget can't cover it, then is released unless you raise the budget; a domain's renewal waits, is tried again each day until it expires, and you're told why.
A purchase that registers or files something in a person's name waits for that person: any domain (it's registered to someone, under the registrar's agreement), and a number whose country asks who holds it (one that asks for documents takes them from your own code: the app's code doesn't file them). The call raises noclick.ApprovalRequired, NoClick sends your account's owner a link to approve it (accepting the terms there), and once they do it makes the call as the app, within its budget then. A plain US number needs nobody.
pick = noclick.PhoneNumber.available(area_code="415")[0]
number = noclick.PhoneNumber.buy(pick, max_monthly_usd=2) # a US local number: charged to the app's budgetWhat bills after its request
Some work goes on spending after the call that started it. From the app's code, each is the app's, counted toward its budget and checked against it before it runs:
- Calls and texts on a number its code bought: each call's minutes and the agent's turns on it, and each text. A call isn't placed or let in, and a text isn't sent, once the budget is used up.
- Automations its code made: every run, whatever started it (a schedule, a webhook, a run from code), and every build its code starts. At the budget their triggers' deliveries are refused before anything runs.
- A hosted MCP server its code made: each call its clients make.
- A channel its code made: each turn its members take.
- A machine its code bought: each day, while the budget covers it; past it, the machine runs on for 48 hours, then stops until the budget does.
- A card its code made: each charge, which must fit what's left of the budget or is declined (
over_budget).
Once the budget is used up, the sandboxes and browsers the app's code started are stopped too, and the email you get says so.
Find or make resources by name
The app's code can also name what it uses. from_name inside a deployment looks in the app's own namespace (its user's resources, or the account's for an account app) for the environment the code runs in:
db = noclick.Database.from_name("orders", create_if_missing=True)
db.migrate("migrations/")
seen = noclick.Dict.from_name("seen", create_if_missing=True)A name bound to the app by hand wins. Otherwise production's code gets the resource of that name, made on first use with create_if_missing (within the app's budget), and it becomes one of the app's bindings, so it shows in app.bindings() and in the resource's used_by. A preview's code gets the branch's own copy of production's resource, or, when production has none yet, one only the branch has. What the app's code makes this way is the app's own, so its code may delete it; what it only finds, it uses and never deletes or renames: that stays yours.
Policy doesn't judge these calls. A binding is the app's own resource, given to it by whoever deployed it, and the app's code is yours; an agent the app messages still runs under its policy.
Everything the app does this way is billed to your account and attributed to the app and its user, and some of it stops when the money does: see When it runs out.
AI and agents in the app
app.ai is noclick.AI acting as the app: the same chat, embeddings, images and transcription, billed to your account, attributed to the app and its user, and held to the app's budget.
app = noclick.Project.current()
reply = app.ai.chat("Summarize in one line: the class was great but the room was cold.")
print(reply.text)Code written for OpenAI's client works as the app too: give it app.ai.base_url and app.ai.headers(), which carry the deployment's credential rather than a key.
from openai import OpenAI
app = noclick.Project.current()
gpt = OpenAI(base_url=app.ai.base_url, api_key="-", default_headers=app.ai.headers())Only the app acts as the app. On a project you reached with your own key, app.ai raises noclick.InvalidRequest; use noclick.AI there, inside as_user for the app's user.
An agent is bound like any resource: one of the app's own user, or one of your account's, which then acts for the app's user as message(user=...) would. app.agent(name) gives it to the app's code (an agent its code makes is talked to the same way):
app = noclick.Project.from_name("booking")
app.bind("SUPPORT", noclick.Agent.from_name("support"))
app.deploy()app = noclick.Project.current()
support = app.agent("SUPPORT")
reply = support.message("Can I move my booking to Saturday?", conversation="visitor-91c2")
print(reply.text)From the app, an agent its code didn't make is there to talk to, and nothing more:
- The app's own conversations.
message,sendandaskstart turns in the app's threads, andhistoryandconversationsread only those. A key the app passes, such as each visitor's id, always names one of the app's threads:visitor-91c2from an app whose id is3f9a…isapp:3f9a…:visitor-91c2to your own code, which reads it, and to the app's own code, which may pass either back. No other app, and no thread of yours, is ever reached that way. The key is the app's id, not its name: a deleted app's name is free for a new one, which mustn't read its threads. - Not its definition.
update,delete, its triggers, memory, share page, wake-ups and children raisenoclick.PermissionDeniedfrom the app; change the agent from your own code. An agent the app's code made is the app's own: its code changes and deletes it too. - Its own rules. The agent's policy judges every tool call it makes, as always, and it acts in its own connections, never the app's bindings.
- Billed like any turn. Its turns count toward the agent's budget, the app's budget and the user's cap, attributed to the app. So does every turn of an agent the app's code made, whatever started it (a trigger, a wake-up).
- A preview's, in a simulated world. A preview's code may
messagean agent: the turn uses the agent's real model, prompt and thread, charged to the app, but every tool it calls answers from the same simulated world as a test run, it's offered nothing that reaches a person or money, and it writes nothing real. Its threads are its own (app-preview:3f9a…:visitor-91c2), apart from production's.ask, and every other turn, wait for production.
app.ai.chat(..., model="agent:support") reaches an agent the same way.
A chat assistant on a site is this, with one thread per visitor. The page keeps a visitor id (in localStorage) and posts each message with it; the app's server answers:
import { Project } from "noclick";
export default {
async fetch(request: Request, env: { ASSETS: { fetch(r: Request): Promise<Response> } }) {
const url = new URL(request.url);
if (request.method !== "POST" || url.pathname !== "/api/chat") return env.ASSETS.fetch(request);
const { visitorId, text } = (await request.json()) as { visitorId: string; text: string };
const assistant = await Project.current().agent("ASSISTANT");
const reply = await assistant.message(text, { conversation: visitorId });
return Response.json({ text: reply.text });
},
};Keep secrets
A secret is a value the app reads from its environment by name, such as an API key. Values are write-only: nothing, including the console, reads one back.
app = noclick.Project.from_name("booking")
app.secrets.set("MAPS_API_KEY", "...")
for name, updated_at in app.secrets.list().items():
print(name, updated_at)
app.secrets.delete("OLD_WEBHOOK_SECRET")A secret applies to every deployment unless you set it for one environment: production (deploys of the production branch, and what's promoted) or preview (every other branch). Give previews a test key and production a live one under the same name:
app = noclick.Project.from_name("booking")
app.secrets.set("STRIPE_KEY", "sk_live_...", environment="production")
app.secrets.set("STRIPE_KEY", "sk_test_...", environment="preview")A private registry's token is a secret too: save it under the name the package manager's settings read it by (// in an .npmrc or .yarnrc.yml reads NPM_TOKEN; in a container, a pip.conf or .pypirc too), set for the environment you deploy. An edge build's install alone gets it, in its environment: never the build after it, what the build makes or its log, which prints [redacted] in its place; the app's other secrets never reach a build. A wrangler build.command that installs the dependencies itself can't have it (take the install out: NoClick installs first). A container's Dockerfile gets it as a BuildKit secret, for the RUN line that mounts it: never a build argument, so no layer of the image holds it, and its build log prints [redacted] wherever that line printed it.
# syntax=docker/dockerfile:1
FROM node:22
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
COPY . .
CMD ["node", "server.js"]There it has to be a secret: a plain setting of that name fails the deploy, since a setting reaches a Dockerfile's build as a build argument, which stays in the image's history. A Dockerfile that never mounts it fails the deploy before it builds, saying the line to add, and so does one mounting it with env= and no # syntax=docker/dockerfile:1 line (mounting a secret as a variable is Dockerfile 1.10's, newer than the builder's own syntax). A container with no Dockerfile, which buildpacks build, can't have one: add a Dockerfile that mounts it. One the app has neither as a secret nor as a setting fails the deploy before it builds, naming it.
A name is letters, digits and _, starting with a letter; a value is at most 5 KB, and an app's environment holds 128 values in all, NoClick's own and each bound secret's keys included. Keep anything larger in a bucket the app reads. A name one of the app's bindings already sets, a bound secret's key included, raises noclick.Conflict. A NoClick database's connection URL raises noclick.InvalidRequest as a secret or a setting: its login ends when it expires, a day at most after it was made, so bind the database instead (in a container, each release then gets a DATABASE_URL of its own). Export lists secret names only.
Plain settings
What isn't a secret, such as a feature flag or the app's public URL, goes in app.settings. Settings reach the app's environment the same way, but read back and show in the console:
app = noclick.Project.from_name("booking")
app.settings.set("PUBLIC_BASE_URL", "https://book.acme.com")
print(app.settings.list()) # {'PUBLIC_BASE_URL': 'https://book.acme.com'}
app.settings.delete("PUBLIC_BASE_URL")A setting's name follows a secret's rules and can't be one of the app's secret names, or a name one of its bindings sets; a value is at most 4 KB. Like secrets, settings apply from the next deployment.
Settings also reach the app's build, and secrets never do (but a private registry's token, to its install alone, or to a container's Dockerfile line that mounts it). So a value the build writes into the page every visitor downloads, public by nature, is a setting: an import.meta.env.VITE_*, process.env.NEXT_PUBLIC_* or process.env.EXPO_PUBLIC_* the code reads that's neither a setting nor in a committed .env file, or is only a secret, fails the deploy before it builds, naming it (one the code reads only when it's set takes an empty setting); so does any other a noclick.json's build_env names. A setting can't name what the build's own tools read (PATH, HOME, npm_config_*, COREPACK_*, BUN_*: put npm's in an .npmrc), and one that looks like a secret (STRIPE_SECRET_KEY, a value like sk_live_...) is named in the deploy's build_warnings: make it a secret.
Run on a schedule
schedule has NoClick POST one of the app's paths on a Cron, in the timezone you give it:
app = noclick.Project.from_name("booking")
reminders = app.schedule(noclick.Cron("0 9 * * 1-5", tz="America/New_York"), path="/jobs/reminders")
print(reminders.next_run)NoClick POSTs the path on the app's own hostname, so a domain that isn't live yet never gets in the way, and waits up to 30 seconds for the answer. Each request carries a NoClick-Signature header, so the app can refuse anyone else (see Check a scheduled request), and a 2xx answer counts as a success; a redirect counts as a failure. Each tick runs once, however often the scheduler retries delivering it. A schedule is keyed by its name, the path unless you pass one, so calling schedule again with the same one updates it instead of adding another. That makes it safe to run on every deploy. tz="user" reads the expression in the app's user's timezone, following them when they move; an app of your account's own has no user, so it names a zone.
last_status and last_error say how the latest run went. When 5 runs in a row fail the same way over at least 30 minutes, a schedule pauses itself: its status is paused, paused_reason says what kept failing, and the schedule.paused event carries the schedule. Calling schedule again while it's paused changes what it will do and leaves it paused. Fix the app, then resume it:
app = noclick.Project.from_name("booking")
for schedule in app.schedules():
if schedule.status == "paused":
print(schedule.path, schedule.paused_reason)
schedule.resume()run_now() calls the path once, outside the schedule, and waits for the answer; a run you start by hand never counts toward pausing it. pause() and delete() do what they say.
Check a scheduled request
The request's body is JSON naming the run: {"object": "schedule_run", "id", "schedule_id", "schedule", "path", "scheduled_at"}, where id is the same for every delivery of one tick, so a handler that must act once can key on it. verify_request checks the signature in the app's own code, with the signing secret NoClick puts in the deployment's environment (NOCLICK_SIGNING_SECRET). Pass the raw body, exactly as it arrived, and the headers. In a Flask app on the container runtime:
from flask import Flask, request
server = Flask(__name__)
@server.post("/jobs/reminders")
def reminders():
app = noclick.Project.current()
try:
app.verify_request(request.get_data(), request.headers)
except noclick.WebhookSignatureError:
return "", 401
return "", 204An edge app does the same in its route with the TypeScript client: await Project.current().verifyRequest(await request.text(), request.headers).
The header is t=<unix seconds>,v1=<hex>, the hex being HMAC-SHA256 of "<t>.<body>", as on webhook deliveries; a timestamp more than five minutes from now is refused, so a captured request can't be replayed.
Hear app events
subscribe has NoClick POST a connection's app events to one of the app's paths as they happen: a WhatsApp message, a Slack post, a new HubSpot contact. The app runs its own pipeline with them, with no agent turn and no polling in between. The source is an OnEvent, as an agent's trigger takes one, on a connection of the app's own scope:
whatsapp = noclick.Connection.from_name("whatsapp", integration="whatsapp")
app = noclick.Project.current()
app.subscribe(noclick.OnEvent(whatsapp, "receive_message"), path="/hooks/whatsapp")Each request is signed as a scheduled one is, so verify_request checks it the same way (see Check a scheduled request). Its body is JSON:
{"object": "app_event", "id": "6f1c…", "subscription_id": "2b9e…", "connection": "whatsapp",
"integration": "whatsapp", "event": "receive_message", "text": "…the message, in words…",
"thread": "12025550101@c.us", "data": {"event": "message", "payload": {"from": "12025550101@c.us", "body": "…"}},
"test": false, "created_at": "2026-11-04T09:00:00+00:00"}data is the event as the integration sent it, text the same in the words an agent reads it in, and thread the conversation it belongs to (a WhatsApp chat, a Slack thread), which a send operation takes back. connection.events() lists each event's shape (what its data holds, field by field, as it has reached your account) and a sample. Answer 2xx within 10 seconds, doing slow work after the answer (ctx.waitUntil on the edge). Anything else, a redirect included, is sent again, the same body, after a minute, five, thirty, then hours apart for three days; key on id to take each event once. While the app is paused its events wait and go once it serves again; while it's in the trash they're skipped.
subscribe again with the same event and path adds another, so call it once, or check subscriptions() first. Up to 20 an app. One whose connection isn't connected yet is error until the account connects, then it hears the next event. deliveries() lists what was sent, newest first, with each body, its attempts and the app's last answer, and unsubscribe() stops it:
app = noclick.Project.current()
for subscription in app.subscriptions():
for delivery in subscription.deliveries(status="failed"):
print(subscription.path, delivery.response_status, delivery.error)test() POSTs a sample of the event now, test: true in its body and placeholders for its values (until one such event has reached your account, an empty data and a text saying so), and waits for the answer, so the route can be tried before anyone has written:
delivery = app.subscriptions()[0].test()
print(delivery.status, delivery.response_status)A test is listed among its deliveries and never sent again.
Add a domain
An app serves at https://<name>.noclick.site from the start, or at <name>-<6 characters> when another app holds the name or it's one NoClick keeps for itself (www, api, mail, bounce and a few like them); app.url says which. Add a domain you bought through NoClick, or one you own elsewhere:
app = noclick.Project.from_name("booking")
domain = app.add_domain("acmebooking.com")
print(domain.status) # active for a bought domain; pending_dns until the records are setA bought domain serves the app at its name and at www, and NoClick writes their records. A name nobody holds yet is connected for the app, in the app's scope, and records lists what to add at its DNS host (see Connect a domain). Each name is live once its certificate is issued, and from then on app.url is the first of them. app.domains() lists the domains, and app.domain_names names the live hostnames without loading each one.
remove_domain stops serving the app at a name; the domain stays yours, and one connected for the app stays connected until you delete it. A domain can't be disconnected while an app is served there:
app = noclick.Project.from_name("booking")
app.remove_domain("acmebooking.com")A subdomain of yours for each user's app
A subdomain of a domain your account holds can serve any project, a user's included, so each user's app gets an address of yours:
store = noclick.Project.from_name("store", user="user_42")
domain = store.add_domain("ana.acmebooking.com")Only a key acting for the whole account (not a user's session, nor a key pinned to a user) may hand one out, and a user's app takes a name under your domain, never the domain itself. Under a domain you bought through NoClick, the record is written for you and the subdomain is active as soon as its certificate is issued, usually within a few minutes. Under a connected one, when the domain was connected with Domain.connect(name, wildcard=True), the subdomain needs no record of its own and is live once its certificate is issued, usually within minutes; otherwise its records list the one to add. The same goes for an app's email: app.email.enable(domain="mail.ana.acmebooking.com").
Logs and usage
logs reads what the app printed while serving, oldest first: the last limit lines, or with since the ones after a moment, so you can read on from the last line you saw. level="error" keeps only errors, and environment="production" (or "preview") one environment's lines. Each line names its environment and the request it was written in (request_id); the host's own line for a request (its method and URL) carries the status it answered, and a read never cuts a request's lines apart, so an exception comes with the request it broke. A line takes up to a minute to show after a request writes it, as the read's delay_s says: a read right after a request may not have it yet. A deployment's logs(kind="runtime") reads one release's lines the same way.
from datetime import datetime, timedelta, timezone
app = noclick.Project.from_name("booking")
an_hour_ago = datetime.now(timezone.utc) - timedelta(hours=1)
for line in app.logs(since=an_hour_ago, level="error"):
print(line.at, line.message)
used = app.usage()
print(used.requests, used.cpu_ms, used.usd) # this month, from period_start
print(used.budget_usd, used.limited_by) # 25.0 None
print(used.by_type) # {'apps': 1.84, 'ai': 6.2, 'model_tokens': 3.1}usd is everything the app spent this month: hosting and builds, its calls to what it's bound to, its email, app.ai and its agents' turns, split in by_type by the types of Usage.series. limited_by says what refuses its paid calls now: project (its budget), user (its user's cap), account (your balance), or None while they go through.
A deployment's own logs(kind="build") holds its build output, logs(kind="runtime") what that one deployment printed, and requests() how its requests went (Check it works). A paid call NoClick refuses is in the log too, as an error line naming the call and what ran out, at most once a minute for each kind of call, so a refusal the code caught still shows.
How it's doing
analytics reads the app's traffic: its requests each day of the last week (period="24h" hour by hour, "30d" the last 30 days), how many failed, the same length of time before to compare with, by status and by who made them, how long answers took to begin, and its busiest paths:
app = noclick.Project.from_name("booking")
week = app.analytics(tz="Europe/Paris")
print(week.requests, week.previous_requests) # 1204 980
print(week.error_rate, week.p50_ms, week.p95_ms) # 0.0025 42.0 310.5
print(week.by_source, week.noclick_requests) # {'browser': 1100, 'automated': 104} 12
for day in week.series:
print(day.at.date(), day.requests, day.errors)
for page in week.top_paths:
print(page.path, page.requests, page.browser_requests, page.p95_ms)It counts every request the app's sites answered, from NoClick's record of each one: pages, static files and API calls, from people and bots alike. They're requests, not visitors: a page that loads twenty files is twenty-one requests. by_source says who made them, as each request's user agent says: browser (a person's browser, or a program that says it's one) and automated (curl, an HTTP library, a headless browser, a crawler), and unknown for requests recorded before NoClick told them apart; each busy path says how many of its requests a browser made (browser_requests). NoClick's own checks of your app (each deploy's, and the tests its coding agent marks as its own) are in no figure but noclick_requests. A failed request is an answer of 500 or more, or none at all. Hours and days start in tz (an IANA time zone, UTC when omitted), and the last one is still running. Only the production site is counted unless you pass environment="preview" (its previews) or "all". sampled is True when a very busy app's record is a sample, each request in it counted for the ones it stands for. The app's page under Resources shows the same.
Every app's requests at once come from one read, however many apps there are: each production site's over the same window analytics reads, how many failed and how many a browser made, NoClick's own checks apart, newest app first, one nobody reached at 0. The Websites list under Resources shows each app's week this way.
week = noclick.Project.analytics_summary(tz="Europe/Paris") # period="7d" by default
for line in week.apps:
print(line.project_id, line.requests, line.browser_requests, line.errors)
print(week.of(app).requests)Email, payments and sign-in
An app can send transactional email, take payments into an account its owner claims, and sign its own users in, through app.email, app.payments and app.sign_in. See Email, payments and sign-in.
Apps NoClick publishes
Publishing an automation's interface in NoClick makes an app too, listed with yours: published is True, repo_id is None, and workflow names the automation it was published from (id, name) and the interface step it serves, for a key that reads workflows (None for any other). Each publish is a deployment of it (no commit, no build), so its deployments, logs, usage and domains read like any app's, and a domain you add serves it. It has no repo of its own, so deploy, delete and every setting but budget_usd_per_month raise noclick.Conflict: it's republished or renamed from its automation, and taken down with unpublish(), which moves it to the trash and returns its TrashItem. It stops answering at once and its page's key stops working, but for 30 days no other app takes its address: restore(), or publishing its automation's interface again, serves it there with the same key. Purged, or after 30 days, it's deleted for good. An automation with two interfaces published renames one by its step: workflow.build(publish={"action": "rename", "step": app.workflow["step"], "subdomain": "morrow"}). Taking it down through a build of its automation (workflow.unpublish(), or publish={"action": "unpublish", "step": ...}) is the same act, so through MCP both ways are judged alike: since it can be undone, a change that needs deploy (as publishing does), which nobody is asked about unless your policy or the connection asks before changes. Purging it from the trash is what waits for your approval.
for app in noclick.Project.list():
if app.published:
print(app.url, "from", app.workflow["name"] if app.workflow else "a page published before apps")
item = noclick.Project.from_name("bakery").unpublish() # offline, in the trash
item.restore() # back at its address, with its keyExport and delete
export packages everything the app is, to run it somewhere else: its code as a git bundle, apps/<name>.json with its settings, its bindings and the names of its secrets (set their values again wherever it runs next), and each database, bucket, dict and queue it binds, each in its own export format. To put the code on GitHub, copy its repo there. It's an operation that gives an export bundle:
app = noclick.Project.from_name("booking")
bundle = app.export().wait()
for item in bundle.contents:
print(item.kind, item.name, item.detail)delete takes the app offline within seconds and moves it to the trash, where it stays restorable for 30 days: its deployments, settings, secrets, bindings and schedules are kept, its domains are detached (a bought one stays yours), its container releases' database logins end (a restore releases what it serves again with new ones), and its name is free meanwhile. The repo and every database and bucket it bound are kept; delete_data=True moves the repo to the trash too, with each database and bucket no other app binds.
item = noclick.Project.from_name("status-page", user="acme").delete()
item.restore() # served again where it was, from the same release: no buildA restore serves the release that was live, its previews and its domains again, within about 30 seconds, and its schedules fire again. It's refused with noclick.Conflict while a new app has its name or its address, while one of its domains serves something else, or while its repo is in the trash (restore the repo first); a domain you've disconnected since doesn't come back, and the restore's domains_not_restored names it. Purging it deletes its releases for good, and purging its repo purges it too.
NoClick's badge
On the Free plan, each page an app serves in production carries a small "Built with NoClick" link in its bottom-right corner (on a phone, at the end of a page that scrolls, so it never sits over the page), at every address it serves, your own domains included. That's your account's own apps and your users' apps alike, since your account's plan decides it. A paid plan drops it, and an app's badge says whether its pages carry it now. NoClick adds it as each page is served, just before the page's </body>, never to your repo or what the build made, so a plan change shows within a few minutes without a deploy. Previews and anything but a page a browser opens (JSON, a page your code fetches, a frame) never carry it. It's one stylesheet and one script, and a page whose Content-Security-Policy header refuses inline ones gets their hashes added to it, so the policy still refuses everything else (a policy in a <meta> tag isn't read, and under one the badge shows as a plain link). A badged page keeps an ETag of its own, the app's with the badge's version, so a browser revalidating it gets a 304 when the app's page is unchanged.
It steps aside from a bar fixed to the bottom of the screen that has a link or a field in it. Where the page's own controls belong in that corner, such as a chat's composer and its send button, put the badge in another corner with the app's badge_corner (bottom-left, top-right or top-left). It moves at once, without a deploy, and in a top corner it drops below a bar fixed to the top instead:
app = noclick.Project.from_name("inbox")
app.update(badge_corner="top-right")Limits and billing
| Limit | Value |
|---|---|
| Apps per account | 100 |
| Builds running at once | 4 per account |
| One build | 15 minutes: installing at most 8 of them, restoring or saving the dependency cache at most 2 (a slower cache is left out), the build and bundling what's left |
| An app's source | 100 MB compressed: large media goes to a bucket |
| What a build publishes | 200 MB compressed, 20,000 files, 25 MB a file: large media goes to a bucket |
| Rollback without a build | the last 10 production deployments |
| A branch's preview | serves 30 days after its deploy |
| A request's body (either runtime) | 100 MB: a bigger file goes to a bucket |
Memory (edge) | 128 MB for each copy of the app, shared by the requests it serves at once |
CPU time per request (edge) | 30 seconds |
A container (container) | 1 vCPU and 512 MiB, up to 10 at once, none while idle; its settings go up to 8 vCPUs and 32 GiB, 3 kept warm |
A request (container) | 5 minutes; up to 60 with request_timeout_s |
| Runtime logs | kept 7 days |
| Schedules per app | 20 |
| A schedule's request | 30 seconds |
| One secret | 5 KB |
| Values in an app's environment | 128 |
Your account pays for everything an app does, attributed to the app and the user it belongs to: the requests it serves and the CPU time it uses (previews cost the same as production while they serve), its builds by the second (never a deploy that failed on NoClick's side), what its calls to its bindings cost at their own prices, its email, app.ai, and the turns of the agents it messages. What a bound database, bucket or dict stores belongs to that resource and counts toward its own user, not the app, since two apps can bind one database. noclick.usage(group_by="project") gives each app's spend this month, to bill its user on.
Hosting and builds cost what NoClick's providers charge for them. Every request an app answers costs $1.90 a million on its way in, whatever answers it, and what runs its code is added:
edge | container | |
|---|---|---|
| A million requests | $1.90 | $1.90 |
| A million requests its code answers, added | $0.60 (a static file runs no code: nothing added) | $0.40 |
| Compute | $0.02 a million ms of CPU time | $0.0909 an hour of the container serving requests ($0.12726 in ap), at 1 vCPU and 512 MiB: a size of its own costs what it adds up to |
| A build, by the second | $0.0031656 a minute ($0.0055308 for Next.js) | $0.006 a minute |
The way in also uses a little CPU time of its own, shared out by request at $0.02 a million ms, and a request the app never answers adds $0.60 a million for the error it logs.
All of it counts toward the cap of the user the app belongs to, and toward the app's budget_usd_per_month: what its code spends, the turns of the agents it messages or made (whatever started them), and the uptime of the sandboxes and browsers it made. noclick.Usage.limits() lists each app with a budget and what it has spent.
Its monthly budget
Every app made through the API has one, so a bug or an attack can't run up your bill: the budget_usd_per_month its maker sets, else $10. An agent making a site for you sets one that fits what it's for and says so (NoClick's own sets a plain site's at $5, one with an assistant at $20, and one that buys a number or makes calls higher, such as $100). Only you change it afterwards, in the app's page under Resources, the console, or app.update; an agent can't raise it, and neither can the app's own code.
An app the app's code makes nests under it: what the new app spends counts toward the budget of the app that made it too, all the way up, and the budget it's given (and any budget, card limit or spend its code gives what it makes: an agent, a channel, a workspace) is at most what the maker has left this month. So an app's code can never spend past its own budget by making another.
$10 is about what a chat assistant's 800 turns cost (an agent's turn is about a cent on average); serving a site costs a fraction of a cent a day. Raise it for an app that does more; an app with code always has one, since its code acts with a key of your user's. An app NoClick publishes from an automation has none until you set one.
app = noclick.Project.from_name("booking", repo=repo, create_if_missing=True, budget_usd_per_month=20)
print(app.budget_usd_per_month) # 20.0
app.update(budget_usd_per_month=50)When it runs out
Once the app's budget, its user's cap or your account's balance is used up, NoClick stops what the app spends without taking it offline: a customer's site going dark is worse than a month that ends a little over budget.
- It keeps serving. Pages, API routes and scheduled requests run, and so does every call that reads what the app already has. Serving costs $1.90 a million requests, so only traffic the site was never built for (a flood) costs much more: once the month's spend reaches twice the budget, its pages pause too, and serve again when the budget is raised or the month turns.
- Its paid calls fail before doing anything, with
noclick.SpendCapExceeded(scopeisprojectfor its budget,userfor its user's cap) ornoclick.PaymentRequired(your balance). The error names the app inprojectandproject_id, says what ran out with itscapandspent, and itsnext_stepsays how to lift it: raise the budget withapp.update, raise the user's cap, add funds, or wait for the month to turn. - Its email waits. A message
email.sendsends isheldand goes out once the app can pay again, or fails after 3 days, never charged, so a form never loses what a visitor sent (When the account can't pay); a code, atime_sensitivemessage and a broadcast are refused. - Deploys are refused with the same error, and production keeps serving the last good deployment.
- What spends on its own stops. The sandboxes and browsers its code started stop, its automations' triggers are refused, a call isn't let in and a text isn't sent, a card's charge is declined, and a machine or a number whose renewal the budget can't cover gets 48 hours before it stops or is released (above).
- You hear, not your customer. NoClick emails your account's owner once when the app reaches its budget in a month, saying which app, what stopped and when it starts again, and once more if its pages pause, and emits a
spend.cap_reachedevent naming the app and its user. NoClick never writes to your users about money: whether and how to tell them is yours to decide, since lifting the limit is too.
| What the app calls | Keeps working | Fails: its paid calls |
|---|---|---|
| Database | query, schema | execute, batch, and a query that calls noclick.embed |
| Bucket | read, head, objects, url, a download link, remove, complete_upload, abort_upload | put, an upload link, start_upload, upload_part_urls |
| Dict | get, keys, items, pop, remove, clear | put, put_if_absent, increment, update |
| Queue | get, iterate, ack, nack, release, len, peek | put, put_many |
| Secret | its keys, in the environment | |
| Connection | lookup | run |
| Agent | history, conversations | message, send, ask |
app.email | status, messages | send, broadcast |
app.ai | models | chat, embed, image, transcribe |
The rule underneath: what reads what the app already has keeps working, so the site stays up and shows its data, and what adds something (a write, a message, a model call, a turn) fails. Keeping working isn't the same as free. Queue reads, secrets and settings cost nothing, as do downloads' bytes, but database rows read, dict reads and file requests are billed at their resource's price even at a cap. They're bounded by the traffic its hosting serves, so usd can end the month past the budget by what serving and reading cost; usage() shows by how much.
Catch the two errors where the app makes a paid call, and serve the page without it:
app = noclick.Project.current()
try:
summary = app.ai.chat("Summarize in one line: the class was great but the room was cold.").text
except (noclick.SpendCapExceeded, noclick.PaymentRequired):
summary = None # the page shows the reviews without a summaryErrors
| Error | When |
|---|---|
NotFound | no app, deployment or schedule by that name or id for the user the call acts for, a branch or commit the repo doesn't have, a domain that doesn't serve the app, or, from an app's code, something another app's code made or an operation it didn't start |
Conflict | the name is taken, the domain belongs to another NoClick account, a production deploy while a live session is open, live editing an app it can't run on, a live command sent in its request while the session starts or deploys, or, from an app's code, a name it resolves names what another app's code made |
InvalidRequest | a branch name that isn't valid, a secret name that isn't valid, a cron expression that isn't, or app.ai on a project reached with your own key |
OperationFailed | a build failed (deployment_id names it), or a live session's end didn't deploy because its build or check failed |
QuotaExceeded | the account has as many apps, builds running, live sessions open or live commands running in the background as it can |
SpendCapExceeded | the app's budget or its user's cap is used up: a deploy is refused, and at run time so are its paid calls (When it runs out) |
PaymentRequired | your account's balance is used up: the same |
PermissionDenied | the app's code made a call it never makes (What the app's code can do), such as changing or deleting what it didn't make, or a call not acting for your whole account handed out a name under your domain |
Every method is in the Project reference: deploy, bind, update, schedule, logs, usage, and Deployment, Schedule, ProjectAI and ProjectLive with theirs.