Customize profiles

Start with the folders created by oar init. They are ordinary files you can edit and commit with your project. A profile defines lasting behavior; command options supply the input, output, and context for one run.

Where to make a change

code-reviewer/
├── profile.yaml         Tasks and the files each task uses
├── prompt-repository.md Instructions for this task
├── skills/              Reusable review guidance and rubric
├── schemas/review.json   Required shape of the result
├── policy.yaml          Sandbox file and network permissions
├── models.json          Pi model definition and API compatibility
└── settings.json        Pi provider, model, and thinking level

Configure Pi's model and inference

OAR uses the Pi coding agent, so model configuration follows Pi's file formats. For each run, OAR copies the profile's models.json and settings.json into Pi's isolated configuration directory inside the sandbox. Your host Pi installation, login, and ~/.pi/agent settings are not used.

Configuration has two parts:

The packaged profiles use this request path:

Pi → OpenAI-compatible Chat Completions → https://inference.local/v1
   → OpenShell inference route → configured upstream model

Model definition

After oar init ./profiles --model YOUR_MODEL_ID, each profile's models.json contains:

{
  "providers": {
    "openshell": {
      "baseUrl": "https://inference.local/v1",
      "api": "openai-completions",
      "apiKey": "unused",
      "authHeader": true,
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "YOUR_MODEL_ID",
          "reasoning": true
        }
      ]
    }
  }
}

openshell is Pi's provider name within the profile; keep it even when OpenShell routes to a differently named upstream provider. OAR requires exactly one provider named openshell and exactly one model under it.

baseUrl points Pi at OpenShell's sandbox inference endpoint. apiKey: "unused" is a placeholder sent with a bearer authorization header; actual upstream credentials belong in OpenShell's provider configuration.

api: "openai-completions" selects Pi's OpenAI Chat Completions client. It does not require an OpenAI-hosted model, but the routed endpoint must accept that protocol and support the tool calls Pi uses. compat.supportsDeveloperRole: false makes Pi send the system prompt with the system role. Other endpoint differences may require Pi compatibility options, such as compat.supportsReasoningEffort: false for a server that rejects reasoning_effort. Model limits such as contextWindow and maxTokens also belong in models.json. See Pi's custom model reference for field definitions. Any API choice must also work with your OpenShell route.

Model selection and reasoning

The corresponding settings.json contains only these three keys:

{
  "defaultProvider": "openshell",
  "defaultModel": "YOUR_MODEL_ID",
  "defaultThinkingLevel": "high"
}

OAR checks that defaultModel matches the model's id in models.json and passes this provider, model, and thinking level to Pi at launch. Additional Pi settings keys are rejected by OAR.

oar init --thinking off sets defaultThinkingLevel to off and the model's reasoning flag to false. Other levels set reasoning to true; they are minimal, low, medium, high (the default), xhigh, and max. Choose a level supported by your model and endpoint. These are Pi reasoning settings; init does not discover model capabilities or test inference.

When changing models, first configure the route in OpenShell and inspect it with oar doctor using the same gateway and workspace as your run. Update both models.json's model id and settings.json's defaultModel to that model ID, then adjust reasoning, limits, and compatibility for the new model. Run oar validate against the profile and try a task to verify inference; local validation and doctor do not send model requests.

How a task is defined

This is the shape of the packaged code review task, with shorter descriptions:

id: code-reviewer
description: Review a code repository.

sandbox:
  policy: policy.yaml

tasks:
  review-repository:
    required_input: repository
    prompt: prompt-repository.md
    prompt_variables:
      focus:
        description: What deserves special attention.
        default: Review the complete repository.
      context:
        description: Purpose and constraints.
        default: No additional context was provided.
    tools: [read, grep, find, ls, bash]
    skills: [skills/review-code]
    output_schema: schemas/review.json

Add another entry under tasks to define another job in the same profile. Each task chooses its own prompt, variables, tools, skills, extensions, and output schema. Set required_input to document for a file or repository for a directory. Omit it for a task that does not accept --input.

Paths to prompts, skills, extensions, policies, and schemas are relative to the profile directory and must stay inside it. OAR also requires models.json and settings.json, which init supplies.

Put variables in a prompt

Use double braces to insert a value:

Review {{ oar.input_path }}.
Original name: {{ oar.input_name }}.

Focus: {{ focus }}
Context: {{ context }}

There are two sources of values:

The two oar.* values are available only when the task declares required_input. They cannot be overridden. They let the same document prompt work with .md, .txt, and other filenames without hard-coding a path.

Declare each custom variable under prompt_variables in profile.yaml and use it in the prompt. A variable with no default must be provided on the command line. Names start with a lowercase letter and contain lowercase letters, numbers, or underscores, up to 63 characters.

Repeat --prompt-var for multiple values. Values are non-empty strings; there is no separate YAML variables input. Substitution inserts the text once, literally: it does not evaluate expressions, loops, or nested placeholders. OAR rejects unknown names, unused declarations, missing values, repeated CLI assignments, and malformed placeholders before starting a sandbox.

Choose tools and skills

OAR runs Pi, the agent inside the sandbox. A task's tools list selects which tools Pi may use: read, grep, find, ls, bash, edit, and write are built in. A skill is a directory containing a SKILL.md with reusable instructions; list the skills the task needs under skills. Tasks with skills must include read in tools: Pi uses it to expose the skill catalog and let the agent load the selected instructions.

For a custom tool, declare its extension file and tool name, then add the name to the task's tools list. This fragment belongs under a task:

tools: [read, custom_check]
extensions:
  - path: extensions/custom-check.ts
    tools: [custom_check]

The extension file must exist and register that tool through Pi. OAR checks the declarations locally and the registered tools before the first model request. Tool selection controls the agent interface; policy.yaml controls sandbox access, including commands run through bash.

Choose the result format

The result file is what OAR returns to the caller. A task can also modify files or act on external services when its tools, credentials, and sandbox policy allow it. OAR currently downloads only the result file; it does not synchronize code changes back to your machine. Work that must persist needs to be exported or pushed before sandbox cleanup. Removing the sandbox does not undo actions already taken on external services, such as opening a pull request.

The result schema is a JSON file in your profile. Each task names the file through output_schema in profile.yaml. For the included reviewers, oar init copies schemas/review.json into the profile; you can edit it to change the required fields, types, and bounds. OAR supplies the validation machinery.

For a JSON task, OAR uploads a copy of that schema along with its built-in submit_result tool. Tell the agent to finish by calling the tool. Invalid submissions return errors so the agent can correct and resubmit. OAR downloads the result and validates it against the profile's schema before replacing the file at --output.

Omit output_schema to save the agent's final text response instead. The --output option chooses only the destination. OAR still checks that the result is non-empty and within the size limit. The run lifecycle shows how both formats fit into sandbox creation, execution, and cleanup.

Use JSON Schema Draft 2020-12 with inline definitions. References ($ref, $dynamicRef, $recursiveRef) and regex keywords (pattern, patternProperties) are rejected. Use types, enums, required fields, lengths, and numeric bounds. format and custom keywords are annotations, not enforced checks.

Check your changes

oar validate ./profiles/code-reviewer
oar run ./profiles/code-reviewer \
  --task review-repository \
  --input ./my-project \
  --output ./code-review.json \
  --dry-run

validate checks every task and its resources. --dry-run also checks the selected task's input and variables and prints the planned commands. Neither runs the agent. When both succeed, remove --dry-run to try the task.