> For the complete documentation index, see [llms.txt](https://docs.apolo.us/index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apolo.us/index/apolo-mcp/capabilities/skills/apolo-flow-workloads.md).

# Apolo Flow Workloads

1. Resolve context with `$apolo-platform-user-context`. Resolve `workspace_path` as the Flow project root. It must contain a real `.apolo` directory. Live configuration is `.apolo/live.yml` or `.yaml`; batch configuration is `.apolo/<batch>.yml` or `.yaml`; optional project settings are in `.apolo/project.yml` or `.yaml`.
2. Use `flow_config_schema` to explore the root and referenced definitions from the installed Flow version's release-tagged JSON schema. For new canonical `.apolo/live.yml`, `.apolo/<batch>.yml`, or `.apolo/project.yml` files, use `flow_config_write`; it validates before writing, creates without overwrite, adds the version-pinned YAML-language-server schema URL, then rereads and validates the result. Use `flow_config_validate` for existing files before execution. Never put literal credentials in Flow configuration; use supported secret references or expressions. Validate project, live job or batch name, parameters, tags, executor, images, volumes, dependencies, and persistent output paths. Do not parse colored human tables for machine state. When a custom image is needed, follow the [Flow-first image-build workflow](https://github.com/neuro-inc/apolo-mcp/tree/master/docs/capabilities/skills/apolo-flow-workloads/references/image-builds.md): declare a dedicated, content-addressed image for each component and build it through the Flow project. Fall back to `apolo-extras image build` only when no Flow project is available.
3. Run live jobs asynchronously by default. Ensure the selected job has `detach: true` before `flow_live_run`; do not keep the MCP start call attached to the workload. After start returns, monitor separately with get, bounded logs, and bounded wait. Match Flow's project/job/suffix resolution rules.
4. Prefer submission-style handling for bakes: start through Flow orchestration, record the returned bake, then inspect or wait in separate bounded calls. Keep the start timeout bounded because the current upstream runner may hold the call open until its remote executor exits. Never post directly to the Flow persistence API: setup must collect configuration, handle images, and launch the supported executor.
5. Record every returned job/bake identifier and context in the session ledger. Keep attempt/task status, terminal reason, outputs, and executor evidence bounded.
6. On controlled failure, inspect structured state and logs, correct the source or parameter, present the exact correction diff/parameter change, and use the supported restart operation. Preserve the failed evidence; restart approval binds to that fix.
7. Treat live kill-all, bake cancel, and bake restart as destructive writes. Describe the exact target and effect, then invoke the operation so the MCP host can apply its approval UI. Require `managed` or `full` server policy and scope kill-all to the exact validated Flow project and context.
8. Verify persistent outputs before success and clean up only exact ledger-owned resources. Preserve a bounded failure path even when the happy path succeeds.

Use a documented bounded CLI fallback only when the installed Flow version lacks the typed facade. Rely on exit codes and JSON/NDJSON when available; never scrape Rich tables as an API.