.sinatrarc.json
Per-repo configuration file schema and examples.
.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 sandbox setup, hooks, and CI behavior for work in that repo. The extensionless .sinatrarc filename is no longer supported: rename it to .sinatrarc.json, remove any retired engine, model or effort keys, and commit the rename on the default branch and any task branches you still use.
Every field is optional. The engine, model and reasoning effort don't come from this file: the presence of engine, agent.model or agent.effort, regardless of its value, is a configuration error. Remove those keys and choose Settings → Models → Your default instead. Sinatra uses your default, then the workspace default, then credential-based selection; see Models.
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:
{
"$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 | not accepted | none | Rejected. Remove this key and choose the engine under Settings → Models → Your default. |
agent
| Field | Type | Default | Description |
|---|---|---|---|
model | not accepted | none | Rejected. Remove this key and choose the model under Settings → Models → Your default. |
effort | not accepted | none | Rejected. Remove this key and choose the effort under Settings → Models → Your default. |
timeout_minutes | integer 1 to 60 | 15 | Reserved — no effect today. The plan sets the time: on Free each agent works up to 60 minutes; on paid plans agents work until they're done, carrying on past a checkpoint every 120 minutes (see Time limits). |
max_turns | integer 1 to 100 | 20 | Reserved — no effect today. Nothing limits how many steps the agent takes. |
See Models for effort ranges per model. agent.model_provider remains deprecated and ignored with a warning; remove it from existing files.
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: agent.timeout_minutes, agent.max_turns, and ci.max_rework. They merge over schema defaults and the committed .sinatrarc.json.
Not overridable: hooks and sandbox. These control code execution and the image shape, so they stay with the committed file the whole team shares.
Engine, model and effort are not per-repository preferences anymore: both repository files and the per-repository override API reject engine, agent.model and agent.effort with a pointer to Settings → Models → Your default. Previously saved per-repository effort overrides are ignored. Pick the engine, model and effort together as your default instead.