Skip to main content
An AGO app is a small web page or API that you build by asking Claude, Codex or another coding agent. AGO hosts it, deploys every change and handles sign-in: only your team, your AGO agents and the servers you give a key to can reach it.
AGO Apps is enabled per workspace: contact AGO to turn it on. For now, only staff members of the workspace can open an app in their browser.

What you can build

  • A page for your team, at https://<app>.<workspace>.agoapps.com: a form, a dashboard that combines several APIs, a calculator. People open it with their AGO account.
  • An API for your agents: an agent tool that looks up a price, formats a document or calls a service your agents need.
  • An API for your own programs: your back office, a script or an integration platform calls the app with a key.
An app can keep data in its own databases and call other services with keys kept as secrets. For public pages that anyone can open, such as a help center, create a site instead.

Create your first app

1

Connect Claude to AGO

Connect your MCP client to AGO and grant the Apps Write scope.
2

Describe the app

Ask, for example: “Create an AGO app called price-check that returns the price including VAT for an amount and a country.” Claude creates the app, writes the code and waits until it is live.
3

Open it

Open the link Claude gives you, or go to Admin › Developer › Apps and choose Open app on the app’s card.
To change the app, ask Claude again. Every change is live in about a minute. If a change does not build or its tests fail, the previous version keeps running and Claude sees the error. To check a change before your team sees it, ask Claude to make it on a preview first.
Get the remote and a token with get_app_git_credentials, then work like with any repository. A push to main goes live; a push to any other branch updates the app’s preview.
A new app contains src/index.ts (a page at / and a JSON endpoint at /api/hello), AGENTS.md and CLAUDE.md. AGENTS.md holds the rules of this page for coding agents: keep it in the repository.

Use your app

Open it in a browser

The first time someone opens the app, the browser goes to your AGO workspace and comes back signed in, without a consent screen. The session lasts one hour, then the next page opened signs the user in again, usually without them noticing.

Let an agent call it

  1. Open Admin › Developer › Apps, select the app and open API.
  2. Select an endpoint and choose Create tool. AGO opens an HTTP Request Tool filled in from the endpoint.
  3. Review and save the tool, then add it to your agent.
Leave the tool’s authentication empty: AGO signs every call to your workspace’s apps and tells the app which user the agent acts for. The API tab needs the app to describe its endpoints at /openapi.json; new apps include one.
Copy the app’s API endpoint from For your AGO agents in Overview, for example https://api.agoapps.com/acme/price-check. Use it, followed by a path, as the URL of an HTTP Request Tool or an API Data Source, such as https://api.agoapps.com/acme/price-check/vat. Leave the authentication empty.Copy configuration in the API tab copies one endpoint’s OpenAPI description, to paste in ChatGPT, another assistant or an integration tool. It contains no credentials.Automatic tool setup supports GET, POST, PUT and DELETE, path and query parameters, and JSON object bodies. Uploads and custom header or cookie parameters need manual configuration.

Call it from outside AGO

Any program outside AGO can call the app’s API: your back office, a script, an integration platform or a tool such as Postman. It needs a key created for the app.
1

Create a key for this app

In Admin › Developer › Apps, select the app, open API and choose Create key under Access from your servers; the Server keys button at the top of the tab takes you there. Name it after the program that will use it and, if you want, restrict it to that program’s IP addresses. Copy the key: it is shown only once.
2

Find the URL to call

The API tab shows the app’s Base URL, for example https://api.agoapps.com/acme/price-check, and the endpoints the app publishes. Add the endpoint’s path to the base URL: https://api.agoapps.com/acme/price-check/vat.
3

Send the key with each request

Put the key in the Authorization header, after Bearer. Nothing else is needed: no token to request first, nothing to renew.
The response is the one your app’s code returns. When a call is refused before it reaches the app, the status code and error tell why: see Manage and troubleshoot.
Keep the key on the server or in the script’s settings. Never put it in a web page or a mobile app, where anyone can read it: calls made from a web page on another site are refused anyway. The key can only call this app: it gives no access to the rest of AGO, and other keys, including Full Access keys, cannot call apps. Create one key per program so you can revoke them one by one. A key keeps its app when you rotate it. A revoked key stops working within 5 minutes; an IP restriction applies to every call. You can also create the key in Admin › Developer › API Keys, with the Apps Invoke scope and the app selected. Programs that already exchange the key for a 5-minute token with POST /api/v1/apps/<app>/tokens, then call the app with that token, keep working.

Write the code

This section is for you or the coding agent writing the app; the app’s AGENTS.md contains the same rules.

The contract

src/index.ts exports a fetch function that receives each request and returns a response. Route on new URL(request.url).pathname and request.method. The second argument, env, holds your workspace name in env.AGO_TENANT, the app’s secrets and its databases.

Who is calling

Your code never checks a password or a token: AGO does it before the request reaches the app, then tells your code who is calling with these headers. Trust these headers: AGO removes any X-Ago-* header sent by the caller, and your app cannot be reached without going through AGO. For example, to accept a route only from your servers:

What is available

  • Web-standard APIs: fetch, Request, Response, Headers, URL, URLSearchParams, crypto.subtle, crypto.randomUUID, TextEncoder, TextDecoder, atob, btoa.
  • npm packages that only use those APIs, for example zod or date-fns. List them in package.json; install scripts do not run.
Node.js built-ins (fs, path, Buffer, process, child_process, net) are not available, and packages that need them fail. There is no filesystem: keep data in a database. Global variables may survive between requests but can be reset at any time.
If you run the app on your computer, commit the package-lock.json that npm install creates: the build then installs exactly the versions you tested. To run tests on every deployment, add a test script to package.json.

Secrets

Keep the keys of the services your app calls, such as an OpenAI or a CRM API key, as secrets, never in the code. Set a secret in Admin › Developer › Apps, on the app’s Secrets tab, or with the API and the Apps Write scope:
Setting an existing secret replaces its value. GET /api/v1/apps/<app>/secrets lists the names and DELETE /api/v1/apps/<app>/secrets/<NAME> deletes one. Claude can list and delete secrets but cannot set them: give a key to AGO yourself, never in a conversation. Read a secret from env:
  • Names use uppercase letters, digits and underscores, start with a letter and have 64 characters at most. Names starting with AGO_ are reserved.
  • A value is at most 5 KB, and an app holds at most 50 secrets.
  • An app receives secrets once its first version is live, about 30 seconds after you create it.
  • Values are never shown again, not even to staff. To change one, set the secret again.
  • Anyone who can change the app’s code can read its secrets. Give the app its own key, with the lowest permissions and a spending limit when the service offers one.
  • The preview has its own secrets: add ?environment=preview to these requests, for example to give it a test key. Set them once the preview has been built.

Databases

An app can keep data in SQL databases (SQLite, on Cloudflare D1). Each database belongs to one app: no other app or workspace can reach it. Declare a database in ago.json at the root of the repository, and create its tables in SQL files under migrations/:
ago.json
migrations/0001_init.sql
Each deployment applies the new migrations, in file name order, before the new version goes live. To change the schema, add a file such as migrations/0002_add_tags.sql; never edit a migration that already ran. Use it from env, under the name declared in ago.json:
Always pass values with ? and .bind(...), never by building the SQL text. The D1 documentation describes .first(), .run() and .batch().
  • Names use uppercase letters, digits and underscores, start with a letter and have 32 characters at most. Names starting with AGO_ are reserved, and a database cannot share its name with a secret.
  • An app has at most 5 databases of up to 10 GB each. With several, put each one’s migrations in its own folder: migrations/DB/0001_init.sql, migrations/AUDIT/0001_init.sql.
  • A migration runs as a whole or not at all. If one fails, the previous version stays live and the deployment shows the SQL error.
  • Removing a database from ago.json detaches it from the app but keeps its data.
  • Data is stored in the European Union.
  • The preview has its own databases, created empty and migrated from its branch: trying a change never touches the live data. Add ?environment=preview to read them.
The app’s Databases tab shows the tables and their rows. Claude reads them with query_app_database, and the API with POST /api/v1/apps/<app>/databases/<DATABASE>/query and the Apps Write scope: both accept a single SELECT and return at most 200 rows. Only the app’s code can change the data.

Limits

Browser rules

  • POST, PUT, DELETE and WebSocket requests must come from the app’s own pages. A request sent from another site, including another app, gets 403 with {"error": "cross_origin_request"}.
  • Cookies set by the app must not have a Domain attribute; such a Set-Cookie header is removed.
  • After the one-hour session, a fetch from the app’s page gets 401 with {"error": "login_required"}: reload the page.

Examples

A JSON API with validation

GET /vat?amount=100&country=FR returns {"amount":100,"rate":0.2,"total":120}.

A page that posts to its own API

To keep the notes, store them in a database.

Calling an external API

For an API that needs a key, store the key as a secret.

Using an npm package

package.json

Deployments

Each change saved on main is deployed in about a minute:
  1. AGO fetches the code and installs the npm packages listed in package.json, without running their install scripts. With a package-lock.json, it installs exactly the versions listed there.
  2. It bundles src/index.ts (or src/index.js) with its packages.
  3. It runs npm test if package.json has a test script.
  4. It applies the new database migrations, then puts the new version live.
If a step fails, the previous version keeps answering. A change whose files were already built, such as a promoted preview, skips steps 1 to 3. If two changes are built at the same time and the older one finishes last, it is marked superseded and not deployed. To check which version is live, call GET /_ago/version on the app: every deployed app answers it with {"version": 7, "commit": "3f2a9c…", "builtAt": "…"}. A change is live once the commit served is the one you made. Right after a deployment, some requests can still reach the previous version for a few seconds.

Previews

A change saved on any branch other than main is built like a live change, but deployed as the app’s preview, at https://preview--<app>.<workspace>.agoapps.com (API: https://api.agoapps.com/<workspace>/preview--<app>/…). Your team signs in to it like to the app, agents call it the same way, and the live app is not affected.
  • An app has one preview: the branch saved last.
  • The preview has its own secrets and databases. env.AGO_ENVIRONMENT is preview there and production on the live app.
  • Ask Claude, for example: “Try a new layout for price-check on a preview.” It saves the change on a branch and gives you the preview link.

Put a preview live

When the preview is right, ask Claude to put it live (promote_app), or call POST /api/v1/apps/<app>/promote with {"branch": "<branch>"} and the Apps Write scope. main then gets the branch’s changes and the version you checked goes live within seconds, without being built again. Its new migrations are applied to the live databases. If main changed since the branch was created, the promotion is refused so that nothing live is lost: add those changes to the branch, check the preview again, then promote it.

Roll back

To put an earlier version back live, ask Claude (rollback_app) or call POST /api/v1/apps/<app>/rollback with {"version": 7}. It takes a few seconds, as the version is not built again.
  • Only a version that was live can come back, among the app’s last 10 different versions.
  • The code on main and the databases do not change: tables added since stay, and the next change saved on main is deployed as usual. Fix the problem in a new change, then save it.

Delete an app

Ask Claude (delete_app, after confirming the app’s name) or call DELETE /api/v1/apps/<app> with the Apps Write scope. The app, its preview, its code, its databases and their data, its secrets and the keys created for it are deleted for good. This cannot be undone.

Manage and troubleshoot

Admin › Developer › Apps lists the apps with their status and who created them. Open app opens the app; select its card to manage it:
  • Overview: the link to share with your team, the API endpoint for your agents, and the latest deployments.
  • API: the endpoints the app publishes, Create tool, and the keys of the programs that call the app.
  • Deployments: the latest 20 builds, with their logs and errors.
  • Secrets: the names of the app’s secrets.
  • Databases: the tables and rows of the app’s databases.
  • Code: the files of main. Markdown files open formatted; switch to Code to see their source, and toggle Wrap lines for long lines.

Security

  • Each app runs isolated from every other app. Its build only gets read access to the app’s code, never the credentials that deploy apps.
  • Every call is checked by AGO before it reaches the app: a session for people, a token valid 60 seconds for one app for your agents, a key created for the app for your servers. The app never receives these credentials.
  • An app’s databases are bound to that app. Workspace staff can read their data in the admin; only the app’s code can write to them.
  • Secret values go straight to the hosting platform, encrypted with the app. AGO does not keep them and nobody can read them back.
  • AGO can turn AGO Apps off for a workspace or a single app at any time; they then stop answering.