Osmosis SDK Execution Backends

An execution backend decides where an AgentWorkflow runs, how a request becomes an executable task, and where reward computation happens.

osmosis eval submit and osmosis train submit do not take a backend flag. Your rollout entrypoint constructs the backend when the Platform starts its rollout server. You also choose a backend when embedding the open source SDK in a self-hosted harness.

Choose a Backend Path

Treat HarborBackend as two distinct paths. Both Harbor modes isolate every rollout in a Harbor trial, but they assign ownership of the instruction differently.

Path	Instruction source	Task selection	Best fit
`LocalBackend`	Prompt fields become `ctx.prompt`; optional row metadata remains in `ctx.metadata`	One configured workflow handles every row	Fast iteration, debugging, and workflows that need no task container
`HarborBackend` template mode	The request prompt replaces `instruction.md` in a copy of one reusable task	Every request starts from the configured task directory	LocalBackend-style prompt processing with per-trial environment isolation
`HarborBackend` dataset mode	Each Harbor task keeps its own `instruction.md`	`metadata["harbor_task_id"]` selects a task directory	Existing Harbor tasks or datasets whose instructions, environments, and verifiers already define each unit of work

Template mode resembles LocalBackend only in its input model: one rollout definition processes changing dataset prompts. Its execution model is still Harbor, with a separate task copy and sandboxed trial for every request.

Shared Server Contract

All backends receive an ExecutionRequest and return an ExecutionOutcome containing the workflow result and optional grader result for that rollout’s single sample. A server created with create_rollout_server() admits rollout requests, serves results to polling callers such as RolloutClient, and performs best-effort ATIF persistence after execution. Calling backend methods directly does not install that server lifecycle. When the server shuts down, it stops admissions, cancels any rollouts that do not finish in time, and then awaits backend.shutdown(). The default ExecutionBackend.shutdown() does nothing, so existing custom backends keep working. Override it in a custom backend that owns persistent resources, such as sandboxes or worker pools. Your override should try to release every resource and print anything it could not clean up to stdout. The server reports when each rollout’s agent started as agent_started_at in result responses. By default, it records that time when execute() begins. A custom backend that runs setup work first, such as provisioning a sandbox, can set the class attribute reports_agent_start = True. Once its agent starts, the backend awaits mark_agent_started() with a UTC datetime on the active RolloutContext. Only the first call is recorded. See RolloutClient for how callers use this field. Backends do not discover workflow, grader, or config objects. The entrypoint selects them explicitly:

from osmosis_ai.rollout import LocalBackend
from osmosis_ai.rollout.server import create_rollout_server

backend = LocalBackend(
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
)
app = create_rollout_server(backend=backend)

Multiple workflow and grader classes can coexist in the entrypoint module. Constructor arguments determine which ones run; the SDK does not scan the module namespace.

Decision Guide

Start in process

Use LocalBackend while developing the workflow and grader. It gives you direct exceptions, breakpoints, and the shortest feedback loop.

Add one reusable environment

Move to Harbor template mode when every row should run in the same task environment but needs an isolated filesystem, process tree, or dependency set.

Preserve authored Harbor tasks

Use Harbor dataset mode when each task already owns its instruction and usually its verifier. This is the closest path for integrating a local Harbor dataset that already works with harbor run.

Dataset mode reuses Harbor task directories; it does not ingest a complete Harbor job config or arbitrary harbor run CLI arguments. HarborBackend replaces job orchestration and supports an Osmosis AgentWorkflow or one of its registered native Harbor agents.

Backend Guides

LocalBackend

Configure in-process execution, grading, concurrency, artifacts, and errors.

HarborBackend

Configure template or dataset mode, native agents, task verifiers, and sandbox capacity.

Get started

Core API

Integrations

Execution

Agent tools

Osmosis SDK Execution Backends

Choose a Backend Path

Shared Server Contract

Decision Guide

Backend Guides

LocalBackend

HarborBackend

​Choose a Backend Path

​Shared Server Contract

​Decision Guide

​Backend Guides

LocalBackend

HarborBackend

Choose a Backend Path

Shared Server Contract

Decision Guide

Backend Guides