Docs

Toupas for coding agents

Toupas makes the app on the user's computer live, at a link anyone can open. The user isn't expected to know anything about servers or deployment, so don't ask them for deployment details: Toupas works them out.

Make the app live

Call toupas_make_live with dir, the absolute path of the app's folder. It signs the user in if needed, works out how to prepare the app, writes toupas.json, prepares the app (in Docker for apps with their own server), sends only changed files, waits until the new version is live, and returns the link. Calling it again updates the live app.

The first time, it may stop and return:

• askUser: a question only the user can answer (copy local data or start empty; Toupas storage or their own). Ask it in its own words, wait for the answer, then call toupas_make_live again with the matching argument (copyLocalData, startEmpty, useToupasStorage, keepOwnStorage). Never answer it yourself.
• agentInstructions: something for you to do first, e.g. switch the app from SQLite to Postgres (E_LOCAL_DATA_STORAGE), or ask the user to install Docker Desktop (E_DOCKER_MISSING, then toupas_setup_docker).
• A sign-in link (E_SIGN_IN_REQUIRED): give it to the user; once they've approved it, call the tool again.
• status: "in_progress": preparing is taking a while. Call toupas_make_live again with the same dir: it keeps waiting for the same run, it doesn't start over.

Words to use with the user

Say "make live", "update the live app", "app", "version", "settings". Avoid "deploy", "deployment", "project", "container", "environment variable" unless the user uses them.

After it's live

• Something wrong: toupas_get_deployment (did the latest version go live, and why not) and toupas_get_logs (what the app printed).
• Settings and secrets: toupas_list_env, toupas_set_env (secret: true for passwords and keys), toupas_unset_env. Don't put secrets in code or in .env files that get uploaded; .env files never go live.
• Data: toupas_get_database, toupas_db_query; files: toupas_get_storage, toupas_list_files.
• Links: toupas_get_links, custom names (toupas_set_subdomain) and the user's own domains (toupas_add_domain). These are paid; the answer then includes a link for the user to pay in their browser.
• Plan and trial: toupas_get_project, toupas_get_usage, toupas_activate_project, toupas_get_billing.

Rules

• Payments always happen in the user's browser. Give them the link; never open it or pay yourself.
• Tools that delete or take things offline take confirm. Without it they only describe what would happen: show that to the user, and call again with confirm: true only if they agree.
• The same can be done in a shell with toupas <command> --json; toupas help lists the commands. Long-running things (toupas db tunnel, toupas dev db, toupas logs --follow) are only in the shell.