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

# Execution Model

> Understand how public process requests become queue items, runtime actions, and callbacks.

# Execution Model

Phonefarm exposes a process-oriented public API, but the underlying runtime is a layered system.

## The Public Model

For callers, the lifecycle is:

1. Submit a request.
2. Receive an accepted response.
3. Observe `process.updated` callbacks.
4. Poll the process record for current state.
5. Cancel with a process-aware endpoint if needed.

## The Internal Flow

Under the hood, the flow is:

```text theme={null}
public request
  -> capability request row
  -> planned actions
  -> child queue items
  -> claimed work on a phone
  -> isolated run container
  -> executor action(s)
  -> process sync
  -> callback + pollable state
```

## Key Objects

| Term          | Meaning                                                                           |
| ------------- | --------------------------------------------------------------------------------- |
| Process       | The public execution object returned to callers. Backed by `capability_requests`. |
| Capability    | A higher-level unit of work such as `keyword_warmup` or `maintenance`.            |
| Queue item    | An internal execution record that the worker can claim and run.                   |
| Run container | An isolated worker container for one claimed queue item on one phone.             |
| Callback      | A best-effort push notification with normalized process state.                    |

## Primary Public Entrypoints

Use these for new integrations:

* `POST /capability-requests/enqueue`
* `POST /maintenance/requests`
* `GET /processes/{process_id}`
* `POST /processes/{process_id}/cancel`

## Compatibility Entrypoints

These older endpoints work directly with queue items:

* `POST /ingest`
* `POST /cancel`

Use them only if you need direct post-video queue-item behavior.

## Routing Modes

Capability requests accept a target with one routing mode:

| Routing mode | Meaning                                                                                 |
| ------------ | --------------------------------------------------------------------------------------- |
| `direct`     | Target a specific `phone_id` and `account_id` for immediate direct execution readiness. |
| `queue`      | Create work that will be materialized and claimed later.                                |
| `group`      | Fan out across explicit `phone_ids` and or `account_ids`.                               |

Not every capability supports every routing mode. See [Capability Registry](../reference/capability-registry).

## Run Modes

| Run mode     | Meaning                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `manual`     | Allowed for all currently implemented public capabilities.               |
| `unattended` | Allowed only for capabilities that are both permitted and live verified. |

Important: `fyp_warmup` is live-verified for unattended watch-only use, but only when `like_probability`, `save_probability`, and `comment_probability` are each explicitly `0`. `fyp_comment_growth` and `maintenance` remain manual-only.

## Callbacks Versus Polling

Callbacks are useful for event-driven systems, but they are not the source of truth:

* callbacks are best-effort
* callback failure does not fail the originating API request
* polling `GET /processes/{process_id}` is the authoritative view

## Read Next

* [Process Lifecycle](./process-lifecycle)
* [Capability Requests](../api/capability-requests)
* [Webhooks](../guides/webhooks)