Settings¶
Below the catalogs in the studio rail sit fourteen global settings groups. Each one is a typed form over a top level block of agentsmith.yml, and each one applies to every project unless a project overrides it.
They save the same way the catalogs do: one Save changes, a row in the change feed, and a live pickup by the running server, except where a field says it applies after a restart. A value the server would refuse at run time (a negative round count, a series cap above 26) is refused on save instead, and the reason shows under the Save button.
What each group changes¶
Orchestrator¶
MaxRunWallTimeSeconds, the ceiling on how long one run may take before it gets cancelled. It defaults to 1800, so a run that is still going after thirty minutes is stopped. Raise it for a codebase where a legitimate run genuinely takes longer, and lower it if you would rather find out early. A design turn in a conversation is not stopped by it: only its cost cap or a person ends one, and every model call it makes is bounded by the agent's network timeout instead.
Sandbox¶
The sandbox agent image (registry and version) plus two timeouts, StepTimeoutSeconds at 900 and RunCommandTimeoutSeconds at 300. The two are one rule: a run_command gets the command timeout when it asks for none, may ask for more, and is killed at the step cap. So the step cap is the ceiling a command may request, and raising it raises what a command may ask for; the command timeout can't be set above it. A repo whose test suite runs longer than five minutes needs the command timeout raised, and the symptom when you haven't is a command that reports it timed out at the same second every time.
Leave the agent version empty and the sandbox agent tag is derived from the release the running server is, so the two can't drift apart by being forgotten. Set it only to pin a different published tag on purpose (an air-gapped mirror carrying one release, say); a pin is reported as an advisory finding, never refused.
The image pin and the two timeouts are read from an instance built at startup, so they need the server restarted; each of those fields says so. The rest of the group applies without one:
MaxConcurrentSandboxes: the Docker capacity probe reads it each time it decides whether a run fits. The field is optional (the same key ismax_concurrent_sandboxesinagentsmith.yml), and left empty it falls back to theSANDBOX_MAX_CONCURRENTenvironment variable, then to the built-in default of 2.0means unbounded. It bounds the Docker backend only: a Kubernetes installation bounds sandboxes through its namespaceResourceQuotaand the in-process backend is unbounded. The full story is on the capacity page.- Sandbox hold (seconds): how long a design conversation keeps the source sandboxes it opened after a turn, so the next question doesn't pay for the clone again. Empty falls back to
SANDBOX_HOLD_SECONDS, then 180;0holds nothing. A project can override it on its own sandbox tab. - Trusted image registries: where a context's
stack.imagemay come from (allowed_registriesinagentsmith.yml). Each entry is a prefix of the image reference as Docker reads it, so an image with no registry host counts asdocker.io:sbtscala/anddocker.io/sbtscala/are the same entry,docker.io/library/is the Docker Hub official images (node:22-bookworm), anddocker.io/alone trusts all of Docker Hub. With no entry the built-in default applies (mcr.microsoft.com/,ghcr.io/anddocker.io/library/), and adding the first entry starts from those three as visible, removable rows, so naming one registry doesn't silently drop the others. Allow new registries (allow_new_registries) lets a ticket's code run add the registry of an image the list refuses, as a change attributed to that run and recorded in its decisions; a pull-request review or a security scan never adds one. Below it, In force now shows the boundary the next decision is judged against, as the server reads it, and says when the form has unsaved changes. A save applies to the next image decision. The boundary judges thestack.imagea context declares, and a refused one falls back to the language default. An image you name yourself in a project's sandbox tab is your choice and passes as written, and so do the built-in fallbacks.
Harden sandboxes (hardening_enabled in agentsmith.yml, off by default) runs Docker and Kubernetes sandboxes as uid 1000 with no Linux capabilities and no privilege escalation. It needs a server restart. Before turning it on, find the projects whose prerequisites install system packages (apt-get, npm install -g): they fail until their sandbox tab turns on run sandboxes as root, which then shows a warning on each of their runs. Kubernetes has the details.
Every one of these except MaxConcurrentSandboxes, hardening and the registry boundary can be overridden per project in the project drawer's sandbox tab (see The Config studio). Image pull secrets and what the hold does to capacity live with the rest of the sandbox model on Sandbox architecture, and the registry boundary from the cluster side on Kubernetes.
Deployment¶
A single registry plus version for the sandbox agent image, used when the Sandbox group leaves its own unset. Left empty, the tag is derived from the running server's release, so there is nothing to bump on upgrade; set it only to pin a tag on purpose.
Registries¶
Private package feeds the agent authenticates against inside the sandbox, so dotnet restore or npm install against your internal feed works without baking credentials into a toolchain image.
Primary provider¶
The agent used when a project doesn't name one.
Limits¶
The ceilings on one agentic loop: tool calls, tokens, sub agents, concurrent skill calls. These stop a confused loop from grinding, and they apply per skill rather than per run.
Pipeline cost cap¶
The money one. A default cap in USD and tokens, five tier caps (trivial, small, medium, large, xl) applied by the estimated size of the work, and optional per pipeline overrides. A run that hits its cap stops and says so. A tier you never edited keeps its built-in default ($1, $2, $8, $25 and $40), and the form shows that value marked as the default; editing one stores only that tier. Pipeline cost cap has the token halves and how a tier is picked.
Queue¶
Consumer backpressure, and how often the queue retries against Redis.
Dialogue¶
How long a run waits for you. HotWaitSeconds is the window it holds the sandbox open expecting a fast answer. ApprovalTimeoutSeconds is how long the question stays answerable before the run gives up. The defaults are ten minutes and three days.
The same block carries dashboard_url, your dashboard's address, so the ticket comment that asks a question links to the run's page. Without it the comment carries no link. It also carries admin_agent, the configured agent the admin assistant runs on (Work it out > Agent Smith, admins only). admin_read_limit and admin_result_max_chars bound what one of its reads returns. All of them have a field in the form.
Spec review¶
Fresh reviewers attack a spec and their cuts are applied when the master revises a spec with revise_spec, when the entry re-ground checks a spec, and in a Work it out turn. A coding run does not review specs before building them. This group sizes that review:
- Rounds per spec, 4 by default.
0turns the review off. - Reviewers per round, 2: fresh reviewers attacking each spec in one round.
- Max concurrent reviewers, 2.
- Budget share (percent), 40: the share of the run's cost cap and wall clock a coding run's review may use. A proposal in Work it out has no share and no time limit: every draft gets its rounds, and only the run's cost cap or a cancel stops them.
The block is spec_review: (rounds, reviewers, max_concurrent, budget_share_percent), and every run reads it fresh. An invalid block is refused at validation: saving it, importing a file with it, and the startup check all name the problem (for example spec_review.rounds is -1; it must be 0 or more). It sets the review a spec gets when its master revises it or the run re-grounds its citations; nothing reviews a spec before its master builds it, and a proposal in Work it out is not reviewed after its turn. design_turn is retired: a file that still sets it gets an advisory.
Series¶
How big a ticket's series of specs may get, how much of it one attempt runs, and how far a chain of attempts may go on by itself:
- Max specs, 24: the most specs one ticket's series holds, between 1 and 26 (one member letter each).
- Specs per attempt, 8: the most specs one attempt runs. It can't exceed max specs, nor 18, the most one run's step guard holds.
- Seconds per spec, 0: the measured time of one whole spec block (build, review, verify, record). With a value, an attempt runs fewer specs when the blocks left don't fit the run's wall clock, keeping one block for the commit and PR.
0means not measured, and specs per attempt alone decides. The server refuses a value where two blocks exceed the Orchestrator's run wall time. - Budget (USD), 150: what one chain of attempts may spend before the next attempt is held for a person.
0turns automatic continuation off, so no attempt starts by itself. - Wall clock (hours of run time), 12: the summed run time of one chain before the next attempt is held. Time spent waiting between attempts doesn't count.
- Continue after a wall-time cancel, on: whether an attempt the wall clock cancelled after a finished spec goes on with the next attempt.
The block is series: (max_specs, specs_per_attempt, seconds_per_spec, budget_usd, wall_clock_hours, continue_after_wall_time), read fresh by every run.
Skills¶
Where the skill catalog is resolved from. Every release ships with its catalog embedded, so there is nothing to pin here. It exists as an override for skills development and for air gapped mirrors.
Pipeline data flow¶
Whether the data flow gate warns or enforces.
Trace¶
Whether a run records its conversation (every prompt as sent, every answer, every tool result as the model received it), not only its numbers. Off by default, because a traced run's record grows fast. The AGENTSMITH_TRACE environment variable, when it is set, wins over this switch in both directions, so a deployment that sets it in its manifest keeps what the manifest says. See Recording what the model was told.
What the settings rail leaves out¶
persistence: is absent on purpose. It's bootstrap only, read from the file before the server can talk to a database, so making it editable in a UI backed by that database would be a circle. Change it in agentsmith.yml and restart.
auth: and tool_runner: are bootstrap as well: the token authority is wired before the database is reachable, and the scanners' runner is built at start. Both stay in the server's own agentsmith.yml. An import doesn't store them and says so, as it does for every other key of the file it doesn't keep.
secrets: is absent because it has its own catalog. The studio holds names, and values stay in the environment.