LocalBackend In-Process Execution

LocalBackend runs an AgentWorkflow and optional Grader in the Python process that created the backend. It is the default starting point for rollout development and the backend used by the standard rollout scaffold.

LocalBackend is an execution strategy, not a laptop-only mode. The same entrypoint can run on your machine or on Platform-managed rollout infrastructure; in either case, the workflow shares the rollout server’s process and filesystem.

Install

LocalBackend is part of the base osmosis-ai package. Add the server extra when exposing it through create_rollout_server():

pip install "osmosis-ai[server]>=0.3.4,<0.4"

Create a Rollout Server

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)

The constructor is keyword-only. A workflow is required; grading is optional.

Parameter	Type	Description
`workflow`	`type[AgentWorkflow] \| str`	`AgentWorkflow` subclass or `"module:attr"` import path
`workflow_config`	`AgentWorkflowConfig \| str \| None`	Optional config instance or import path passed to the workflow
`grader`	`type[Grader] \| str \| None`	Optional `Grader` subclass or import path
`grader_config`	`GraderConfig \| str \| None`	Optional config instance or import path passed to the grader

Multiple classes can exist in the imported module. These arguments select the workflow, grader, and configs explicitly.

Execution Lifecycle

Create the workflow context

The backend passes the request prompt and metadata into AgentWorkflowContext. It deep-copies the configured workflow config for that execution.

Run the workflow

The workflow runs in the current process under an active RolloutContext. Its explicit return value or registered sample source becomes the rollout sample.

Run the grader when applicable

After a successful workflow, the configured grader runs when request.grade is True and the request has a label or metadata. It receives the sample, label, metadata, and artifact directory through GraderContext.

Return the result

An ExecutionOutcome carries the workflow result and optional grader result to the rollout server. Grading remains on the rollout’s critical path: its latency or failure affects the completed result.

Process and Isolation Model

LocalBackend deliberately provides no sandbox boundary:

Workflow and grader code share the server’s Python interpreter, installed packages, environment variables, filesystem, and event loop.
Breakpoints, normal logging, stack traces, and print debugging work directly.
A process crash, blocking call, global-state mutation, or dependency conflict can affect other rollouts in that server.
Tools that modify files or spawn processes are not isolated between executions unless your code creates that isolation.

Use HarborBackend when each rollout needs a task-owned environment or isolated process and filesystem.

Concurrency and Timeouts

LocalBackend uses workflow_config.concurrency.max_concurrent as its in-process execution limit:

from osmosis_ai.rollout import AgentWorkflowConfig, ConcurrencyConfig, LocalBackend

config = AgentWorkflowConfig(
    name="my-workflow",
    concurrency=ConcurrencyConfig(max_concurrent=8),
)

backend = LocalBackend(workflow=MyWorkflow, workflow_config=config)

Configuration	Effective limit
No `workflow_config`	`4` concurrent executions
`max_concurrent=<n>`	At most `<n>` concurrent executions
Config provided with `max_concurrent=None`	No backend concurrency cap

LocalBackend enforces finite agent_timeout_sec and grader_timeout_sec values with asynchronous deadlines. Time spent waiting for an execution slot reduces the workflow budget; grading gets its own independent budget. Omit a timeout to leave that phase unbounded. Deadlines can interrupt cooperatively cancellable asynchronous code. Synchronous code that blocks the event loop, or code that suppresses cancellation, cannot be forcibly stopped in process; the backend reports a timeout when control returns after the deadline. Use an isolated execution environment when you need a hard process boundary.

Grading Rules

The grader is constructed after each successful workflow execution rather than shared across requests. It runs only when all of the following are true:

grader is configured.
The workflow result is successful.
The request contains a label or metadata.
request.grade is True (the default).

The grader must leave a reward on its sample unless it sets remove_sample=True to discard that sample. If grade=True but the grader is missing or neither label nor metadata is supplied, the completed rollout fails even if the workflow succeeded. Set grade=False when you want an ungraded rollout; see RolloutClient.

Artifacts and Persistence

When writable, the backend gives the workflow and grader an artifacts directory under ~/.osmosis/<rollout-id>/artifacts. Failure to create that directory degrades to artifacts_dir=None; it does not fail the rollout by itself. ATIF persistence belongs to create_rollout_server(), not LocalBackend. A harness that calls run_workflow() or execute() directly must persist any trajectory it needs.

Error Categories

LocalBackend converts uncaught workflow and grader exceptions into structured results:

Exception	Category
`TimeoutError`	`TIMEOUT`
`ValueError`, `TypeError`, `AssertionError`	`VALIDATION_ERROR`
Other exceptions	`AGENT_ERROR`

The full traceback is logged by the rollout server process; the result contains the exception message and category.

When to Use LocalBackend

Use LocalBackend when you want:

The shortest development and debugging loop.
One workflow to process changing dataset prompts.
The current Python environment to supply all dependencies.
A lightweight custom evaluation or rollout harness.

Move to Harbor template mode when the prompt-driven workflow is correct but tools or dependencies need a reusable isolated environment. Move to Harbor dataset mode when each task already owns its instruction and verifier.

Get started

Core API

Integrations

Execution

Agent tools

LocalBackend In-Process Execution

Install

Create a Rollout Server

Execution Lifecycle

Process and Isolation Model

Concurrency and Timeouts

Grading Rules

Artifacts and Persistence

Error Categories

When to Use LocalBackend

Next Steps

AgentWorkflow

HarborBackend

​Install

​Create a Rollout Server

​Execution Lifecycle

​Process and Isolation Model

​Concurrency and Timeouts

​Grading Rules

​Artifacts and Persistence

​Error Categories

​When to Use LocalBackend

​Next Steps

AgentWorkflow

HarborBackend

Install

Create a Rollout Server

Execution Lifecycle

Process and Isolation Model

Concurrency and Timeouts

Grading Rules

Artifacts and Persistence

Error Categories

When to Use LocalBackend

Next Steps