Deployments.ai Docs
Platform

Agent-built apps

Web apps that deployed agents build with a Postgres database and a static site, the members who can open them, the publication settings that decide who an app serves, and the custom domains it can answer on.

An agent-built app is a web app that a deployed agent builds with the app.* tools. Each app has its own Postgres database and a static site at https://<slug>.<apps domain>. The database's api functions are the app's API, and the site calls them at /_platform/api/<name>. Members of the organization sign in to use the app. A public app also serves its pages and its visitor functions to people who do not sign in.

What an agent does

ToolWhat it does
app.createCreates the app and its database. The slug becomes the subdomain and is never reused.
app.listLists the apps the agent owns in its workspace.
app.describeReturns the publication settings, the schema, the api and visitor functions, the releases, and a TypeScript client.
app.migrateApplies one schema migration as a single transaction.
app.queryRuns one read-only SQL statement.
app.dev_tokenMints a short-lived token so a dev server in the sandbox can call the app's API.
app.releaseUploads a built site from the sandbox as a new release.
app.promoteMakes a release the live site. Promoting an earlier release rolls back.
app.set_publicationChanges the app's audience, serving, or both.

An agent can also write visitor functions, which anyone can call without signing in once the app is public. Visitors can call no other function. The agent cannot attach a custom domain.

An app is a draft until its first promotion. A person must approve these agent calls:

CallNeeds approval when
app.migrate, app.promoteThe app has a live release or its audience is public. Promoting the release that is already live never does.
app.set_publication to publicAlways, unless the app is already public.
app.set_publication with a new servingThe app has a live release.

A call that only sets audience back to members never needs approval, and no other agent call does. The approval request states why the call needs approval, such as "it opens app orders, which has no live release yet, to anyone on the internet". A promotion's reason names the release that is live, which the promotion replaces. The rule is checked again when the call runs. The call fails with approval_required if it now needs approval and was allowed without it, or if the reason it would state now differs from the reason the person approved. That happens when the app goes live, becomes public, or returns to members in between, and for a promotion when a different release goes live. The agent then calls again to ask for approval.

Who can open an app

A member opens an app by signing in on its URL. The member's role in the app comes from two settings:

  • access.organizationMembers gives every organization member none, viewer, or editor.
  • A grant gives one member viewer or editor on top of that.

A viewer can call the app's read functions. An editor can also call its write functions.

Publication settings

Every app has a publication setting with two fields.

FieldValuesDefault
audiencemembers, publicmembers
servingsingle-page, static-sitesingle-page

audience says whether the app serves only signed-in members or also visitors who do not sign in. serving says whether every page path returns the app's index.html, as a single-page app expects, or each path returns its own HTML file, as a static site expects. An app created before these settings existed reports the defaults.

The app gateway reads both fields. Public apps describes what audience changes, and Static-site serving describes serving.

When you set audience to public, the platform first brings the app's database up to the current layout through the same idempotent step that creates it. Then it writes the new setting. If the database step fails, the setting does not change. The first app.migrate on an app created before these settings existed runs the same step. For 10 minutes after the step starts, the platform refuses to erase the app, so the step cannot recreate the database of an erased app. An erase in that window answers 409 app_state_conflict and names the time it becomes possible, whether the app is active or archived.

Change the settings with setAppPublication:

deployments app set-publication <appId> --audience public --serving static-site

Send one field or both. The field you leave out keeps its value.

Public apps

An app is public when its audience is public, it is active, and it has a live release. An app with a public audience but no live release behaves as a members app until its first promotion.

RequestMembers appPublic app
A page, signed in with a roleThe pageThe page
A page, not signed inA 302 redirect to sign-inThe page
A page, with a session the app refuses403The page
An API call, signed in with a roleThe call, run with the member's roleThe call, run with the member's role
An API call, not signed in401 unauthenticatedA visitor call
An API call, with a session the app refuses403A visitor call, or 403 for a function visitors cannot call
/_platform/me, not signed in401401

A visitor gets the same page a member gets, with the same cache-control: no-store header. The app refuses a session that belongs to another app or another host, and a session whose person is not an active member or has no role in the app.

A visitor call runs only functions in the app database's visitor schema, as the app's visitor role. A visitor who is not signed in and calls an api function or a name the app does not have gets 401 unauthenticated, the same answer for both, so signing in may help and the answer does not reveal which names exist. A person whose session the app refuses gets that refusal instead, such as 403 not_a_member, so signing in again does not change the answer. A signed-in member who calls a visitor function on a public app runs it as the visitor role too.

The generated client sends the browser to sign-in only on 401 unauthenticated. On a 503 it waits for the Retry-After delay, at most 30 seconds, and sends the call once more, so a retried visitor call counts twice against the address limit. Every other error, and a second 503, throws PlatformApiError with the status, the code, the message and retryAfter, the seconds from the Retry-After header or null.

A visitor call must come from the app's own pages. The gateway refuses it with 403 unless the request sends Sec-Fetch-Site: same-origin and Content-Type: application/json, which a fetch from the app's pages does. A call with an Authorization: Bearer header skips this check, because a browser never attaches one on a page's behalf. A bearer token the app refuses still runs as a visitor call. The gateway also limits visitor calls and visitor page loads.

LimitValueAnswer when exceeded
Pages from one address, across appsA burst of 60, then 300 per minute429 page with Retry-After
Calls from one address to one appA burst of 10, then 10 per minute429 rate_limited with Retry-After
Visitor calls to one appA burst of 120, then 300 per minute429 rate_limited with Retry-After
Request body16 KiB413 body_too_large
Visitor calls running at once for one app2503 gateway_busy with Retry-After
Visitor calls running at once across all apps16503 gateway_busy with Retry-After
Time to answer2 seconds504 deadline_exceeded, or 503 gateway_busy if the call was still waiting for a slot

Only requests the gateway answers with a page count against the page limit. Its redirects do not: the 307s that send asset paths such as /site.css to the release's files, so a page and its assets count once, and the 308s that add or remove a trailing slash, such as /about/ to /about. Page loads by signed-in members do not count either.

A visitor call that answers 504 deadline_exceeded was rolled back, so a form can retry it without writing twice. A call that answers 504 outcome_unknown had sent its commit when the gateway lost the database's answer, so its changes may have been saved. This can happen to any call, a member's too. Retrying it may write twice, so check first, or make the function safe to repeat, for example with INSERT ... ON CONFLICT DO NOTHING on a key the form sends again.

The gateway counts an IPv4 address on its own and an IPv6 address by its /56 prefix. Each gateway task keeps its own counts, so the limit a visitor meets is the value above times the number of gateway tasks your installation runs. The app-runtime infrastructure module sets these values in gateway.tf, and an operator changes one by changing the module.

A session works only on the host where the person signed in. If its cookie reaches another host of the same app, a members app answers 403 other_host and a public app serves the request as a visitor.

Static-site serving

When serving is static-site, each page path returns its own HTML file from the live release. On a members app, a person still signs in first.

RequestResponse
/index.html
/about.htmlabout.html
/aboutabout.html. If only about/index.html exists, a 308 redirect to /about/.
/about/about/index.html. If only about.html exists, a 308 redirect to /about.
A missing path with another file extension, such as /site.cssA 307 redirect to the release's copy under /_r/<releaseId>/
Any other missing pathThe release's 404.html with status 404, or a platform 404 page if it has none

Redirects keep the query string. A path with an empty, . or .. segment, an encoded /, or a backslash counts as missing. Page paths also answer HEAD.

The gateway removes any <base> element from a page. It points the page's images, media, scripts, style sheets, icons, preloads, and manifest at the release's files, resolved against the page's directory. It leaves links between pages alone. The redirects above serve every page from its own directory, so a relative link resolves to the right page.

app.release records the release's .html and .htm files. A release may hold at most 500 of them, with paths of at most 64 KiB in total, and a larger build is refused. A release created before the platform recorded these files serves only its home page in static-site mode. Its other paths return a 404 page that says so. Release and promote the app again to serve every page.

SVG, PDF, XML, XSL, and XHTML files are never served, either as pages or from /_r/.

With the default single-page serving, every page path returns index.html with a <base href="/_r/<releaseId>/">.

Custom domains

An app can also answer on a hostname your organization controls, such as www.example.com or example.com. You attach the hostname to the app, publish two DNS records, and then refresh the domain so the platform checks that you own it.

Activation is automatic. Once a domain is verified, the platform requests a TLS certificate for the hostname, connects the hostname to the app, and moves the domain to active when CloudFront serves it. That usually takes a few minutes after the CNAME record resolves. The platform checks every domain every 5 minutes, and a refresh queues a check of that domain right away. List the domains to follow the progress.

Attach a domain

deployments app-domain attach <appId> --hostname www.example.com

The response lists the DNS records to publish in dnsRecords.

TypeNameValue
TXT_deployments-app.<hostname>deployments-app=<token>
CNAME<hostname>The installation's routing endpoint

The TXT record proves that your organization controls the hostname. The token is random and belongs to this attachment only. The CNAME record sends traffic for the hostname to the platform. A zone apex such as example.com cannot hold a CNAME. For an apex, publish an ALIAS or ANAME record with the same value, or use your DNS provider's CNAME flattening.

Attaching a hostname that the app already holds returns the existing domain and its token. The platform trims the hostname and lowercases it before it checks it. A hostname is ASCII, with punycode for international names. It has at least two labels and at most 236 characters, so that _deployments-app.<hostname> fits the 253 characters DNS allows. It cannot be an IP address. The platform answers 422 invalid_hostname for any other value, including an empty or longer one. It answers 422 hostname_reserved for the apps domain, for the API, identity, console, and stream gateway hostnames of the installation, and for every name under them. This release does not reserve the installation's docs hostname.

Verify a domain

After you publish the TXT record, refresh the domain:

deployments app-domain refresh <appId> <domainId>

Refresh looks up the TXT record. If the record holds the token, the domain moves from unverified to verified. If the record is missing or holds another value, refresh answers 422 txt_not_found and changes nothing. If the DNS lookup itself fails, refresh answers 503 dns_lookup_failed. Try again later. Refreshing a domain that is already verified or active skips the DNS lookup. A refresh of a verified or active domain then queues its setup at the edge and answers the domain as it stands, without waiting for the setup. The queued setup also requests a failed or timed-out certificate again. It usually starts within seconds, but it can wait for the 5-minute check of every domain to finish first.

The platform runs a queued setup once and does not retry it. If the setup fails, or cannot start within 10 minutes, the platform drops it. The 5-minute check still connects the hostname, but only a refresh requests a failed or timed-out certificate again. If the domain still shows certificate_failed or certificate_timed_out a few minutes after a refresh, refresh it again.

When CloudFront refuses to connect the hostname, the platform records domain_conflict or edge_rejected and tries again on its own: after 10 minutes, then after twice as long each time, up to once a day, until it succeeds. A refresh does not skip that wait, because every refused attempt can use up one of the installation's yearly TLS certificate requests. The problem message says when the next attempt runs.

Each TLS certificate request also counts against two daily limits: one for your organization and one for the whole installation. The defaults are 5 and 12 requests per UTC day. Connecting a hostname, and requesting a new certificate on refresh, each make one request. Detaching a hostname and attaching it again does not give the requests back. When a limit is reached, the platform records organization_certificate_limit or platform_certificate_limit and makes the request on its own after 00:00 UTC. The problem message gives the time.

Publish the TXT record before the first refresh. A refresh that finds no record makes DNS resolvers remember the miss for up to your zone's negative-caching TTL, which the zone's SOA record sets. Until that time passes, refresh can keep answering txt_not_found after you publish the record.

An attachment that is not verified claims nothing. Two organizations can attach the same hostname, and the first one to verify it wins. Every later attempt to verify that hostname, from any app, answers 409 domain_claimed until the winner detaches it.

A domain moves through these states:

StateMeaning
unverifiedAttached. The platform has not seen the TXT record yet and claims nothing.
verifiedOwnership is proven and the hostname is claimed. The platform is requesting the certificate and connecting the hostname.
activeCloudFront serves the app on the hostname with its own certificate. activatedAt records when.

A verified or active domain also carries problem, which is null or a code with a message. The platform clears it once the cause is gone.

CodeCauseWhat to do
certificate_failedThe certificate authority refused or revoked the certificate, or it expired.Check that the CNAME points at the routing endpoint, then refresh to request a new one.
certificate_timed_outThe certificate was not validated in time, usually because the CNAME did not resolve to the routing endpoint.Fix the CNAME, then refresh to request a new one.
domain_conflictAnother CloudFront resource, in this account or another, already serves the hostname.Remove the hostname there. The platform tries again at the time the message gives.
edge_rejectedCloudFront refused the hostname, usually because its CNAME does not point at the routing endpoint yet.Fix the CNAME. The platform tries again at the time the message gives.
organization_certificate_limitYour organization has made all the TLS certificate requests it may make today.Wait. The platform requests the certificate at the time the message gives.
platform_certificate_limitThe installation has made all the TLS certificate requests it may make today.Wait. The platform requests the certificate at the time the message gives.
previous_tenant_drainingThe hostname was detached and attached again, and the platform is still removing the earlier attachment from the edge.Wait. The platform connects the hostname once the earlier one is gone, usually in minutes.

Limits

LimitValueError when exceeded
Domains attached to one app, in any state10409 app_domain_limit_reached
Verified and active domains in one organization50409 organization_domain_limit_reached
TLS certificate requests for one organization per day5 by default (UTC days)organization_certificate_limit problem
TLS certificate requests for the installation per day12 by default (UTC days)platform_certificate_limit problem

The domain limits are the same for every organization in this release. The certificate request limits are set per installation.

Detach a domain

deployments app-domain detach <appId> <domainId>

Detaching deletes the domain and releases the hostname at once, so another app or organization can verify it. You can detach a domain while the app is provisioning, active, failed, archived, or being erased. Attaching and refreshing need an app that is provisioning or active, and answer 409 app_state_conflict otherwise.

Erasing an app detaches every one of its domains before the platform erases the app's data.

Serve and sign in on a domain

An app answers on a custom domain only while the domain is active and attached to that app. The domain serves the same pages and API calls as the app's slug URL, under the same publication settings. Every other hostname that reaches the platform gets 404 before the platform reads the app or touches its database. That includes a domain that is unverified or verified and a domain of another app.

Members sign in on a custom domain only when a person attached it. An API key can attach and verify a domain with no person involved, so on a domain that a key attached, the sign-in link sends the member to sign in at https://<slug>.<apps domain>. The member then uses the app at that URL. Visitors to a public app use every active domain, whoever attached it.

A session works only on the host where the person signed in. A session from the slug URL does not work on a custom domain, and a session from one domain does not work on another, so a member signs in separately on each.

The platform checks the domain again when the identity provider sends the member back. If the domain was detached, moved to another app, or attached again by an API key while the member was signing in, sign-in stops with a link to sign in at the slug URL.

After you detach a domain, the app stops answering pages and API calls on it within 5 seconds. The release files under /_r/ keep loading on that hostname until the platform removes the hostname from its edge, because release files are public. A domain that just became active can take up to 5 seconds to start serving.

Who can change an app

OperationScopePeopleAPI keys
List and read apps, grants, releases, and domainsapps:readEvery roleAllowed
Rename, set access, change the agent, grant, archive, erase, promoteapps:writeowner or adminRefused
Set publication; attach, refresh, and detach a domainapps:publishowner or adminAllowed when the key and its service account name apps:publish

To find one app by its slug, list apps with ?slug=<slug> (deployments app list --slug <slug>). The list holds that app, or nothing when no app in the environment has the slug. It reads one record however many apps the environment has.

Every change except a domain refresh also needs an Idempotency-Key header. A refresh moves the domain to the state that DNS shows, so repeating it is safe without one.

An API key that lacks apps:write gets 403 insufficient_scope on those changes. A key that holds it, directly or through a wildcard, gets 403 human_principal_required.

An API key gets apps:publish only when the key and its service account both name it. Neither apps:* nor platform:* grants it to a key, though both still grant it to a person. A key that relies on a wildcard gets 403 insufficient_scope, and it cannot create a service account or key that names apps:publish either. Publishing an app can expose its data to people outside the organization, and a domain decides where they reach it, so an automation gets these changes only when someone grants them on purpose. Agents have no tool for domains.

The CLI and the console request apps:publish when you sign in. If you signed in before your installation added the scope, sign in again before you change an app's publication.

On this page