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, run one agent execution, and return at most one RolloutSample. A server created with create_rollout_server() handles controller callbacks and performs best-effort ATIF persistence after execution. Calling backend methods directly does not install that server lifecycle. 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