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():
Create a Rollout Server
Multiple classes can exist in the imported module. These arguments select the workflow, grader, and configs explicitly.
Execution Lifecycle
1
Create the workflow context
The backend passes the request prompt and metadata into
AgentWorkflowContext. It deep-copies the configured workflow config for that execution.2
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.3
Run the grader when applicable
After a successful workflow, the configured grader runs when the request has a label or metadata. It receives the sample, label, metadata, and artifact directory through
GraderContext.4
Return the result
Workflow and grader results are returned separately 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.
Concurrency and Timeouts
LocalBackend uses workflow_config.concurrency.max_concurrent as its in-process execution limit:
LocalBackend does not enforce agent_timeout_sec or grader_timeout_sec itself. Those request fields do not interrupt in-process code. A TimeoutError raised by your code is categorized as a timeout, but a custom harness must enforce any hard deadline it requires outside the backend.
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:graderis configured.- The workflow result is successful.
- The request contains a label or metadata.
- The caller requested a grader completion result, as
create_rollout_server()does for graded rollouts.
remove_sample=True to discard that sample. If no grader is configured, the workflow result can still succeed with an ungraded sample.
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:
The full traceback is logged by the rollout server process; the result contains the exception message and category.
When to Use LocalBackend
UseLocalBackend 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.
Next Steps
AgentWorkflow
Implement the agent behavior that LocalBackend executes.
HarborBackend
Add per-trial task environments or reuse existing Harbor tasks.