> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capsule.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks And Scheduling

> Use Capsule's built-in task execution model for background work, retries, cron jobs, and task-aware UI.

If your app needs to do real work beyond one chat reply, this is where that work belongs.

Capsule has a built-in task execution model, so you do not need a separate worker service just to run background jobs or recurring automation.

Tasks and schedules let Capsule apps keep the chat loop responsive while still doing real work.

## Why this is a platform feature

In Capsule, background execution is part of the same app model as chat, pages, and deploys. That means:

* tasks can share the same collections, settings, filesystems, and integrations as the rest of the app
* the UI can render task state directly with task cards and task boards
* you do not need to split the app across a request stack and a second job stack before the product is even useful

## Tasks

Tasks are declared with `@app.task()` or `@cpsl.task()`.

They are useful for:

* slow API calls
* report generation
* batch processing
* retries and cancellation
* work that should continue after the current reply

Tasks return `TaskHandle` objects from `.submit()` and `.schedule()`.

## What belongs in a task?

As a rule of thumb, put work in a task when any of these are true:

* it talks to an external system
* it might take more than a quick request-response turn
* it should retry safely
* the user should be able to leave the page while it keeps running
* the result should show up later in collections or a workflow page

Good examples are inbox syncs, report generation, attachment processing, enrichment jobs, or any state transition with real side effects.

## Schedules

Schedules are declared with `@app.schedule(cron)` or `@cpsl.schedule(cron)`.

Use them for:

* recurring syncs
* periodic cleanup
* digests
* precomputation and cache warming

Schedules run on cron, not in response to a live chat message.

## Task UI

Capsule has first-class task UI:

* `session.show_task(handle)` renders an inline task card
* `cpsl.ui.TaskBoard(...)` renders a full-page kanban view

That means background execution is part of the product surface, not just an implementation detail.

## How background work stays observable

Capsule gives you a few ways to make async work visible to the user:

* `session.show_task(handle)` for inline task cards from chat
* `TaskBoard(...)` for page-level visibility
* collections and data handlers for richer audit trails or workflow state

That combination matters. Real apps need users to trust that work was started, is still running, and either completed or failed for a reason.

## Runtime context

Tasks can optionally receive a `session`:

* with a bound `session`, the task can reply, notify, stream, and access `session.db`
* without one, the task still runs, but there is no live chat target

Scheduled handlers usually rely on `cpsl.current_session()` when they need owner-scoped runtime identity.

## Process isolation

Set `process=True` when the task should run in a separate OS process for:

* CPU parallelism
* crash isolation
* heavy local computation

## Locking

Task `lock=` values prevent duplicate work for the same logical key:

```python theme={null}
@app.task(lock="report:{report_id}")
async def build_report(...):
    ...
```

This is especially useful for idempotent jobs, recurring syncs, and user-triggered retries.

## How background work stays safe

The safety model is a mix of ordinary engineering and Capsule primitives:

* use `lock=` when duplicate work would be harmful
* use `retries=` when a task should self-heal from transient failures
* keep the side-effecting code inside the task instead of the chat turn
* write the resulting state back to collections so pages and later turns can inspect it

The model should help decide what to do. The task should own doing it safely.

## Related pages

* [Why Capsule](/concepts/why-capsule)
* [Tasks And Schedules](/features/tasks-and-schedules)
* [Decorators Reference](/reference/decorators)
* [Session And Request Context Reference](/reference/session-and-request-context)