.sinatrarc.json

.sinatrarc.json is the supported JSON configuration file, committed to the root of a target repo. Sinatra reads it from GitHub, normally from the repository's default branch. It controls the engine, model, sandbox setup, and CI behavior for work in that repo. The extensionless .sinatrarc filename is no longer supported: rename it to .sinatrarc.json without changing its contents, and commit the rename on the default branch and any task branches you still use.

Every field is optional. The tables below give schema defaults; workspace defaults and credential-based model selection, explicit repository settings, and personal overrides determine the effective engine and model.

The canonical JSON Schema is served at https://api.sinatra.dev/sinatrarc/schema. Set it as $schema for editor autocomplete.

Example

This example sets up a pnpm repository without pinning a model, so it can use your workspace default or available credentials:

{
  "$schema": "https://api.sinatra.dev/sinatrarc/schema",
  "hooks": {
    "test_command": "pnpm test"
  },
  "sandbox": {
    "env": { "NODE_ENV": "development" }
  },
  "ci": {
    "max_rework": 2
  }
}

Top level

Field	Type	Default	Description
`$schema`	string	none	URL of the JSON Schema, for editor autocomplete.
`engine`	`claude-code` \| `oh-my-pi`	`oh-my-pi`	The agent harness. Explicitly setting this disables credential-based default selection. See Models.

`agent`

Field	Type	Default	Description
`model`	enum	per engine	The model to run. Must belong to the chosen engine. Defaults to `opus-5-5` on `claude-code` and `anthropic/claude-opus-5-5` on `oh-my-pi`.
`effort`	`low` \| `medium` \| `high` \| `xhigh` \| `max`	`medium`	How hard the model thinks. Clamped to the levels the model supports.
`timeout_minutes`	integer 1 to 60	`15`	Reserved — no effect today. Each agent run has a 120-minute runtime cap; on Free each request stops at 60 minutes (see Billing). A task can span many runs.
`max_turns`	integer 1 to 100	`20`	Reserved — no effect today. The agent is not turn-limited.

See Models for model names, effort ranges, and required credentials. agent.model_provider is deprecated and ignored, with a warning; remove it from existing files. To select a Codex model explicitly, use engine: oh-my-pi with an openai-codex/* model.

`hooks`

Shell commands run inside the sandbox. All are optional.

Field	Type	When it runs
`before_run`	string	Reserved — no effect today. Describe setup in your README or AGENTS.md instead.
`after_run`	string	Reserved — no effect today.
`test_command`	string	After the implementation agent finishes, usually with a draft PR already open. Sinatra re-runs the agent to fix failures up to twice; if tests still fail, it reports the failure and continues. This does not prevent the PR from being marked ready.

The two test-fix retries are separate from ci.max_rework, which governs GitHub CI failures. Describe setup in your README or AGENTS.md, and combine checks in test_command if you need more than one. before_run and after_run do not execute.

`sandbox`

Field	Type	Default	Description
`snapshot_name`	string	none	An existing snapshot available to Sinatra's sandbox provider. This is a snapshot name, not an arbitrary Docker image or registry URL. Omit it to use the platform-selected snapshot.
`env`	object	none	Plaintext environment variables from the committed file. Use repository secrets for credentials.
`setup_commands.pre_clone`	string[]	none	Commands run when the sandbox is created, if the repository is known by then.
`setup_commands.post_clone`	string[]	none	No effect today. The agent clones the repository itself and reads these commands as setup hints.
`clone_strategy`	`full` \| `blobless`	`full`	No effect today: the agent clones the repository itself. `blobless` was a `--filter=blob:none` clone for large repositories.
`sync_with_base`	boolean	`true`	No effect today: Sinatra no longer prepares the checkout, so it doesn't probe the working branch against the default branch.

Per-repository auto-snapshots are retired. Use sandbox.snapshot_name to select an existing compatible snapshot. For a custom snapshot, contact us about registering a compatible image before setting snapshot_name. Without an explicit snapshot, workspaces outside the repository-environments rollout use sinatra-agent-base; enabled workspaces use the managed selection described in Sandboxes.

Setup commands run when the repository is prepared in a sandbox, not before every follow-up prompt. Changes to setup commands do not retroactively reinstall dependencies in a retained sandbox.

`ci`

Field	Type	Default	Description
`max_rework`	integer 0 to 10	`2`	How many automatic CI fixes Sinatra runs in a row, with no message from a person, before it stops and says so on the PR. A person's message resets the count. `0` turns automatic CI fixes off.

Retired phase settings

The planning and brainstorm blocks are retired. Existing repository files and personal overrides can still contain them; current workers ignore these keys with warnings. Remove them when you next edit your configuration.

Ask the agent questions or for a plan in the conversation, and it answers in an ordinary reply. There is no phase toggle and no approval step.

Per-user overrides

A teammate can override some of the repo's .sinatrarc.json for their own runs from Repos → repository, without changing the committed file. Members, admins, and owners can each manage their own preferences. Overrides are selected for the person triggering the iteration, including follow-up feedback.

Overridable fields: engine, agent.model, agent.effort, agent.timeout_minutes, agent.max_turns, and ci.max_rework.

Not overridable: hooks and sandbox. These control code execution and the image shape, so they stay with the committed file the whole team shares.

Personal overrides take priority over an explicit repository engine/model pairing, then the workspace default. An explicit repository engine or model keeps its compatible repository pairing. Other fields merge schema defaults, the committed .sinatrarc.json, then the user's override.

Sinatra selects a credential-based default only when no layer explicitly selects an engine or model. A saved workspace default is an explicit preference, not a credential grant. An incompatible engine/model combination or a missing credential can prevent admission; check the validation shown on the repository page.

On this page