Skip to main content
A runtime mode is the contract for a Dari agent. It answers one important question: who owns the agent loop? If Dari owns the loop, use the managed Pi runtime. If your code owns the loop, use a custom runtime server. This is the main design choice for every agent bundle.

​
Choose A Runtime Mode

Managed Pi Runtime

Use this when you want Dari to call the model, run tools, save checkpoints, and manage the standard coding-agent loop. Today this is harness: pi.

Custom Runtime Server

Use this when your runtime code calls the model or SDK and decides what happens on each turn. Today this is kind: customRuntimeServer.

​
The Difference

QuestionManaged Pi RuntimeCustom Runtime Server
Who calls the model?DariYour runtime code
Is llm required?YesNo, unless your runtime wants to use it as configuration
Who decides when to use tools?Dari’s managed runtimeYour runtime code or SDK
Who emits assistant output?Dari’s managed runtimeYour runtime response
Best forStandard coding agentsExisting SDKs, custom planners, provider-specific loops
Current manifest kindpicustomRuntimeServer
The managed Pi runtime is configuration-first. You provide prompts, a model, tools, skills, extensions, and sandbox setup. Dari advances the runtime for each session message. A custom runtime server is code-first. Dari provides the session input and previous state. Your runtime runs whatever loop it needs and returns text, state, or explicit events.

​
Managed Pi Runtime Example

dari.yml
name: my-agent
harness: pi
instructions:
  system: prompts/system.md
llm:
  model: openai/gpt-5.5
built_in_tools:
  - read
  - bash
  - edit
  - write
Use this path when you want a Dari coding agent and do not need to write your own runtime process. See Managed Pi Runtime or the Pi Harness Example.

​
Custom Runtime Server Example

dari.yml
name: claude-sdk-runtime
harness:
  kind: customRuntimeServer
  protocol: dari-runtime-v1
  customRuntimeServer:
    command: sh -c 'uvicorn custom_runtime_server:app --host 0.0.0.0 --port "${PORT:-8787}"'
    port: 8787
instructions:
  system: prompts/system.md
sandbox:
  provider: e2b
  internet_access: true
  secrets:
    - ANTHROPIC_API_KEY
Use this path when your agent needs to bring its own SDK or loop. For the common case, the runtime returns assistant text and state. Omit state to keep the previous state unchanged; return "state": null to clear it. 
{
  "text": "Done — I inspected the project.",
  "state": {"thread_id": "abc123"}
}
See Custom Runtime Server or the Claude Agent SDK Example.

​
Rule Of Thumb

Start with the managed Pi runtime. Move to a custom runtime server only when the managed loop is the wrong abstraction: for example, when you need Claude Agent SDK, a provider-specific memory model, a custom planner, or an existing agent framework.