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_filereturns 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_settingsandtool_choiceas ananthropic: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, andChatBedrockConversesends 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.yamladds underegress, each of which must be insandbox.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 allowsexample.comand 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:
| Use | Hosts |
|---|---|
setup.sh, and scie-pants' downloads of the Pants PEX and its Python | release-assets.githubusercontent.com, the host that github.com redirects release downloads to |
| Pants' downloads of pex, ruff and buildifier | release-assets.githubusercontent.com |
| Pants' downloads of the lockfiles' distributions | pypi.org, files.pythonhosted.org |
Tests that start temporalio's WorkflowEnvironment, which downloads the Temporal test server | temporal.download |
setup.sh's install of corepack, corepack's downloads of pnpm, and npm's and pnpm's package downloads | registry.npmjs.org |
| Plugin and marketplace fetches | github.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_guidancewith apath_guidancelist; - add hosts from
sandbox.approved_repo_egresstosandbox.egresswith anegresslist.
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.
| Setting | Read by | Meaning |
|---|---|---|
max_nits | github_post_review | Nits posted per review; the rest are counted in the body |
max_pre_existing | github_post_review | Pre-existing findings posted per review |
max_considerations | github_post_review | Considerations posted per review, under "Worth a look" |
skip_paths | github_post_review | Glob patterns; a finding or consideration on a matching path is not posted |
max_changed_files | github_push | The 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:
| Field | Default | Meaning |
|---|---|---|
type | required | The work item's type. The loader rejects a type that has no context type. |
event | any event | The work item's event |
actions | any action | The actions that match the work item's action |
when | no conditions | Conditions on top-level payload fields. A scalar field must equal the value, and a list field must contain it. |
step | required | The step the agent run starts at |
request | the step's | Replaces 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
activityand runs that activity instead of an agent loop. The activity is a key ofauto_swe.agents.registry.STEP_ACTIVITIES; - a rubric step, which sets
rubricandstate, 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:
| Field | Default | How 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. |
instructions | none | Files appended to the agent's instructions in the system prompt |
tools | none | Added to the agent's tools. The loader rejects a tool that both list. |
model, model_settings, max_model_calls, max_minutes | the agent's | Each replaces the agent's |
settings | none | Replaces the agent's settings that it names. The repository's .auto-swe/config.yaml overrides them in turn. |
credentials | the agent's | Replaces the agent's credentials. Each grant must be the agent's grant or its read-only grant. |
conversation | none | The name of the agent's conversation that the step continues and saves. See Conversations. |
prepare_script | the agent's | Replaces 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_promptandmemory_prompt;read_limit;sandboxapart fromprepare_script,repo_contextandplugin_pins;allow_sandbox_writesandmcp_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:
| Field | Default | Meaning |
|---|---|---|
on | {} | The next step for each outcome, or end |
max_rounds, after_max_rounds | no limit | How 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
onleaves out an outcome that the step's tool or activity declares; - a step's
onmaps an outcome that the step cannot return; - a step has more than one tool that returns outcomes;
- a trigger, an
onor anafter_max_roundsnames 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:
| Field | Meaning |
|---|---|
rubric | A YAML file, relative to the agent's directory, that lists the questions |
state | The 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
| Field | Default | Meaning |
|---|---|---|
model | required | The Jev model. typesafe:<model> needs a price in auto_swe/harness/model_prices.json. |
criteria[].id | required | The Noul's key in the request. Lowercase letters, digits and underscores, starting with a letter, and unique in the rubric. |
criteria[].question | required | The Noul's instructions. Write it so that yes means the criterion is met. |
criteria[].yes, criteria[].no | none | What 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[].required | true | Whether 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:
rejectedwhen a required criterion is no;unsettledwhen no required criterion is no and one is unsettled;passedwhen 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, orNone.;$request, the step'srequest, or therequestof 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 noconversationlearns from$last_replywhat 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,labelschanged_files,additions,deletionshead_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 withgit diff $merge_base HEAD.sender, who caused the event, andlabel, the label alabeledaction addedcomment_id,comment_author,comment_body,comment_path, for a comment eventcheck_name,check_conclusion, for a check eventlinked_issues, the issues the pull request closes, each with its title and its body up to 2,000 charactersconversation, 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
toolsthat 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, asdagster_run_eventsreads 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 ofauto_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:Tool Writes Per step run In a dry run github_post_commentA comment on the pull request, with 👍 and 👎 reactions Once Not 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 whosestatusisfixedorneeds_choice. The same review holds therepliesin 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 setsresolveOnce Renders 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 👎 reactions Once Returns 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 whenresolve_asked_threadis setOnce Returns 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 isauto-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 ispushed, with thebranchandcommit, and for alinear.issue, thebase_commitOnce Lists each commit's message and files, pushing nothing and returning no outcome The Linear tools act on a
linear.issuework item's issue:Tool Writes Per step run In a dry run linear_post_commentA comment on the issue Once Not run github_pushandgithub_open_pull_requestact on alinear.issue's branch in the work item's repository. They read the payload'sidentifier,branch,base_commitandreview, and the checkout's commit. They read no field specific to the system the work item came from:Tool Writes Per step run In a dry run github_open_pull_requestA draft pull request from the branch to main, with thepr-reading-guideskill'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 isopened, with thepull_request_urlOnce Returns the title and body, opening nothing and returning no outcome submit_reviewwrites nothing and acts on agithub.pull_requestor alinear.issue. It takes the arguments ofgithub_post_reviewwithoutfix_summaryandreplies. Its outcome isfindingswhile an important finding is open, with the open important findings to fix. Otherwise its outcome ispassed. Both have the review's findings, fixed and open, asreview. It runs once per step run, and runs in a dry run as it does outside one. -
Script tools, entries in
toolsthat give ascript. 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_serversallows. 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.
| Key | Value | The sandbox gets |
|---|---|---|
github | GitHub App permissions, each read or write: actions, checks, contents, issues, metadata, pull_requests, statuses | GH_TOKEN for gh and the REST API, and git's Authorization header in the checkout, for the work item's repository |
linear | read or write | LINEAR_API_KEY, which holds the whole Authorization header value Bearer <token>. The token is from the Linear OAuth app for that access level |
nessie | read | NESSIE_TOKEN, and NESSIE_URI and NESSIE_AUTH=token for ai_core.nessie.load_nessie_catalog |
dagster | read or write | DAGSTER_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
githubcredential that hascontents; - 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:
| Found | Loaded as |
|---|---|
CLAUDE.md, .claude/rules/*.md, and the files they import with @path, up to four hops | Instructions, 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 searched | Instructions, after the system prompt |
.claude/skills/*/SKILL.md | Skills |
enabledPlugins in .claude/settings.json | The plugins' skills |
PreToolUse and PostToolUse command hooks in .claude/settings.json | Hooks, 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.
| Field | Default | Meaning |
|---|---|---|
agents | empty | Agents to run besides those enabled by default |
start | None | An 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_run | false | Give 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_timeout | 14 days | A session with no work item for this long ends |
model_timeout | 5 minutes | One model call's activity timeout |
model_heartbeat_timeout | 1 minute | One model call's heartbeat timeout |
model_max_attempts | 10 | The most attempts at one model call. When the last attempt fails, the step run fails |
sandbox | SandboxSettings() | Sandbox paths, command timeouts, Daytona auto-stop and auto-delete |
run_budget | RunBudget(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
| Variable | Read by | Meaning |
|---|---|---|
TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE | both | The Temporal endpoint and namespace |
TEMPORAL_API_KEY | both | Set for Temporal Cloud, which also turns on TLS |
EXTERNAL_STORAGE_BUCKET or EXTERNAL_STORAGE_DIR | both | Where payloads over 64 KB are written |
GITHUB_WEBHOOK_SECRET | webhook | The GitHub App's webhook secret |
GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID | worker | The GitHub App the worker mints tokens as |
GITHUB_TOKEN | worker | Local 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_KEY | worker | Sandbox and Secret calls to Daytona; the key needs write:sandboxes, delete:sandboxes and manage:secrets |
AUTO_SWE_CREDENTIAL_EXPIRY_TABLE | worker | The DynamoDB table of credential expiries. A local worker without it keeps them in memory |
AUTO_SWE_AWS_MCP_ROLE_ARN | worker | The role the worker assumes for the AWS MCP Server. A local worker without it uses its own AWS credentials |
ANTHROPIC_API_KEY | worker | Model calls of agents whose model starts with anthropic: |
OPENAI_API_KEY | worker | Model calls of agents whose model starts with openai: |
LANGSMITH_API_KEY, LANGSMITH_PROJECT | worker | Tracing, required: the worker does not start without the key |
TYPESAFE_API_KEY | worker | In 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_* variables | worker | Optional. 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.