How apps run
This page explains how apps with server-side processing run. Static sites do not need an app server to start. In a hybrid app that combines a static frontend with an API server, the startup and shutdown behavior below applies to the API server.
Keelson starts your app server when it receives traffic and stops it after a period without traffic. The next request starts it again.
Handle page loads and API calls within requests, enqueue work that continues after a request as a background task, and use Keelson scheduled jobs for work such as daily reports. Work that assumes the app is always running is not supported.
When web apps start and stop
Section titled “When web apps start and stop”When a request arrives while an app is stopped, Keelson starts the app. The first request after a shutdown may therefore take longer than usual.
After a restart, variables held in memory and data written to local files during execution are lost. Save data you need to keep in Managed SQLite or with the Files / Media SDK.
See Database (Managed SQLite) and Files and media.
Work that runs within a request
Section titled “Work that runs within a request”Complete all work needed for a request, including saving data and calling external APIs, before returning the response.
Background work that continues after the response is sent is not guaranteed to finish. If your app uses FastAPI BackgroundTasks or starts asynchronous work without waiting for it, you need to change how that work runs: await short work before returning the response, and enqueue work that must continue after the response as a background task.
You can use streaming to return results incrementally, such as an AI-generated answer. Streaming does not provide a way to keep processing after the connection closes.
Work that continues after a request
Section titled “Work that continues after a request”Declare work such as heavy external API calls, PDF or image generation, or anything that exceeds the request time limit under tasks in keelson.yaml, and enqueue it from your app with the SDK. Keelson runs the task’s command once in an execution environment separate from the web app and retries it automatically if it fails.
A task may run more than once, so write it so that running it twice does no harm. See Background tasks for setup instructions.
Work that runs on a schedule
Section titled “Work that runs on a schedule”Configure daily reports or periodic data synchronization in the crons section of keelson.yaml. These jobs run on schedule even when nobody is using the web app.
Each job starts in an execution environment separate from the web app and exits when its command finishes. Save data shared with the web app in a database or another persistent store.
Timers and schedulers inside the app do not run while the app is stopped. Use Keelson scheduled jobs for recurring work.
See Scheduled jobs for setup instructions.
Choose how to run your work
Section titled “Choose how to run your work”| What you want to do | How to implement it |
|---|---|
| Save a submitted form | Save during the request, then return the result |
| Display an AI answer as it is generated | Stream the response during the request |
| Create a report every morning | Configure a scheduled job |
| Sync with an external service periodically | Run one synchronization pass per scheduled job |
| Accept heavy work and run it after the response | Enqueue it as a background task |
| Collect work and process it later in batches (a wait is acceptable) | Save pending work in the database and process it with a scheduled job |
Saving work for later introduces a delay until the next job runs. Use a background task for work that should start right away. In either case, you need to handle duplicate processing and failures. See Background tasks and Job design rules.
Keelson does not support continuously running workers. Enqueue work that continues after a request as a background task.
Work in the browser
Section titled “Work in the browser”The behavior above applies to server-side processing. These restrictions do not apply to browser-side timers or automatic page updates.
Execution time limits
Section titled “Execution time limits”HTTP requests, background tasks, and scheduled jobs each have a time limit. Split long-running work into units that finish within the applicable limit.
See Plans and limits, Background tasks, and Scheduled jobs.