Runtime & deploy reference

For the agent · read before your first deploy

You deploy an app by handing agenthost your project files in-band and letting it build and run them. This page is the contract: the one entrypoint each runtime looks for, the file it installs dependencies from, how the runtime is chosen, and how to confirm a deploy actually came up. Match these conventions and a deploy just works.

How a deploy works

Call create_app with your project source as inline files([{ path, content, encoding }]). agenthost builds it and runs it on managed hosting with automatic HTTPS and routing — you never configure a server, a container, or a port. Passingfiles to create_app builds and deploys in the same call;deploy_app ships new source to an app that already exists.

Builds are asynchronous. Both tools return as soon as the build is queued, so the status you get back is not the final one — poll get_app until it settles, then confirm the app actually serves. See Deploying & checking status.

Runtimes at a glance

The runtime decides how your source is built and started. Pass it explicitly asruntime (e.g. "node:22"), or omit it on create_app and agenthost infers it from your files. Each runtime looks for one entrypoint:

Inference is a convenience for the common case; when in doubt, set runtime explicitly. If you omit it and no runtime can be inferred, create_app fails and asks for one.

Static sites static

Your files are served exactly as handed, over HTTPS. index.html at the project root is served at /; other files are served at their paths. There is no build step and nothing to start — good for a landing page, a docs site, or any pre-built single-page-app bundle.

# minimal static site
index.html          # served at /
styles.css
app.js

Node node

A package.json is required — it both selects the Node runtime and holds the command that starts your app. On deploy, agenthost installs your dependencies, runs yourbuild script if you have one, then starts the app with npm start.

• Define a start script — it is the entrypoint. Without one, npm start has nothing to run and the app won't come up.
• A build script runs automatically before start, if present (e.g. to compile TypeScript or bundle a frontend). It's skipped when absent.
• Dependencies are installed from package.json (using the lockfile when you include one). Don't ship node_modules.

"scripts": {
  "build": "tsc",        // optional — runs if present
  "start": "node server.js"  // required — how your app starts
}

Python python

Python apps are served as a WSGI application. agenthost imports the nameapp from app.py — so your project must have a file namedapp.py at its root that exposes a WSGI callable named app. This is a fixed convention, not something you can rename with a parameter.

• The entrypoint is app in app.py. A Flask or Django app object named app in that file is exactly what's expected.
• List your dependencies in requirements.txt — and include gunicorn there, since that's what serves the app. Omit it and the app fails to start.

# app.py — must expose `app`
from flask import Flask
app = Flask(__name__)

@app.route("/health")
def health():
    return {"ok": True}

# requirements.txt
flask
gunicorn

PHP php

PHP apps are served from your project root with index.php as the front controller. Requests for real files (assets, other .php scripts) are served directly; everything else is handled by your index.php.

• Put an index.php at the project root.
• If a composer.json is present, its dependencies are installed for you (production, optimized). No composer.json is fine for a plain PHP app — omit it.

Choosing a version

Append a version to the runtime — "<language>:<version>". Leave it off and a supported default is used. static takes no version.

Examples: "node:24", "python:3.13", "php:8.4". An unsupported version is rejected with the list of supported ones.

Environment variables

Pass runtime configuration and secrets as env (a map of name → value) oncreate_app. They're stored securely and injected into your app's environment at run time — never written into your source. Read them the normal way for your language (process.env.X, os.environ["X"], getenv('X')). Only thenames of the variables you set are ever echoed back (as envKeys); values are not.

Deploying & checking status

Because builds are asynchronous, a successful tool call means "queued", not "live". Confirm a deploy in this order:

• Poll get_app until status settles (e.g. running or error). A freshly created app may report running from a previous deploy while the new build is still coming up, so don't stop at the first read.
• Prove it serves. The real signal is a request to the app's URL — hit a known route (a /health endpoint is ideal) and check the response body, not just that a status says "running".
• get_app_logs shows recent build/runtime output when you need to see why something crashed. It's best-effort and can be briefly unavailable — if it is, fall back to hitting the URL.

Common pitfalls

• Assuming a start_command (or port) field exists. It doesn't — those parameters are silently ignored. How an app starts is the per-runtime entrypoint convention above.
• Python entrypoint not named app.py / app. The import is app:app. A file called main.py, or an object named application, won't be found.
• Missing gunicorn in requirements.txt. It's what serves a Python app; without it the app can't start.
• Node without a start script. npm start needs one; add it to package.json.
• Trusting the first status. Builds are async — poll get_app and confirm with a real request before calling a deploy done.
• Shipping build output. Skip node_modules, vendor, and virtualenvs — dependencies are installed for you from your manifest.