Host a service with your app
An app can declare services (AIP-53 services[]): processes the daemon
runs for it, such as a web server for a bot's mini app. By default the daemon
starts each one when the app is installed and when it boots, and keeps it
running. A service that is only used now and then does not need that. This
page shows how to declare one, and how to have the daemon run it only while
somebody is using it.
Declare a service
In .agentproto/APP.md, or through defineApp({ services }):
services:
- name: viewer
command: node
args: [dist/viewer.js]
port: 8789command and args are run directly, with no shell (entry is the legacy
shell-line form). cwd is relative to the app directory. The daemon runs the
process detached, adds it to the session list as a command row labelled
app:<appId>:service:<name>, appends its output to <state>/services/<name>.log
and restarts it with a growing delay when it exits unexpectedly.
Add expose to give it a public URL through a tunnel; AGENTPROTO_PUBLIC_URL
then carries that origin to the process.
Run it only when it is used
services:
- name: viewer
command: node
args: [dist/viewer.js]
port: 8789
expose:
auth: service
activation:
mode: on-demand
idleStopMs: 600000 # stop after 10 minutes with no open request or connection (default 5 minutes)
startTimeoutMs: 30000 # a request waits at most this long for the cold start (default 30 seconds)With on-demand the daemon, not the process, listens on port, on the
loopback interface, from install and boot on. No process runs until a request
arrives:
- The first request starts it. The daemon spawns the command with
PORTset to a free loopback port and waits until the process accepts connections there. Requests that arrive during the start wait for it (one start serves them all). - It proxies. HTTP requests and WebSocket upgrades are forwarded as they
came in, with
Hostand the body untouched, and the response is streamed back. The process behaves as if it were listening onportitself. - It stops when idle. While a forwarded request or an upgraded
connection is open the service is busy, and a request is never cut off
however long it runs.
idleStopMsafter the last one ended, the daemon stops the process and its children. The next request starts it again.
If the process does not start, the caller gets 503 with a Retry-After
header and no detail in the body; the reason is in the daemon log. After an
unexpected exit the daemon waits 1s, then 2s, 4s, up to 60s, before it starts
the process for another request, so a crashing service is not respawned at the
rate requests come in. It never gives up for good: it keeps listening.
What the process has to do
- Listen on
PORT, and only there. The declaredportbelongs to the daemon, so a service that hardcodes it cannot be on demand. Bind the loopback interface (127.0.0.1):PORTis otherwise reachable on every interface you bind, without the daemon in front. - Only react to requests. A poller, a queue consumer, a long-lived
connection to a third party or a timer does its work while nobody is calling
it. The daemon would stop it as idle and it would miss that work, so it must
stay on the default (
mode: always, or noactivationat all). - Expect a cold start. The first request after an idle period pays for the
process starting. Keep that under
startTimeoutMs. - Do not hold connections open for nothing. An open streaming response or WebSocket counts as busy and keeps the process up until it ends.
Exposure
expose works as before: the tunnel targets http://127.0.0.1:<port>, which is
now the daemon's listener, so the public URL answers while no process runs and
the first request through it starts the service. With auth: guard a request
the guard refuses never reaches the listener and starts nothing. With
auth: service, anyone who holds the URL can start the process, which is the
price of an unguarded URL.
Seeing what it is doing
app_status lists services.activations for the app: each on-demand service
with its state (idle, starting, running, stopping, or absent when the
daemon could not take the port). Every start is a row in the session list
(an idle stop leaves it as killed), and the log file keeps every run.
Switching an existing service
Changing a running service between always and on-demand and reinstalling
(or restarting the daemon) replaces it: the keep-alive process is stopped
first, so the daemon can take the port. If something else still holds the
declared port, for example a copy started by hand, the install reports
port <n> is already in use for that service and the rest of the install goes
on.
Build your own agent app
An agentproto app (AIP-53) bundles agents, the workflows they run, an optional UI, and durable data into one versioned, installable unit.
Distribute an app
Once an app runs on your daemon (scaffold it, serve it), the next question is how it reaches other machines and other people.