Actor Standby

With Actor Standby, your actor runs as a small web server. Callers send HTTP requests to a Standby URL and Lantfly forwards them to a warm run of the actor in the caller's account. The run is started on the first request, serves many requests, and stops after it has been idle for a while. Use it for APIs that must answer in seconds, where starting a run per call would be too slow.

Standby runs are billed like any other run.

1. Serve HTTP in your actor

Listen on the port in ACTOR_WEB_SERVER_PORT (default 4321) on all interfaces:

src/main.js

import http from 'node:http';
import { Actor } from '@lantfly/actor-sdk';

await Actor.init();
const port = Number(process.env.ACTOR_WEB_SERVER_PORT ?? 4321);

const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, 'http://localhost');
  if (url.pathname === '/title') {
    const target = url.searchParams.get('url');
    const html = await (await fetch(target)).text();
    const title = /<title>([^<]*)<\/title>/i.exec(html)?.[1] ?? null;
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ url: target, title }));
    return;
  }
  res.writeHead(404).end();
});

server.listen(port, '0.0.0.0', () => Actor.log.info(`Listening on ${port}`));
Actor.on('aborting', () => server.close());

main.py

import asyncio
import json
import os
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

from lantfly import Actor


class Handler(BaseHTTPRequestHandler):
    def do_GET(self) -> None:
        body = json.dumps({"path": self.path}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)


async def main() -> None:
    async with Actor:
        port = int(os.environ.get("ACTOR_WEB_SERVER_PORT", "4321"))
        server = ThreadingHTTPServer(("0.0.0.0", port), Handler)
        Actor.on("aborting", lambda event: server.shutdown())
        await asyncio.to_thread(server.serve_forever)


asyncio.run(main())

Keep the server running until the run is stopped. Answer quickly: Lantfly waits for the server to answer before it forwards the first request.

2. Turn on Standby for a version

Standby is a setting of a version:

Enable Standby on version 1.0

curl -X PATCH "https://lantfly.com/api/v3/actors/<username>~my-actor/versions/1.0" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "standby": {
      "is_enabled": true,
      "desired_idle_instances": 0,
      "max_requests_per_run": 4,
      "idle_timeout_secs": 300,
      "memory_mbytes": 1024
    }
  }'

Field	Default	Meaning
is_enabled		Turns Standby on for this version.
desired_idle_instances	0	1 keeps the run after the idle timeout.
max_requests_per_run	4	Requests one run serves at the same time (1–1000). More requests answer 503 standby_capacity_exceeded.
idle_timeout_secs	300	Stop the run after this many idle seconds (30–86400).
memory_mbytes	the actor's default	Memory of the Standby run (at least 128).

Send "standby": null to turn it off.

3. Call the actor

Send any HTTP method to:

https://lantfly.com/api/v3/standby/<actor>/<path>

<actor> is the actor's id or username~name; <path> (and the query string) is passed to your server.

Call a Standby actor

curl "https://lantfly.com/api/v3/standby/<username>~my-actor/title?url=https://example.com" \
  -H "Authorization: Bearer $LANTFLY_TOKEN"

Lantfly finds the caller's Standby run of the actor, or starts one, waits until it is running and its server answers, then forwards the request and returns your answer.

Authentication

• Send an API token as Authorization: Bearer … (see API tokens).
• The token needs the actors.run permission. Read-only tokens are refused, even for GET, because any request can start a billed run.
• A token limited to some actors can call Standby of those actors only.

Limits and errors

Limit	Value
Requests waiting at the same time	5 per account (shared with MCP). More answer 429 rate_limit_exceeded with Retry-After: 5.
Total time of one request (waiting and forwarding)	300 seconds.
Response size	Limited; a larger response answers 502 response_too_large.

Error code	HTTP	Meaning
actor_standby_not_enabled		The actor's version has no Standby.
standby_capacity_exceeded	503	The run already serves max_requests_per_run requests. Retry later.
standby_run_not_ready	504	The run did not start or its server did not answer in time.
standby_run_failed	502	The Standby run failed.
standby_proxy_unreachable	502	The request could not reach the run.
request_too_large	413	The request body is too large.
response_too_large	502	Your answer is too large.
rate_limit_exceeded	429	Too many requests waiting for this account.

Errors use the usual envelope { "error": { "code", "message" } }. See Errors and the API page on Standby.

Tips

• Start serving as early as possible; do slow setup (browser launch, model load) after listen, or lazily on the first request.
• Keep per-request state in memory or in the run's key-value store. Different callers get different runs, one per account.
• Watch the run log of the Standby run like any other run; it shows up in the account's runs.