Skip to main content

Configuration

Agents​

An agent is a directory under workflows/auto_swe/src/auto_swe/agents/<name>/ that contains agent.yaml and the files it names, such as the system prompt and the prompt template. agent.yaml holds:

  • the agent's defaults: the model, prompts, sandbox, tools and credentials of every step;
  • its triggers: which work items start an agent run, and at which step;
  • its steps: what each step asks for, what it changes of the defaults, and which step follows each outcome.

Agents describes how a session runs an agent's steps, and the reasons for the file's design. The worker loads every agent in an activity for each work item. If any agent is invalid, the loader rejects the whole set and names each problem.

agents/agent.example.yaml lists every key the Agent model accepts, with a comment on each and the default of each optional key. A test validates that file against Agent. For complete agents, see agents/pull-request/agent.yaml and agents/implement/agent.yaml. The sections below describe what the keys do.

The paths in instructions, prompt, skills_prompt, memory_prompt and a step's instructions are relative to the agent's directory. An agent names a file in agents/_shared/ by a relative path, such as ../_shared/review-rules.md.

sandbox: null runs the agent without a sandbox. The agent then has no checkout, no repository context and no execute tool.

model is anthropic:<name>, openai:<name> or bedrock:<Bedrock model ID>. The part before the first colon names the provider, and the rest is the provider's name for the model. The same model can have both an anthropic: and a bedrock: name, such as anthropic:claude-opus-5-5 and bedrock:us.anthropic.claude-opus-5-5.

The bundled agents name us. inference profiles. Bedrock routes a call through a us. profile to us-east-1, us-east-2 or us-west-2. It routes a call through a global. profile to any commercial Region, including Regions outside the US.

The model must have a price in auto_swe/harness/model_prices.json. The loader rejects an agent when its model or a step's model has another provider or no price. The session estimates each step run's cost from those prices; see Tokens and cost. To price a model, run uv run --directory workflows/auto_swe python scripts/update_model_prices.py --add <model>. LiteLLM's price table names a Bedrock model by its Bedrock ID, so --add bedrock:openai.gpt-oss-120b-1:0 prices openai.gpt-oss-120b-1:0. The worker's role may call the bedrock: models in model_prices.json; see Bedrock.

The loader records a model_profile for the agent's model and for each step's model, from the model's profile in its LangChain provider package. Deep Agents reads it in the workflow:

  • Deep Agents replaces content that the model does not accept, such as an image that read_file returns to a model without image input, with a text notice.
  • A model with a window smaller than 200,000 tokens has its max_input_tokens. Deep Agents summarizes its conversation at 85% of the window and keeps 10% of the window.
  • Without a window in the profile, Deep Agents summarizes the conversation at 170,000 tokens and keeps the last 6 messages.

The agent loop turns off Deep Agents' truncation of the write_file and edit_file arguments in older messages. A truncated argument changes a message that comes before Claude's later thinking blocks. Anthropic's API then rejects the request with the error "The block is bound to a different conversation".

The loader rejects a model whose profile has no max_input_tokens, and a bedrock: model whose profile has no max_output_tokens. For a Converse model, the profile is the one ChatBedrockConverse reads: the profile of the model's ID without its inference profile prefix.

Deep Agents saves a tool result longer than 80,000 characters to large_tool_results/<tool call id> under the sandbox's SandboxSettings.artifacts_dir. This applies to execute and to the registered, script and MCP tools that an agent adds, not to Deep Agents' file tools such as read_file and grep. In place of the result, the model receives the file's path and the result's first and last 5 lines, each truncated to 1,000 characters. Deep Agents saves the messages it summarizes to conversation_history/ under the same directory.

Bedrock models​

The worker calls a bedrock: model with the worker's AWS credentials, through one of two APIs:

  • The worker calls a Claude model through Anthropic's Messages API on Bedrock (ChatAnthropicBedrock). The model therefore has the same prompt cache, model_settings and tool_choice as an anthropic: model.
  • The worker calls any other model through Bedrock's Converse API (ChatBedrockConverse). Of these models, Bedrock caches the prompts of Amazon Nova models only. The last call of an agent loop, the third call past its model-call limit, has no tools, and ChatBedrockConverse sends the conversation's tool calls and results as text.

Both chat models take max_tokens from the model's profile: its max_output_tokens, at most the part of the model's window that the conversation leaves free when Deep Agents summarizes it, less 5% of the window for the error of Deep Agents' token estimate. Some Bedrock models count a request's max_tokens against the window. For openai.gpt-oss-120b-1:0, with a window of 131,072 tokens, that is 13,108 tokens. max_tokens is also at most 32,000, because Bedrock reserves a request's max_tokens against the model's tokens-per-minute quota when the request starts. A max_tokens model setting replaces this limit. The Claude steps of the implement, pull-request and hook-probe agents set it to 128,000, the limit of Claude Opus 5.5 and Sonnet 5.5 through Anthropic's API, so that a call at effort: high can spend most of its output on thinking and still return a tool call. Each of their requests reserves 128,000 tokens of the model's quota.

The worker builds a Converse chat model once per model, because building one builds two boto3 clients. It builds a Claude chat model for each call, because its async client is bound to the event loop it was built in, and each Lambda invocation runs a new one.

botocore's errors have no status_code for the model activity to read, so the worker turns a failed Converse call into a Temporal error that says whether to retry it. Temporal retries the call after:

  • a throttled request;
  • an HTTP 408, 429 or 5xx;
  • one of Bedrock's model errors, such as ModelErrorException.

Another client error fails the call at once, as do a missing AWS region or credentials and a TypeError, which a keyword argument the chat model does not take raises. A Converse model call that raises ValueError fails after three attempts. ChatBedrockConverse raises it both for a request it cannot build, which every attempt repeats, and for a reply it cannot parse, which a new reply can avoid.

Bedrock returns the encrypted reasoning of some Converse models, such as GPT-6.1 Sol, as bytes. The model activity returns its reply to the workflow in the form that LangChain's dumpd writes. dumpd writes bytes as a placeholder, and load raises on that placeholder. The worker's Converse chat model therefore holds the encrypted reasoning as base64 text in its reply. It decodes the text to bytes again when it sends the conversation back to Bedrock.

ChatBedrockConverse has no async API, so a Converse call runs in a thread, which the model activity's timeout does not stop. The call's socket timeout, 5 minutes, ends it. A session's model_timeout longer than 5 minutes therefore does not give a Converse call longer.

A local worker cannot read the AWS credentials of aws login, because reading them needs botocore[crt]. Export them with aws configure export-credentials --format env.

model_settings are keyword arguments that the worker binds to the chat model on every call, such as effort: high for an Anthropic model, or reasoning: {effort: medium} for an OpenAI model. A reasoning setting sends an OpenAI model's calls to the Responses API, which a GPT-5.6 model needs to call tools with reasoning. The pull-request agent sets effort: medium. For a Converse model, the loader rejects a setting that a Converse call does not take: it takes reasoning_effort, additional_model_request_fields and the request fields of Bedrock's Converse API. The loader also rejects a reasoning_effort level that the model profile's reasoning_effort_levels does not list. ChatBedrockConverse raises ValueError on such a level, and ignores reasoning_effort for a model whose profile lists no levels.

Egress​

The sandbox reaches only the hosts in its egress allowlist, which the session sets when it creates the sandbox. The allowlist has:

  • the hosts in sandbox.egress;
  • the hosts that the repository's .auto-swe/config.yaml adds under egress, each of which must be in sandbox.approved_repo_egress;
  • the hosts of each credential's Secrets, which the session adds. The table of credentials lists them.

An entry in sandbox.egress is one of:

  • a lowercase fully qualified domain name, such as pypi.org, without a scheme, port or path;
  • *. followed by such a name, such as *.example.com, which allows example.com and every subdomain of it.

The loader rejects any other entry. With no hosts in either list, the sandbox has no outbound access. Daytona accepts at most 100 entries in an allowlist.

sandbox.approved_repo_egress lists the hosts that a repository may add. Each entry is a fully qualified domain name, without the *. prefix. The loader rejects the list for an agent with egress: all. A host enters the list only with a change to auto_swe, so each new destination is reviewed once, centrally.

In sandbox.egress, list every host that one of these reaches, unless a credential adds it:

  • the setup script;
  • the repository's setup script, repo_context.base_setup_script;
  • the prepare script;
  • the repository's hooks;
  • the agent's own commands.

The packaged scripts and this repository's tools reach these hosts:

UseHosts
setup.sh, and scie-pants' downloads of the Pants PEX and its Pythonrelease-assets.githubusercontent.com, the host that github.com redirects release downloads to
Pants' downloads of pex, ruff and buildifierrelease-assets.githubusercontent.com
Pants' downloads of the lockfiles' distributionspypi.org, files.pythonhosted.org
Tests that start temporalio's WorkflowEnvironment, which downloads the Temporal test servertemporal.download
setup.sh's install of corepack, corepack's downloads of pnpm, and npm's and pnpm's package downloadsregistry.npmjs.org
Plugin and marketplace fetchesgithub.com, which the github credential adds

With an allowlist, Daytona sends the sandbox's HTTPS requests through a proxy. For each host, the proxy presents a certificate signed by the proxy's own CA. Daytona sets SSL_CERT_FILE, REQUESTS_CA_BUNDLE and CURL_CA_BUNDLE to the path of that CA's certificate file. A client that reads none of these variables fails to connect. Pants reads none of them, so setup.sh sets Pants' ca_certs_path option in ~/.pants.rc to that path. Daytona also sets NODE_EXTRA_CA_CERTS, which Node, npm and corepack read.

egress: all gives the sandbox full internet access, including Daytona's essential services. The sandbox then has no allowlist, so the session adds no credential hosts. Use it for an agent whose hosts cannot be listed in advance, or whose allowlist would need more than 100 entries. Security model describes the risk.

Settings a repository can change​

settings holds the defaults of the settings the agent's registered tools read. A tool declares its settings with ToolSpec.settings_model. The loader rejects:

  • a setting that none of the agent's tools reads;
  • a missing setting;
  • a setting of the wrong type.

A repository overrides them in .auto-swe/config.yaml, under the agent's name:

pull-request:
max_nits: 2
skip_paths: ["**/*.lock", "src/generated/**"]

The session reads the file from the pull request's base branch, so a pull request cannot change the settings it runs under. A change to the file applies once it merges. The repository can:

  • change the keys under settings, and set a setting that the agent's tools read but the agent leaves to its default;
  • add file names to repo_context.path_guidance with a path_guidance list;
  • add hosts from sandbox.approved_repo_egress to sandbox.egress with an egress list.
pull-request:
path_guidance: [CONTRIBUTING.md, docs/REVIEW-NOTES.md]
egress: [nexus.example.com]

The session appends the names to the agent's repo_context.path_guidance. If a name is an absolute path or contains .., the session ignores the whole list.

The session adds the hosts to the agent's sandbox.egress, never replacing it. Each entry must be one of the agent's sandbox.approved_repo_egress, so a repository cannot list all or a *. entry. If one entry is not approved, the session ignores the whole list. Security model describes what each added host allows.

Everything else in agent.yaml, such as the model and max_model_calls, stays fixed. The session ignores an unknown key and a value of the wrong type, and keeps the default. It passes each problem to the tools in ToolRequest.step_run.settings_problems. github_post_review lists the problems in the review.

SettingRead byMeaning
max_nitsgithub_post_reviewNits posted per review; the rest are counted in the body
max_pre_existinggithub_post_reviewPre-existing findings posted per review
max_considerationsgithub_post_reviewConsiderations posted per review, under "Worth a look"
skip_pathsgithub_post_reviewGlob patterns; a finding or consideration on a matching path is not posted
max_changed_filesgithub_pushThe most files the commits of one push may change

A step can add a tool that the agent's tools does not list. The loader checks the agent's settings against the tools of the agent and of every agent step. It checks a step's settings against the step's own tools.

Triggers​

triggers lists the work items that start the agent. A trigger has these fields:

FieldDefaultMeaning
typerequiredThe work item's type. The loader rejects a type that has no context type.
eventany eventThe work item's event
actionsany actionThe actions that match the work item's action
whenno conditionsConditions on top-level payload fields. A scalar field must equal the value, and a list field must contain it.
steprequiredThe step the agent run starts at
requestthe step'sReplaces the step's request in the step run that this trigger starts. The loader rejects it on a trigger of an activity step or a rubric step.

The first trigger a work item matches starts the agent run, so list a narrower trigger, such as when: {mentioned: true, draft: false}, before a broader one. Comments that address the agents lists the payload fields of a GitHub comment that a when can name.

Every step of an agent run works on the work-item type that its trigger matched. The loader therefore checks each step's tools, activity and request against every work-item type of the agent's triggers.

Steps​

steps holds the agent's steps, by name. A step's name has lowercase letters, digits and hyphens, starts with a letter, and is not end. A step is one of:

  • an agent step, which runs an agent loop with the agent's defaults and the changes the step sets;
  • an activity step, which sets activity and runs that activity instead of an agent loop. The activity is a key of auto_swe.agents.registry.STEP_ACTIVITIES;
  • a rubric step, which sets rubric and state, and asks TypeSafe's Jev the rubric's questions instead of running an agent loop. See Rubric steps.

An agent step may set these fields:

FieldDefaultHow it combines with the agent's fields
request""What the step asks for, a template of the context type's fields. It fills the prompt's $request. A trigger's request replaces it.
instructionsnoneFiles appended to the agent's instructions in the system prompt
toolsnoneAdded to the agent's tools. The loader rejects a tool that both list.
model, model_settings, max_model_calls, max_minutesthe agent'sEach replaces the agent's
settingsnoneReplaces the agent's settings that it names. The repository's .auto-swe/config.yaml overrides them in turn.
credentialsthe agent'sReplaces the agent's credentials. Each grant must be the agent's grant or its read-only grant.
conversationnoneThe name of the agent's conversation that the step continues and saves. See Conversations.
prepare_scriptthe agent'sReplaces the agent's sandbox.prepare_script in this step. The step runs in the same sandbox as the agent's other steps.

An agent step uses the agent's other fields unchanged:

  • prompt, skills_prompt and memory_prompt;
  • read_limit;
  • sandbox apart from prepare_script, repo_context and plugin_pins;
  • allow_sandbox_writes and mcp_servers.

A step can therefore give a tool that writes, such as github_push, only to the step runs whose request asks for that write. The pull-request agent's fix and review-and-fix steps add github_push and fix.md. The loader checks each step as it runs the agent, with the same checks as the agent's own fields.

Every step may set these fields:

FieldDefaultMeaning
on{}The next step for each outcome, or end
max_rounds, after_max_roundsno limitHow many times one agent run may enter the step, and the step it enters instead after that, or end. They are set together.

An activity step sets only activity, on, max_rounds and after_max_rounds.

A step run ends with an outcome. A registered tool or a step activity that returns outcomes declares them in its spec. A rubric step returns passed, rejected or unsettled. The session itself sets failed, over_budget and no_outcome. Agents describes where each outcome comes from. The loader rejects an agent in which:

  • a step's on leaves out an outcome that the step's tool or activity declares;
  • a step's on maps an outcome that the step cannot return;
  • a step has more than one tool that returns outcomes;
  • a trigger, an on or an after_max_rounds names a step that does not exist;
  • no trigger leads to a step, directly or through other steps.

failed, over_budget and no_outcome end the agent run unless the step's on maps them.

Rubric steps​

A rubric step asks Jev a list of yes-or-no questions about fields of the step's context, in one System One request. Code turns the answers into the step's outcome. The step runs no agent loop and uses no sandbox. It sets these fields, and only on, max_rounds and after_max_rounds besides:

FieldMeaning
rubricA YAML file, relative to the agent's directory, that lists the questions
stateThe fields of the step's context that Jev reads, by name, such as [title, plan]. Each must be a field of the context type of every trigger's work-item type, or last_reply or rubric_explanation.
steps:
plan-rubric:
rubric: plan-rubric.yaml
state: [title, plan]
on:
passed: implement
rejected: revise
unsettled: end

The rubric file has the Jev model and its criteria. Each criterion is one Noul, the TypeSafe question whose answer is the probability that a statement is true:

model: jev-1.14.0
criteria:
- id: names_files
question: Does the plan name the files it changes?
yes: The plan lists each file it changes or adds.
no: The plan names no file, or names only a directory.
- id: one_pull_request
question: Is the plan small enough for one pull request?
no:
what: The plan splits the work into several pull requests.
examples:
- Part 1 adds the model. Part 2, after it merges, adds the endpoint.
required: false
FieldDefaultMeaning
modelrequiredThe Jev model. typesafe:<model> needs a price in auto_swe/harness/model_prices.json.
criteria[].idrequiredThe Noul's key in the request. Lowercase letters, digits and underscores, starting with a letter, and unique in the rubric.
criteria[].questionrequiredThe Noul's instructions. Write it so that yes means the criterion is met.
criteria[].yes, criteria[].nononeWhat a yes and a no mean. They are sent as the Noul's true and false criteria. Each is a string, or an object with what and an optional list of examples. An object is sent to Jev as JSON.
criteria[].requiredtrueWhether the criterion decides the outcome. A rubric needs at least one required criterion.

A probability of 0.7 or more counts as yes, and one of 0.3 or less counts as no. A probability between them is unsettled. The step's outcome is:

  • rejected when a required criterion is no;
  • unsettled when no required criterion is no and one is unsettled;
  • passed when every required criterion is yes.

The step's explanation lists each criterion, required or optional, that Jev did not answer yes, with its answer and probability. Under a criterion answered no, it repeats the criterion's no text, or the what of its no object. The explanation fills $rubric_explanation in the agent run's later steps. The outcome's data holds it as rubric_explanation, so a later activity step reads it from the work item's payload. The step_finished event counts the required criteria by answer.

The session loads the step's context as it does for an agent step, then runs the jev_rubric activity with the rubric and the state fields. As for an agent step, the session checks the run budget before and after the context loads. When the session is over a limit, the step ends with the over_budget outcome and does not ask Jev. The Jev request's tokens count toward the session's usage and cost. A context that skips the work item ends the agent run.

Conversations​

The session keeps each agent's named conversations, by <agent>/<conversation>, and passes them to its next run when it continues as new. A step with conversation: <name> starts its agent loop from the agent's conversation of that name in this session, when the session has one. When the step run ends without failing, the session saves the step run's conversation under that name. Every model call of the step run therefore also sends the messages of the earlier step runs that saved the conversation.

Several steps of one agent can name the same conversation, and the steps of a later agent run continue it. Two agents never share a conversation, even under the same name.

A step without conversation starts its agent loop from its prompt alone, and the session does not keep the step run's conversation. The prompt then has to give the step run what it needs from earlier step runs. The pull-request agent's steps set no conversation, and read the pull request's earlier comments from the context field $conversation.

The prompt template​

The file prompt names is a string.Template. Every agent step of the agent uses it. Its $name placeholders are substituted with:

  • the context type's fields;
  • $prepare_output, the tail of the prepare script's output;
  • $context_files, the sandbox path of each file the context loaded, such as an issue's attachments, one per line, or None.;
  • $request, the step's request, or the request of the trigger that started the agent run at that step;
  • $last_reply, the final reply of the agent run's previous agent step, empty in the agent run's first agent step. A step that sets no conversation learns from $last_reply what the previous agent step did;
  • $rubric_explanation, the explanation of the agent run's latest rubric step, empty until a rubric step runs.

$request is itself a template of the context type's fields, $last_reply and $rubric_explanation. It states what the step asks for, such as a review or an answer, and which tool to answer with. The loader rejects a placeholder in the prompt template or in a request that the context type of one of the agent's triggers does not provide. The context type of github.pull_request provides:

  • number, title, body, author, head_ref, base_ref, labels
  • changed_files, additions, deletions
  • head_sha, the pull request's head commit. The checkout is at this commit.
  • merge_base, the pull request's merge base. A prompt can have the agent read the change with git diff $merge_base HEAD.
  • sender, who caused the event, and label, the label a labeled action added
  • comment_id, comment_author, comment_body, comment_path, for a comment event
  • check_name, check_conclusion, for a check event
  • linked_issues, the issues the pull request closes, each with its title and its body up to 2,000 characters
  • conversation, the pull request's reviews, review threads and comments, oldest first, each body up to 2,000 characters. The App's own reviews and comments are marked (this agent). A resolved review thread is marked (resolved). The review thread of the comment that started the run is marked (you were asked in this thread). When the entries total more than 30,000 characters, the oldest are left out, except that thread and the App's latest review

Tools​

Deep Agents gives every agent its file tools, write_todos and, with a sandbox, execute. Its task tool is withheld; Security model gives the reason. An agent adds more tools; to the model, every one is a tool it can call:

  • Registered tools, entries in tools that give a name. Each runs an activity on the worker that acts on the work item's subject. A tool never writes to a target the model names. A tool that reads may read what the model names within the subject, as dagster_run_events reads any run of the failure's Dagster+ deployment. No tool writes in a dry run. A tool can set how many times the harness runs it per step run. The loader rejects a name that is not a key of auto_swe.tools.registry.TOOLS, and a tool that cannot act on a work-item type the agent's triggers name. A tool whose spec declares outcomes ends its step with one of them; see Steps. The GitHub tools:

    ToolWritesPer step runIn a dry run
    github_post_commentA comment on the pull request, with 👍 and 👎 reactionsOnceNot run
    github_post_reviewOne review. A finding or consideration whose lines are in one hunk of the diff becomes an inline comment, unless the finding is pre-existing. The tool adds 👍 and 👎 reactions to each inline comment. Every other finding or consideration goes in the review's body. When the step run sets fix_summary, the review opens with a 🔧 Review and fix line. The review marks each item whose status is fixed or needs_choice. The same review holds the replies in earlier review threads, each with 👍 and 👎. A reply without a body only resolves its thread. The tool then resolves the threads of fixed items and each thread whose reply sets resolveOnceRenders the review and its replies and returns them, posting nothing
    github_reply_in_threadA reply in the review thread the step run started from, with 👍 and 👎 reactionsOnceReturns the reply, posting nothing
    github_post_fix_reportOne review that answers the comment that asked for a fix, under a 🔧 Fix heading. The answer is a reply in the comment's review thread, or the review's body when the comment is in the pull request's conversation. Replies in other review threads go in the same review, each with 👍 and 👎. A reply without a body only resolves its thread. The tool then resolves each thread whose reply sets resolve, and the comment's own thread when resolve_asked_thread is setOnceReturns the answer and the replies, posting and resolving nothing
    github_pushThe commits the agent made in the checkout after the commit it checked out, recreated by the App on the work item's branch; see Pushing a fix. It refuses changes that are not committed, and checks each commit's message. For a pull request, the branch is its head branch. For a linear.issue, it is auto-swe/<identifier>, with the identifier in lowercase. An agent run's first push creates the branch, or replaces the commits an earlier agent run on the issue pushed there. It refuses to replace a branch that has a commit the App did not commit. Its outcome is pushed, with the branch and commit, and for a linear.issue, the base_commitOnceLists each commit's message and files, pushing nothing and returning no outcome

    The Linear tools act on a linear.issue work item's issue:

    ToolWritesPer step runIn a dry run
    linear_post_commentA comment on the issueOnceNot run

    github_push and github_open_pull_request act on a linear.issue's branch in the work item's repository. They read the payload's identifier, branch, base_commit and review, and the checkout's commit. They read no field specific to the system the work item came from:

    ToolWritesPer step runIn a dry run
    github_open_pull_requestA draft pull request from the branch to main, with the pr-reading-guide skill's reading guide as its body. The body ends with the agent run's estimated cost and its tokens by model. A second call updates the open pull request. Its outcome is opened, with the pull_request_urlOnceReturns the title and body, opening nothing and returning no outcome

    submit_review writes nothing and acts on a github.pull_request or a linear.issue. It takes the arguments of github_post_review without fix_summary and replies. Its outcome is findings while an important finding is open, with the open important findings to fix. Otherwise its outcome is passed. Both have the review's findings, fixed and open, as review. It runs once per step run, and runs in a dry run as it does outside one.

  • Script tools, entries in tools that give a script. Each runs a script from the checkout in the sandbox, with the arguments the model passes. A script tool needs a sandbox with a checkout, and its name must differ from every other tool's name.

  • MCP tools, the tools mcp_servers allows. The worker sends each call of an MCP tool to its server. MCP tools describes the field and how a call runs.

Credentials​

credentials lists what the sandbox's commands can reach, by credential provider. Each credential is a Daytona Secret: the sandbox holds a placeholder, and Daytona puts the value into requests to the provider's hosts. Security model describes how.

KeyValueThe sandbox gets
githubGitHub App permissions, each read or write: actions, checks, contents, issues, metadata, pull_requests, statusesGH_TOKEN for gh and the REST API, and git's Authorization header in the checkout, for the work item's repository
linearread or writeLINEAR_API_KEY, which holds the whole Authorization header value Bearer <token>. The token is from the Linear OAuth app for that access level
nessiereadNESSIE_TOKEN, and NESSIE_URI and NESSIE_AUTH=token for ai_core.nessie.load_nessie_catalog
dagsterread or writeDAGSTER_CLOUD_API_TOKEN, DAGSTER_CLOUD_ORGANIZATION and DAGSTER_CLOUD_URL for ai_dagster_api.credentials.load_credentials. The token is the access level's Dagster+ API token

The loader rejects:

  • a key that is not in auto_swe.credentials.registry.PROVIDERS;
  • a value the provider does not accept;
  • credentials without a sandbox;
  • a checkout without a github credential that has contents;
  • a credential that grants write access, unless the agent sets allow_sandbox_writes: true.

A write to the work item's subject belongs in a registered tool, which writes there and nowhere else. allow_sandbox_writes is for a write that needs the sandbox, such as a push. A dry run gets read-only credentials.

Step runs share a sandbox only when they have the same:

  • snapshot;
  • credentials;
  • egress.

A step whose credentials differ from its agent's therefore runs in a different sandbox from a step with the agent's credentials.

Repository context​

A step run with a checkout loads the repository's own Claude Code configuration, found by convention:

FoundLoaded as
CLAUDE.md, .claude/rules/*.md, and the files they import with @path, up to four hopsInstructions, after the system prompt
Each file that repo_context.path_guidance names, in the directory of each changed file and in its parents. Only the 50 shallowest of these directories are searchedInstructions, after the system prompt
.claude/skills/*/SKILL.mdSkills
enabledPlugins in .claude/settings.jsonThe plugins' skills
PreToolUse and PostToolUse command hooks in .claude/settings.jsonHooks, run around write_file, edit_file, execute, read_file, glob and grep as Claude Code runs them around Write, Edit, Bash, Read, Glob and Grep

An invalid skill fails the step run. An agent that sets repo_context.invalid_skills: skip runs without the invalid skill instead, and the worker log names the skill. An enabled plugin that cannot be resolved fails the step run. The step run skips each of the following and loads the rest:

  • a settings file that is not a JSON object;
  • a value of the wrong type in the settings file;
  • an invalid hook.

A hook matcher that is * or empty matches every tool, as in Claude Code. A hook's command is a shell command, as in Claude Code. Bash runs it in the checkout, with the tool call's JSON on stdin and CLAUDE_PROJECT_DIR set to the checkout. When the command is a script path, the script must be executable. History holds the commands and file reads that locate the repository context, and the resolve_plugins result with each plugin's commit. The list of items the step run skipped is not recorded.

repo_context changes the convention for one agent. Its keys are under repo_context in agents/agent.example.yaml: include and exclude lists of instruction files, skills, plugins and hooks, skills.only, marketplaces, base_instructions and base_setup_script.

skills.only names the only skills the agent gets, from .claude/skills/, the skills.include directories or the enabled plugins. An agent that sets it does not get a skill added to the repository later. The worker log lists the skills that skills.only leaves out. An agent cannot set both only and exclude. A name in only that matches no skill fails the step run, as an invalid skill does. With repo_context.invalid_skills: skip, the agent runs without the missing skill, and the worker log names it.

base_instructions lists files that the session reads from the pull request's base branch, not from the checkout. Each file found is appended to the system prompt, after the agent's instructions, in the order listed. A missing file is skipped. Use it for rules a pull request must not change for itself, such as the review rules in REVIEW.md. The repository's other instructions come from the checkout, as above.

base_setup_script names a script that the session reads from the base branch. When the file exists, the session runs it with bash after sandbox.setup_script, with the checkout's path as its argument. It runs:

  • in each step run until it succeeds in the sandbox;
  • never again in the sandbox after a run that does not finish;
  • again when the base branch's script changes;
  • within the time limit SandboxSettings.command_timeout;
  • with the sandbox's egress and credentials, and no others.

When the script fails or does not finish, the agent runs anyway. The session adds the failure to ToolRequest.step_run.settings_problems. It also adds a note to the agent's prompt that tools the script installs may be missing, and that a command that fails because of that is not evidence of a problem in the code. The script runs against the checkout of the pull request's head; The pull request's own configuration describes what that allows. The session reuses a sandbox for each push to the pull request, so the script does not update the dependencies it installed for later pushes. Install toolchains in the script. The agent installs dependencies with its own commands when it needs them.

The step run loads a plugin at its marketplace's current commit, unless the agent's plugin_pins names a commit for it. Either way, the commit is recorded in history.

SessionConfig​

auto_swe.session.config.SessionConfig is the session's input besides its subject. The webhook function starts every session with the defaults.

FieldDefaultMeaning
agentsemptyAgents to run besides those enabled by default
startNoneAn agent and step that every work item's agent run starts at, in place of where its triggers start it. Only the evals of one step set it
dry_runfalseGive the sandbox read-only credentials, so writes from the sandbox fail. Registered tools write nothing. The prompt of an agent with allow_sandbox_writes says that its writes from the sandbox will be refused
idle_timeout14 daysA session with no work item for this long ends
model_timeout5 minutesOne model call's activity timeout
model_heartbeat_timeout1 minuteOne model call's heartbeat timeout
model_max_attempts10The most attempts at one model call. When the last attempt fails, the step run fails
sandboxSandboxSettings()Sandbox paths, command timeouts, Daytona auto-stop and auto-delete
run_budgetRunBudget(per_day=10, usd_per_day=3)The most step runs the session starts, and the most dollars it spends on them, in a rolling hour and a rolling day. See The run budget

Environment​

VariableRead byMeaning
TEMPORAL_ADDRESS, TEMPORAL_NAMESPACEbothThe Temporal endpoint and namespace
TEMPORAL_API_KEYbothSet for Temporal Cloud, which also turns on TLS
EXTERNAL_STORAGE_BUCKET or EXTERNAL_STORAGE_DIRbothWhere payloads over 64 KB are written
GITHUB_WEBHOOK_SECRETwebhookThe GitHub App's webhook secret
GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_IDworkerThe GitHub App the worker mints tokens as
GITHUB_TOKENworkerLocal runs only: a token used in place of the App's for the worker's own GitHub calls. The sandbox's GitHub Secrets always hold App installation tokens
DAYTONA_API_KEYworkerSandbox and Secret calls to Daytona; the key needs write:sandboxes, delete:sandboxes and manage:secrets
AUTO_SWE_CREDENTIAL_EXPIRY_TABLEworkerThe DynamoDB table of credential expiries. A local worker without it keeps them in memory
AUTO_SWE_AWS_MCP_ROLE_ARNworkerThe role the worker assumes for the AWS MCP Server. A local worker without it uses its own AWS credentials
ANTHROPIC_API_KEYworkerModel calls of agents whose model starts with anthropic:
OPENAI_API_KEYworkerModel calls of agents whose model starts with openai:
LANGSMITH_API_KEY, LANGSMITH_PROJECTworkerTracing, required: the worker does not start without the key
TYPESAFE_API_KEYworkerIn a local run, the TypeSafe key that the worker's TypeSafe requests use in place of auto-swe/typesafe/api-key. See Tokens and cost
OTEL_EXPORTER_OTLP_ENDPOINT and the other OTEL_* variablesworkerOptional. Where the sandbox spans are exported. See Sandbox spans

In AWS each secret arrives as <NAME>_SECRET_ARN, which the function resolves at cold start. Locally, workflows/auto_swe/.env holds the non-secret values. The credential providers read their values from Secrets Manager by name, when they mint a Secret.