#Managed mode: which parts of lazy.toml a shared host honours

Normally, lazy.toml is yours. You committed it, you run lazy on your own machine, and every key in it is honoured exactly as written. Nothing on this page applies to that. Managed mode is off by default and, when off, changes nothing at all.

Managed mode is for a shared host — any fleet where one machine runs daemons for projects belonging to different people. There, lazy.toml arrives with the repository, and a repository is untrusted input. A committed config that says "run agents outside the container, as the fleet user" is not a preference; it is an escape. So on a managed host lazy sorts every config key into three buckets:

#Why override some keys and refuse others

Both are equally safe — neither honours the repository. The choice is about diagnosability:

• Override when the fleet's value is a drop-in substitute and your project still does what you meant. You asked for a specific [server] port; you get a different one; everything works. Silently substituting is fine because nothing about your project's behaviour changed.
• Refuse when the fleet does not offer the capability at all. Silently dropping [[mounts]] would leave your project running as something materially different from what you configured, with no failure to trace. A refusal is loud, once, at the moment you'd otherwise start debugging.

#Unclassified keys fail closed

A config key with no entry in the classification is refused, not overridden. Overriding to a default asserts that the default is safe — which is exactly the judgement nobody made for a key that nobody classified.

In practice you should never see this: lazy's own test suite fails when a config key it knows has no classification, so an unclassified key cannot reach a release. The runtime refusal is the backstop.

A key lazy does not know at all — a typo, or a stale option from an older version — is not refused. Lazy never reads it, so it cannot do anything. Those still show up in lazy doctor as unknown options, exactly as they always have.

#Finding out why your config is being ignored

Run lazy doctor in the project. On a managed host it prints one line per key the fleet is not honouring:

⚠ lazy.toml 'runner.type'
  This repository's lazy.toml asks for "host"; managed mode uses "docker".
  A host runner would run agent code outside any container, as the fleet user,
  on a machine shared with other projects.

That is the only surface that explains it. Everything else — a start failure, a provisioning error — carries one generic pointer here rather than repeating the diagnosis, because an override warning printed on every config load would land in the middle of every agent turn.

A refusal is different: it is not a warning to go looking for, it is the error you already got. It fires at the earliest possible moment — lazy init checks the repository's committed config before it writes anything — and then on every command afterwards, naming each refused key and what to do about it.

#How a host becomes managed

Three environment variables, read at daemon start:

Deliberately not a lazy.toml key: lazy.toml is the untrusted input this whole mechanism exists to bound. A managed host armed without a storage path refuses to run rather than falling back to the repository's external_path.

A fleet host sets these in the environment of each project's daemon when it starts it; Lazy Teams does this for every project it runs.

#The classification, in full

Every key lazy resolves appears below. Non-respected keys carry the reason.

#Refused

#Overridden

#Respected, with a containment guard

These are honoured, but the value must stay inside the project directory. An absolute path or a .. that escapes the checkout is refused — it would reach host files that are not this project's.

docker.dockerfile · worktree.include · documents.path

#Respected

Everything else. In full:

models.default · models.roles.*.model · models.roles.*.agent · agents.*.harness · agents.*.model · agents.*.description · proxy.retry_after_threshold · proxy.upstream_timeout · proxy.policy.deny_path_globs (it can only ever ADD denials) · docker.build_inputs · remote.driver · remote.git_remote · remote.auto_approve · remote.offline · remote.github_auto_push · remote.gitlab_auto_push · automation.maintain · automation.react · automation.pre_accept · automation.pre_accept.enabled · automation.pre_accept.commands · automation.pre_accept.timeout · automation.pre_turn · automation.pre_turn_timeout · automation.pre_turn_required · automation.post_turn · automation.post_turn_timeout · automation.accept_check · automation.accept_check_timeout · checks.post_turn · checks.post_turn_timeout · session.verbose · session.debug · session.auto_commit_instructions · git.default_branch_prefix · git.lfs_check · git.coauthor_trailer · output.shortid_length · agent.agent_id · agent.by_type · agent.watchdog_output_timeout_ms · agent.wind_down_timeout_ms · agent.graceful_exit_timeout_ms · agent.effort · agent.low_high_loop · agent.low_high_loop_draft_effort · agent.low_high_loop_review_effort · builder.effort · chattiness.default · chattiness.builder · chattiness.agent · permissions.protected · protection.enabled · protection.protected_branches · protection.protected_tasks · protection.gate_default_branch · serve.ports · serve.services · serve.start_services_cmd · memory.warn_bytes · docs.url · daemon.auto_react_ci · daemon.auto_react_comments · daemon.auto_react_max_retries · daemon.auto_react_backoff · daemon.auto_react_daily_budget · daemon.max_auto_turns · limits.max_turns_without_human · cluster.max_child_fix_rounds · loop.max_child_fix_rounds (the deprecated spelling, still honoured) · usage_pause.threshold_percent · usage_pause.credentials · review.mode · review.auto_fix · review.gate · review.draft_effort · review.review_effort · agent.low_high_loop · agent.low_high_loop_draft_effort · agent.low_high_loop_review_effort (the deprecated spellings of the three [review] keys above, still honoured) · daemon.auto_resume · daemon.auto_resume_interval_minutes · daemon.auto_resume_gap_minutes · daemon.auto_resume_max_attempts

A resolved role is a flattened agent profile, so lazy's own resolution puts a few more fields on it than any lazy.toml key spells — models.roles.*.harness, models.roles.*.credential, models.roles.*.wire, models.roles.*.pinned and models.roles.*.profile. They are classified as respected because their values come from asks that were already classified above (models.roles.*.agent and the [agents.<name>] block it names), never from a string a repository put there.

The automation hooks deserve a note, because "does this run on the host?" is the question that decides the whole table. automation.pre_turn and automation.post_turn run inside the agent container — but only because runner.type is overridden. Under a host runner they would execute on the fleet machine. automation.pre_accept — the acceptance gate — runs in its own ephemeral gate container (same runner type, no agent inside), so it never executes on the fleet machine either way. That is why the runner is the linchpin, and why it is not negotiable.

#What lives where

The classification is a property of lazy itself, not of any one fleet product: a self-hosted single-tenant managed install needs exactly the same table, and lazy doctor needs to point somewhere that renders. So the table and the mechanism live in lazy itself; the fleet-side decisions (how the daemon is armed, how a refusal is surfaced in the UI) belong to the managed product itself.

#When the host owns the config file

A host can take ownership of a project's lazy.toml altogether. It sets LAZY_MANAGED_CONFIG_PATH in the daemon's environment to an absolute path outside the project checkout (a path inside it is refused). Until that file exists, lazy reads the repository's lazy.toml as usual. Once it exists, lazy reads only that file — changes to the repository's lazy.toml no longer have any effect, and nothing is ever written into the checkout.

Lazy Teams uses this for its project Settings → Configuration page:

• When a project is set up, its repository's lazy.toml is copied once.
• The team's owner edits it on the page; every member can read it, and anyone who can read it can download it as a lazy.toml to commit if they wish. Every save is kept as a new version with who saved it and when, and the history shows what each version changed as a diff against the one before it.
• Settings are edited in a form, grouped by what they are for. Each shows what it does, lazy's default, and when a change to it is picked up. Settings with list or table values (protected files, maintained files, agent profiles) are edited in the lazy.toml text, which stays available underneath the form; comments in the file are kept when the form saves.
• Check judges a change without saving it and lists what saving would change. Each save is checked by lazy first too, with the same rules a load uses: an error names the setting it is about, and a configuration with errors is not saved. Settings the host decides (see the tables above) and settings lazy does not recognise are reported as notes — they are kept in the file but have no effect.
• lazy re-reads the configuration every time it does something, so a saved change needs no restart: it is picked up the next time lazy does what that setting governs. After a save the page names each changed setting and when that is — when the next turn starts (models, effort, usage pause), when the next turn finishes (after-turn checks, protected files), at the next review or accept, within a minute for background behaviour such as resuming interrupted work, or immediately for settings like the forge driver. The exception is what lazy's proxy is set up with when the project starts: [proxy] retry_after_threshold, upstream_timeout, [proxy.policy] deny_path_globs, and agent profiles ([agents.<name>]) that send their traffic to their own endpoint. Changing any of those restarts the project, which pauses work in progress and resumes it.
• Agent profiles in this file may set endpoint and credential (including ones copied from the repository at setup), although a repository's own lazy.toml may not: on a managed host a profile's own endpoint is paid only by the credential each member connects for that profile — never by the host's own credentials — and members see the endpoint before they connect one. A member's credential is sent only to the endpoint the profile had when they connected it; if the owner points the profile elsewhere, it is not used until they connect it again.
• It is one-way: a downloaded or committed copy is never read back.
• If a saved configuration stops loading after an upgrade, the project cannot start. The owner fixes it on the same page: the correction is checked by lazy, saved, and — unless the project was stopped on purpose — the project is started with it. When another project on the installation already runs the current version of lazy, it checks the fix before it is saved. Otherwise the project's own start is the check: if the configuration still cannot be loaded, lazy's reason is shown on the page next to the saved version, so it can be corrected and saved again.