Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(canvas): quiet backend logs by default (#18830)

Graham Neubig39891795e0bb
diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.md
index 0ff6d95dbd..6ba82af3a0 100644
--- a/.agents/skills/local-stack-runtime/references/guide.md
+++ b/.agents/skills/local-stack-runtime/references/guide.md
@@ -116,6 +116,8 @@ you are running inside of β€” NOT the automation backend.
- Security: the automation backend receives the same session key as the agent-server through `AUTOMATION_LOCAL_API_KEY`; the frontend does not bake a separate automation API key.
- `scripts/ingress.mjs` is a standalone HTTP reverse proxy that can be used independently to route traffic to multiple backends based on URL path prefix.
- `scripts/dev-safe.mjs` (now `npm run dev:minimal`) runs just agent-server + Vite without automation.
+- **Backend log level**: every Canvas launch path defaults the spawned backends to `WARNING` so a plain launch is readable β€” at `INFO` the automation service's `setup_all_loggers()` raises *every* registered logger, including `sqlalchemy.orm`, which emits hundreds of model-mapping lines before the service is reachable. The policy lives in `scripts/dev-safe.mjs` (`DEFAULT_BACKEND_LOG_LEVEL`, `backendLogLevel()`, `buildBackendLogEnv()`), which `dev-with-automation.mjs`, `dev-static.mjs`, and `docker/entrypoint.sh` all use; the same resolved level is passed to Uvicorn's `--log-level`, because that flag β€” not `LOG_LEVEL` β€” governs the startup banner and per-request access lines. Precedence: `--verbose` > an explicit `LOG_LEVEL` / `AUTOMATION_LOG_LEVEL` > the `WARNING` default. Standalone automation-service deployments keep their own `INFO` default; only what Canvas passes changes. `WARNING` rather than `ERROR` is deliberate β€” `ERROR` would also hide the workspace-retention warning.
+ - The two sides accept different vocabularies, so the Uvicorn argument is narrowed by `uvicornLogLevel()` (and the shell's `uvicorn_log_level()` in the entrypoint) rather than forwarded verbatim. The app reads `LOG_LEVEL` through Python's logging module, which also understands `WARN`, `FATAL`, `NOTSET` and numeric levels; Uvicorn validates `--log-level` with a `click.Choice` over `critical | error | warning | info | debug | trace` and exits `2` on anything else, which would take the service β€” and the dev stack β€” down. Aliases map to their equivalents (`WARN` β†’ `warning`, `FATAL` β†’ `critical`), numbers map to the nearest name, and values with no Uvicorn equivalent (`NOTSET`, `0`, unrecognized strings) fall back to `info`, Uvicorn's own default. The env value keeps its raw form; only the CLI argument is narrowed.
- **Centralized config**: `config/defaults.json` is the single source of truth for version pins (agent-server, automation, automation SDK), port defaults, persistence paths, and package names. All consumers read from this file:
- JS scripts (`dev-safe.mjs`, `dev-with-automation.mjs`, `check-sdk-version-sync.mjs`) read it via `JSON.parse(readFileSync(...))`.
diff --git a/.pr/design.html b/.pr/design.html
new file mode 100644
index 0000000000..1f57505de7
--- /dev/null
+++ b/.pr/design.html
@@ -0,0 +1,392 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Quiet Canvas backend logs by default β€” design doc</title>
+<style>
+ :root {
+ --bg: #fbfaf7;
+ --ink: #1b1d22;
+ --muted: #6a6f7a;
+ --line: #e2ded4;
+ --card: #ffffff;
+ --accent: #b4541f;
+ --accent-soft: #fdf1e8;
+ --green: #1f6f43;
+ --green-soft: #eaf5ee;
+ --red: #a83232;
+ --red-soft: #fbeceb;
+ --blue: #245b8f;
+ --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+ }
+ * { box-sizing: border-box; }
+ body {
+ margin: 0;
+ background: var(--bg);
+ color: var(--ink);
+ font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+ }
+ .wrap { max-width: 1060px; margin: 0 auto; padding: 48px 28px 96px; }
+ header { border-bottom: 2px solid var(--ink); padding-bottom: 22px; margin-bottom: 34px; }
+ .kicker { font-size: 12px; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); font-weight: 700; }
+ h1 { font-size: 34px; line-height: 1.2; margin: 10px 0 12px; letter-spacing: -.02em; }
+ .lede { font-size: 18px; color: #3c414b; margin: 0; max-width: 74ch; }
+ .meta { margin-top: 16px; font-family: var(--mono); font-size: 12.5px; color: var(--muted); }
+ .meta a { color: var(--blue); text-decoration: none; border-bottom: 1px dotted var(--blue); }
+ h2 { font-size: 22px; margin: 46px 0 14px; letter-spacing: -.01em; }
+ h2 .n { color: var(--accent); font-family: var(--mono); font-size: 15px; margin-right: 8px; }
+ h3 { font-size: 16px; margin: 26px 0 8px; }
+ p { margin: 10px 0; }
+ code, .mono { font-family: var(--mono); font-size: 13px; }
+ code { background: #f1eee7; padding: 1px 5px; border-radius: 4px; }
+ a { color: var(--blue); }
+ .callout {
+ border-left: 4px solid var(--accent);
+ background: var(--accent-soft);
+ padding: 16px 20px;
+ margin: 22px 0;
+ border-radius: 0 8px 8px 0;
+ }
+ .callout .tag { font-weight: 700; color: var(--accent); }
+ .stats { display: flex; gap: 14px; flex-wrap: wrap; margin: 22px 0; }
+ .stat {
+ background: var(--card); border: 1px solid var(--line); border-radius: 10px;
+ padding: 14px 18px; min-width: 150px;
+ }
+ .stat .k { font-size: 11.5px; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
+ .stat .v { font-family: var(--mono); font-size: 21px; font-weight: 700; margin-top: 4px; }
+ .stat .v .to { color: var(--green); }
+ .stat .v .from { color: var(--red); }
+ figure { margin: 22px 0; }
+ figcaption { font-size: 13px; color: var(--muted); margin-top: 8px; }
+ svg { max-width: 100%; height: auto; display: block; }
+ table { border-collapse: collapse; width: 100%; margin: 16px 0; font-size: 14px; }
+ th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--line); vertical-align: top; }
+ th { font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); }
+ td code { font-size: 12.5px; }
+ .files { background: var(--card); border: 1px solid var(--line); border-radius: 10px; overflow: hidden; }
+ .files .row { display: grid; grid-template-columns: 26px 1fr 92px; gap: 10px; padding: 11px 16px; border-bottom: 1px solid var(--line); align-items: baseline; }
+ .files .row:last-child { border-bottom: 0; }
+ .files .p { font-family: var(--mono); font-size: 13px; }
+ .files .d { font-family: var(--mono); font-size: 12.5px; text-align: right; color: var(--muted); }
+ .files .d .a { color: var(--green); }
+ .files .d .r { color: var(--red); }
+ .badge { font-size: 11px; padding: 2px 7px; border-radius: 999px; border: 1px solid var(--line); color: var(--muted); white-space: nowrap; }
+ .badge.changed { background: var(--accent-soft); color: var(--accent); border-color: #eccdb6; }
+ .badge.added { background: var(--green-soft); color: var(--green); border-color: #c4e0cd; }
+ pre { background: #23252c; color: #e6e8ee; padding: 16px 18px; border-radius: 10px; overflow-x: auto; font-family: var(--mono); font-size: 12.5px; line-height: 1.55; }
+ pre .c { color: #8b93a7; }
+ pre .k { color: #ffc07a; }
+ pre .s { color: #9ae6a8; }
+ pre .x { color: #ff9d9d; }
+ details { margin: 10px 0 0; }
+ summary { cursor: pointer; font-size: 13px; color: var(--muted); }
+ .twocol { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
+ @media (max-width: 720px) { .twocol { grid-template-columns: 1fr; } }
+ .panel { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
+ .panel.bad { border-top: 3px solid var(--red); }
+ .panel.good { border-top: 3px solid var(--green); }
+ .panel h4 { margin: 0 0 8px; font-size: 13px; letter-spacing: .05em; text-transform: uppercase; }
+ .panel.bad h4 { color: var(--red); }
+ .panel.good h4 { color: var(--green); }
+ ul { margin: 10px 0; padding-left: 22px; }
+ li { margin: 6px 0; }
+ .foot { margin-top: 54px; padding-top: 18px; border-top: 1px solid var(--line); font-size: 13px; color: var(--muted); }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<header>
+ <div class="kicker">Design doc Β· Agent Canvas</div>
+ <h1>Quiet backend logs by default</h1>
+ <p class="lede">
+ Launching Canvas printed several hundred lines of library-internal startup chatter, burying the
+ handful of lines a user needs. This PR makes a default launch readable and keeps the noise
+ available behind an explicit opt-in.
+ </p>
+ <div class="meta">
+ PR <a href="https://github.com/OpenHands/OpenHands/pull/18830">#18830</a> Β·
+ Fixes <a href="https://github.com/OpenHands/OpenHands/issues/18823">#18823</a> Β·
+ 7 files Β· <span class="a">+624</span> / <span class="r">βˆ’13</span> Β·
+ head <code>02d279d6c</code> Β· base <code>c69d5291b</code>
+ </div>
+</header>
+
+<h2><span class="n">01</span>What changed</h2>
+
+<p>
+ Both backends that Canvas spawns read <code>LOG_LEVEL</code> and default it to <code>INFO</code>.
+ At <code>INFO</code> the automation service's logging setup raises <em>every</em> registered logger β€”
+ including <code>sqlalchemy.orm</code> β€” so the SQLAlchemy model mapper narrates its own construction
+ and prints 338 lines before the service is even reachable. The launcher never set a level, so that
+ was the default experience.
+</p>
+
+<p>
+ This PR defaults both backends to <code>WARNING</code> in the shared launcher helper and in the
+ Docker entrypoint. An explicit <code>LOG_LEVEL</code> / <code>AUTOMATION_LOG_LEVEL</code> still wins,
+ and <code>--verbose</code> opts back into <code>DEBUG</code>. Uvicorn's own <code>--log-level</code>
+ is set from the same resolved value, because that flag β€” not <code>LOG_LEVEL</code> β€” governs the
+ startup banner and the per-request access lines.
+</p>
+
+<div class="callout">
+ <p><span class="tag">β˜… The choice of WARNING over ERROR is load-bearing.</span></p>
+ <p style="margin-bottom:0">
+ <code>ERROR</code> would have silenced the flood too, but it also hides a real, actionable warning
+ this repo emits today:
+ <code>Workspace retention is enabled but the configured root … does not exist on this host; no workspace will be purged.</code>
+ <code>WARNING</code> is the smallest change that removes the noise while keeping signals a user can act on.
+ </p>
+</div>
+
+<div class="stats">
+ <div class="stat">
+ <div class="k">Automation lines</div>
+ <div class="v"><span class="from">431</span> β†’ <span class="to">7</span></div>
+ </div>
+ <div class="stat">
+ <div class="k">SQLAlchemy ORM lines</div>
+ <div class="v"><span class="from">338</span> β†’ <span class="to">0</span></div>
+ </div>
+ <div class="stat">
+ <div class="k">With <code>--verbose</code></div>
+ <div class="v">1344 / 338</div>
+ </div>
+</div>
+
+<h2><span class="n">02</span>The behavior before β†’ after</h2>
+
+<figure>
+<svg viewBox="0 0 960 300" role="img" aria-label="Before: launcher passes no level, so INFO reaches every logger including sqlalchemy.orm. After: launcher passes WARNING, so ORM output is suppressed while readiness survives.">
+ <defs>
+ <marker id="ar" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0,0 L10,5 L0,10 z" fill="#6a6f7a"/>
+ </marker>
+ <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0,0 L10,5 L0,10 z" fill="#a83232"/>
+ </marker>
+ <marker id="arg" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+ <path d="M0,0 L10,5 L0,10 z" fill="#1f6f43"/>
+ </marker>
+ </defs>
+
+ <!-- BEFORE -->
+ <text x="12" y="22" font-size="13" font-weight="700" fill="#a83232" font-family="monospace">BEFORE</text>
+ <rect x="12" y="34" width="180" height="52" rx="8" fill="#fff" stroke="#e2ded4"/>
+ <text x="24" y="56" font-size="12" font-family="monospace" fill="#1b1d22">spawnService()</text>
+ <text x="24" y="74" font-size="11" font-family="monospace" fill="#a83232">no LOG_LEVEL set</text>
+
+ <line x1="192" y1="60" x2="248" y2="60" stroke="#a83232" stroke-width="1.6" marker-end="url(#arr)"/>
+
+ <rect x="250" y="34" width="200" height="52" rx="8" fill="#fff" stroke="#e2ded4"/>
+ <text x="262" y="56" font-size="12" font-family="monospace" fill="#1b1d22">config.log_level</text>
+ <text x="262" y="74" font-size="11" font-family="monospace" fill="#a83232">default "INFO"</text>
+
+ <line x1="450" y1="60" x2="506" y2="60" stroke="#a83232" stroke-width="1.6" marker-end="url(#arr)"/>
+
+ <rect x="508" y="26" width="240" height="68" rx="8" fill="#fbeceb" stroke="#e0b4b2"/>
+ <text x="520" y="48" font-size="12" font-family="monospace" fill="#1b1d22">setup_all_loggers()</text>
+ <text x="520" y="66" font-size="11" font-family="monospace" fill="#a83232">every registered logger</text>
+ <text x="520" y="83" font-size="11" font-family="monospace" fill="#a83232">set to INFO, at import time</text>
+
+ <line x1="748" y1="60" x2="804" y2="60" stroke="#a83232" stroke-width="1.6" marker-end="url(#arr)"/>
+
+ <rect x="806" y="26" width="142" height="68" rx="8" fill="#fbeceb" stroke="#e0b4b2"/>
+ <text x="818" y="48" font-size="12" font-family="monospace" fill="#a83232">sqlalchemy.orm</text>
+ <text x="818" y="66" font-size="11" font-family="monospace" fill="#a83232">338 lines</text>
+ <text x="818" y="83" font-size="11" font-family="monospace" fill="#a83232">of mapper output</text>
+
+ <!-- AFTER -->
+ <text x="12" y="176" font-size="13" font-weight="700" fill="#1f6f43" font-family="monospace">AFTER</text>
+ <rect x="12" y="188" width="180" height="52" rx="8" fill="#fff" stroke="#e2ded4"/>
+ <text x="24" y="210" font-size="12" font-family="monospace" fill="#1b1d22">buildBackendLogEnv()</text>
+ <text x="24" y="228" font-size="11" font-family="monospace" fill="#1f6f43">LOG_LEVEL=WARNING</text>
+
+ <line x1="192" y1="214" x2="248" y2="214" stroke="#1f6f43" stroke-width="1.6" marker-end="url(#arg)"/>
+
+ <rect x="250" y="188" width="200" height="52" rx="8" fill="#fff" stroke="#e2ded4"/>
+ <text x="262" y="210" font-size="12" font-family="monospace" fill="#1b1d22">config.log_level</text>
+ <text x="262" y="228" font-size="11" font-family="monospace" fill="#1f6f43">"WARNING" (explicit)</text>
+
+ <line x1="450" y1="214" x2="506" y2="214" stroke="#1f6f43" stroke-width="1.6" marker-end="url(#arg)"/>
+
+ <rect x="508" y="180" width="240" height="68" rx="8" fill="#eaf5ee" stroke="#b9d8c4"/>
+ <text x="520" y="202" font-size="12" font-family="monospace" fill="#1b1d22">setup_all_loggers()</text>
+ <text x="520" y="220" font-size="11" font-family="monospace" fill="#1f6f43">every registered logger</text>
+ <text x="520" y="237" font-size="11" font-family="monospace" fill="#1f6f43">set to WARNING</text>
+
+ <line x1="748" y1="214" x2="804" y2="214" stroke="#1f6f43" stroke-width="1.6" marker-end="url(#arg)"/>
+
+ <rect x="806" y="180" width="142" height="68" rx="8" fill="#eaf5ee" stroke="#b9d8c4"/>
+ <text x="818" y="202" font-size="12" font-family="monospace" fill="#1f6f43">ORM silent</text>
+ <text x="818" y="220" font-size="11" font-family="monospace" fill="#1f6f43">0 lines</text>
+ <text x="818" y="237" font-size="11" font-family="monospace" fill="#1f6f43">Ready-at kept</text>
+</svg>
+<figcaption>
+ The mechanism is one variable. Because <code>setup_all_loggers()</code> applies the level to every
+ registered logger at import time, the level the launcher passes decides whether SQLAlchemy narrates
+ its own mapper construction.
+</figcaption>
+</figure>
+
+<div class="twocol">
+ <div class="panel bad">
+ <h4>Before β€” <code>LOG_LEVEL=INFO</code></h4>
+ <pre style="margin:0"><span class="c">[automation]</span> Applying database migrations
+<span class="c">[automation]</span> {"name": "sqlalchemy.orm.mapper.Mapper",
+ "message": "(Automation|automations)
+ _configure_property(runs, …)"}
+<span class="x">… 338 lines like the above …</span>
+<span class="c">[automation]</span> Ready at http://127.0.0.1:18901/…</pre>
+ </div>
+ <div class="panel good">
+ <h4>After β€” default</h4>
+ <pre style="margin:0"><span class="c">[automation]</span> Starting on port 18901...
+<span class="c">[automation]</span> Using local (.../automation)
+<span class="s">[automation]</span> Ready at http://127.0.0.1:18901/…</pre>
+ </div>
+</div>
+
+<h2><span class="n">03</span>Files changed</h2>
+
+<div class="files">
+ <div class="row"><span class="badge changed">✏️</span><span class="p">scripts/dev-safe.mjs</span><span class="d"><span class="a">+129</span> <span class="r">βˆ’2</span></span></div>
+ <div class="row"><span class="badge changed">✏️</span><span class="p">scripts/dev-with-automation.mjs</span><span class="d"><span class="a">+44</span> <span class="r">βˆ’8</span></span></div>
+ <div class="row"><span class="badge changed">✏️</span><span class="p">scripts/dev-static.mjs</span><span class="d"><span class="a">+16</span> <span class="r">βˆ’1</span></span></div>
+ <div class="row"><span class="badge changed">✏️</span><span class="p">docker/entrypoint.sh</span><span class="d"><span class="a">+53</span> <span class="r">βˆ’2</span></span></div>
+ <div class="row"><span class="badge changed">✏️</span><span class="p">__tests__/scripts/dev-with-automation.test.ts</span><span class="d"><span class="a">+196</span></span></div>
+ <div class="row"><span class="badge added">οΌ‹</span><span class="p">__tests__/scripts/docker-log-level.test.ts</span><span class="d"><span class="a">+184</span></span></div>
+ <div class="row"><span class="badge changed">✏️ </span><span class="p">.agents/skills/local-stack-runtime/references/guide.md</span><span class="d"><span class="a">+2</span></span></div>
+</div>
+
+<h3>The launcher gains one shared helper</h3>
+<p>
+ <code>scripts/dev-safe.mjs</code> now owns the policy, so every launch path resolves the level the
+ same way instead of each re-deriving it:
+</p>
+<pre><span class="k">export const</span> DEFAULT_BACKEND_LOG_LEVEL = <span class="s">"WARNING"</span>; <span class="c">// dev-safe.mjs:819</span>
+
+<span class="k">export function</span> backendLogLevel({ verbose = <span class="k">false</span>, env = process.env } = {}) {
+ <span class="k">return</span> verbose ? <span class="s">"DEBUG"</span> : env.LOG_LEVEL || DEFAULT_BACKEND_LOG_LEVEL; <span class="c">// :834</span>
+}
+
+<span class="k">export function</span> buildBackendLogEnv({ verbose, automation, env } = {}) {
+ <span class="k">const</span> level = backendLogLevel({ verbose, env });
+ <span class="k">return</span> {
+ LOG_LEVEL: level,
+ ...(automation ? { AUTOMATION_LOG_LEVEL: verbose ? <span class="s">"DEBUG"</span> : env.AUTOMATION_LOG_LEVEL || level } : {}),
+ };
+}</pre>
+
+<p>
+ Precedence is deliberate and matches how the services themselves resolve their settings:
+ an explicit environment variable is the strongest signal, <code>--verbose</code> overrides even that
+ because it is a per-invocation instruction, and the quiet default applies only when neither is present.
+</p>
+
+<table>
+ <tr><th>Invocation</th><th>Resolved <code>LOG_LEVEL</code></th><th>Uvicorn <code>--log-level</code></th></tr>
+ <tr><td><code>npm run dev</code></td><td><code>WARNING</code></td><td><code>warning</code></td></tr>
+ <tr><td><code>LOG_LEVEL=INFO npm run dev</code></td><td><code>INFO</code></td><td><code>info</code></td></tr>
+ <tr><td><code>npm run dev -- --verbose</code></td><td><code>DEBUG</code></td><td><code>debug</code></td></tr>
+ <tr><td><code>AUTOMATION_LOG_LEVEL=ERROR npm run dev</code></td><td><code>WARNING</code> / auto <code>ERROR</code></td><td><code>warning</code></td></tr>
+</table>
+
+<h3>Why Uvicorn's flag is set separately</h3>
+<p>
+ Uvicorn takes a <em>lowercase</em> level name and applies it to its own loggers, which are distinct
+ from the application's. Setting only <code>LOG_LEVEL</code> would leave the startup banner and one
+ access line per request at <code>INFO</code>. Measured on a real launch, access lines go from 1 to 0.
+ <code>--verbose</code> restores them.
+</p>
+
+<h3>Docker follows the same default</h3>
+<p>
+ <code>docker/entrypoint.sh</code> defaults both variables and passes the resolved level to both
+ Uvicorn invocations. The two lines are marked with a delimited block
+ (<code># &gt;&gt;&gt; backend-log-level</code> … <code># &lt;&lt;&lt; backend-log-level</code>) so the new
+ test can extract and execute exactly those lines rather than grepping the whole script:
+</p>
+<pre><span class="c"># docker/entrypoint.sh:308</span>
+<span class="k">export</span> LOG_LEVEL=<span class="s">"${LOG_LEVEL:-WARNING}"</span>
+<span class="k">export</span> AUTOMATION_LOG_LEVEL=<span class="s">"${AUTOMATION_LOG_LEVEL:-${LOG_LEVEL}}"</span>
+
+<span class="c"># :413 and :419 β€” both uvicorn invocations</span>
+--log-level <span class="s">"$(uvicorn_log_level "${LOG_LEVEL}")"</span></pre>
+
+<h3>The two sides accept different vocabularies</h3>
+<p>
+ Narrowing the value is not cosmetic. The application reads <code>LOG_LEVEL</code> through Python's
+ <code>logging</code> module, which also understands the aliases <code>WARN</code> and <code>FATAL</code>,
+ numeric levels, and <code>NOTSET</code>. Uvicorn validates <code>--log-level</code> with a
+ <code>click.Choice</code> over <code>critical | error | warning | info | debug | trace</code> and exits
+ <code>2</code> on anything else β€” before the service ever binds. Forwarding the env value verbatim would
+ therefore turn a documented override into a crash:
+</p>
+<pre><span class="c">$ LOG_LEVEL=WARN npm run dev # before this fix</span>
+<span class="r">Invalid value for '--log-level': 'warn' is not one of 'critical', 'error', 'warning', …</span>
+<span class="r">The automation backend exited during startup</span></pre>
+<p>
+ A single normalizer β€” <code>uvicornLogLevel()</code> in JS, <code>uvicorn_log_level()</code> in the
+ entrypoint β€” maps aliases to their equivalents (<code>WARN</code> β†’ <code>warning</code>,
+ <code>FATAL</code> β†’ <code>critical</code>), numeric levels to the nearest name, and everything with no
+ Uvicorn equivalent (<code>NOTSET</code>, <code>0</code>, an unrecognized string) to <code>info</code>,
+ which is what Uvicorn defaulted to before this PR set the flag at all. The environment value keeps its
+ raw form, so the application still sees exactly what the user asked for; only the CLI argument is narrowed.
+</p>
+
+<h3>A latent bug fixed along the way</h3>
+<p>
+ <code>scripts/dev-static.mjs</code> carries its own copies of both starters and was silently dropping
+ <code>--verbose</code>: it parsed the flag into <code>config.verbose</code> but never passed it on, so
+ verbose launches from that path were not verbose. It now threads the flag through to both services.
+</p>
+
+<h2><span class="n">04</span>Evidence</h2>
+<p>
+ Measured from real launches on this branch β€” <code>npm run dev --backend-only</code> against the
+ pinned automation 1.23.2, counting <code>[automation]</code> lines only so the comparison isolates the
+ service under discussion.
+</p>
+
+<table>
+ <tr><th>Run</th><th>Automation lines</th><th>ORM lines</th><th>Ready-at line</th></tr>
+ <tr><td><code>LOG_LEVEL=INFO</code> (previous default)</td><td>431</td><td>338</td><td>present</td></tr>
+ <tr><td>default (this PR)</td><td><strong>7</strong></td><td><strong>0</strong></td><td>present</td></tr>
+ <tr><td><code>--verbose</code></td><td>1344</td><td>338</td><td>present</td></tr>
+</table>
+
+<p>
+ The evidence image attached to the PR shows the same two panels rendered from those captured logs.
+ The tests assert the policy rather than the log text: which variable each launch path sets, that the
+ agent-server does not receive <code>AUTOMATION_LOG_LEVEL</code> (it does not read it), and that every
+ Uvicorn invocation in the entrypoint receives the resolved level.
+</p>
+
+<h2><span class="n">05</span>Compatibility and risk</h2>
+<ul>
+ <li><strong>Standalone deployments are unaffected.</strong> The automation service keeps its
+ <code>INFO</code> default; this PR only changes what Canvas passes when it spawns the service, plus
+ the Docker image's fallback for an unset variable.</li>
+ <li><strong>Not a breaking change for overrides.</strong> Anything already setting <code>LOG_LEVEL</code>
+ keeps working, because the launcher defers to it.</li>
+ <li><strong>Trade-off:</strong> a user who was relying on application <code>INFO</code> logs appearing
+ by default now needs <code>LOG_LEVEL=INFO</code>. That is the intended change; the noisy default was
+ the reported problem.</li>
+ <li><strong>Not addressed here:</strong> selecting <code>INFO</code> still raises third-party loggers,
+ because the pinned automation service silences <code>sqlalchemy.engine</code> but not
+ <code>sqlalchemy.orm</code> in its own <code>lifespan</code>. Fixing that belongs in the automation
+ repository and is tracked as a follow-up; see the PR notes.</li>
+</ul>
+
+<div class="foot">
+ Self-contained page, no external assets. Temporary review artifact under <code>.pr/</code>, removed
+ automatically after merge.
+</div>
+
+</div>
+</body>
+</html>
diff --git a/.pr/evidence.png b/.pr/evidence.png
new file mode 100644
index 0000000000..5872b9eb99
Binary files /dev/null and b/.pr/evidence.png differ
diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.ts
index 7d96573ab9..efafc93229 100644
--- a/__tests__/scripts/dev-with-automation.test.ts
+++ b/__tests__/scripts/dev-with-automation.test.ts
@@ -23,6 +23,7 @@ import { describe, expect, it, afterEach } from "vitest";
import {
buildAgentServerAutomationEnv,
buildAutomationCommand,
+ buildAutomationLogArgs,
buildAutomationTelemetryEnv,
buildAutomationRuntimeServicesInfo,
buildConfig,
@@ -43,8 +44,10 @@ import {
} from "../../scripts/dev-with-automation.mjs";
import {
buildAgentServerEnv,
+ buildBackendLogEnv,
buildSafeDevConfig,
resetPersistedSessionApiKeyCache,
+ uvicornLogLevel,
} from "../../scripts/dev-safe.mjs";
import { createRouter } from "../../scripts/proxy-utils.mjs";
@@ -1495,6 +1498,199 @@ describe("dev-with-automation CLI", () => {
});
});
+describe("backend logging defaults", () => {
+ // Minimal SafeDevConfig for buildAgentServerEnv; only the fields it reads
+ // matter, but it accesses them directly rather than via optional chaining.
+ const baseConfig = () => ({
+ cwd: process.cwd(),
+ backendPort: 18000,
+ vscodePort: 18001,
+ vscodeBasePath: "/vscode",
+ stateDir: "/tmp/state",
+ tmuxTmpDir: "/tmp/tmux",
+ conversationsPath: "/tmp/conversations",
+ workspacesPath: "/tmp/workspaces",
+ bashEventsDir: "/tmp/bash-events",
+ backendBaseUrl: "http://127.0.0.1:18000",
+ backendHost: "127.0.0.1",
+ workingDir: process.cwd(),
+ secretKey: "secret",
+ sessionApiKey: "session",
+ canvasToolsDir: "/tmp/tools",
+ extensionsDir: null,
+ });
+
+ it("quiets the automation service by default", () => {
+ const env = buildBackendLogEnv({ automation: true, env: {} });
+
+ expect(env.LOG_LEVEL).toBe("WARNING");
+ expect(env.AUTOMATION_LOG_LEVEL).toBe("WARNING");
+ });
+
+ it("leaves AUTOMATION_LOG_LEVEL unset for the agent-server", () => {
+ // The agent-server does not read AUTOMATION_LOG_LEVEL; setting it there
+ // would suggest it has an effect it does not.
+ const env = buildBackendLogEnv({ env: {} });
+
+ expect(env.LOG_LEVEL).toBe("WARNING");
+ expect(env).not.toHaveProperty("AUTOMATION_LOG_LEVEL");
+ });
+
+ it("honors an explicit LOG_LEVEL from the caller's environment", () => {
+ const env = buildBackendLogEnv({
+ automation: true,
+ env: { LOG_LEVEL: "INFO" },
+ });
+
+ expect(env.LOG_LEVEL).toBe("INFO");
+ expect(env.AUTOMATION_LOG_LEVEL).toBe("INFO");
+ });
+
+ it("lets AUTOMATION_LOG_LEVEL diverge from LOG_LEVEL", () => {
+ const env = buildBackendLogEnv({
+ automation: true,
+ env: { LOG_LEVEL: "ERROR", AUTOMATION_LOG_LEVEL: "DEBUG" },
+ });
+
+ expect(env.LOG_LEVEL).toBe("ERROR");
+ expect(env.AUTOMATION_LOG_LEVEL).toBe("DEBUG");
+ });
+
+ it("raises both services to DEBUG under --verbose, overriding the environment", () => {
+ const env = buildBackendLogEnv({
+ verbose: true,
+ automation: true,
+ env: { LOG_LEVEL: "ERROR" },
+ });
+
+ expect(env.LOG_LEVEL).toBe("DEBUG");
+ expect(env.AUTOMATION_LOG_LEVEL).toBe("DEBUG");
+ });
+
+ it("passes the same level to uvicorn as to the automation service", () => {
+ const args = buildAutomationLogArgs({ autoBackendPort: 18001 }, {});
+
+ expect(args).toEqual([
+ "--host",
+ "127.0.0.1",
+ "--port",
+ "18001",
+ "--log-level",
+ "warning",
+ ]);
+ });
+
+ it("passes debug to uvicorn under --verbose", () => {
+ const args = buildAutomationLogArgs(
+ { autoBackendPort: 18001, verbose: true },
+ {},
+ );
+
+ expect(args.at(-1)).toBe("debug");
+ });
+
+ // Uvicorn validates --log-level with a click.Choice and exits 2 on anything
+ // outside its set, which takes the whole dev stack down. The app accepts
+ // more than Uvicorn does, so an explicit override must be narrowed rather
+ // than forwarded verbatim.
+ describe("narrows the Uvicorn --log-level to a value Uvicorn accepts", () => {
+ const UVICORN_ACCEPTS = [
+ "critical",
+ "error",
+ "warning",
+ "info",
+ "debug",
+ "trace",
+ ];
+
+ it("keeps every level Uvicorn already accepts", () => {
+ for (const level of UVICORN_ACCEPTS) {
+ expect(uvicornLogLevel(level)).toBe(level);
+ expect(uvicornLogLevel(level.toUpperCase())).toBe(level);
+ }
+ });
+
+ it("maps the Python aliases Uvicorn rejects", () => {
+ expect(uvicornLogLevel("WARN")).toBe("warning");
+ expect(uvicornLogLevel("warn")).toBe("warning");
+ expect(uvicornLogLevel("FATAL")).toBe("critical");
+ expect(uvicornLogLevel("fatal")).toBe("critical");
+ });
+
+ it("maps numeric levels onto the nearest Uvicorn name", () => {
+ expect(uvicornLogLevel("50")).toBe("critical");
+ expect(uvicornLogLevel("40")).toBe("error");
+ expect(uvicornLogLevel("30")).toBe("warning");
+ expect(uvicornLogLevel("20")).toBe("info");
+ expect(uvicornLogLevel("10")).toBe("debug");
+ expect(uvicornLogLevel("5")).toBe("trace");
+ });
+
+ it("falls back to Uvicorn's own default for unrepresentable values", () => {
+ // `NOTSET` means "inherit", not "most verbose", and Uvicorn has no
+ // equivalent; the pre-PR launchers passed no --log-level at all, which
+ // left Uvicorn at `info`.
+ expect(uvicornLogLevel("NOTSET")).toBe("info");
+ expect(uvicornLogLevel("0")).toBe("info");
+ expect(uvicornLogLevel("")).toBe("info");
+ expect(uvicornLogLevel(undefined)).toBe("info");
+ expect(uvicornLogLevel("verbose")).toBe("info");
+ });
+
+ it("never returns a value outside Uvicorn's accepted set", () => {
+ const inputs = [
+ "WARN",
+ "FATAL",
+ "NOTSET",
+ "30",
+ "0",
+ "",
+ "bogus",
+ "999999999999999999999",
+ " 30 ",
+ "warning",
+ ];
+ for (const input of inputs) {
+ expect(UVICORN_ACCEPTS).toContain(uvicornLogLevel(input));
+ }
+ });
+
+ it("narrows an explicit LOG_LEVEL alias in the built args", () => {
+ // The regression: `LOG_LEVEL=WARN npm run dev` aborted Uvicorn.
+ const args = buildAutomationLogArgs(
+ { autoBackendPort: 18001 },
+ { LOG_LEVEL: "WARN" },
+ );
+
+ expect(args.at(-1)).toBe("warning");
+ });
+
+ it("leaves the app's LOG_LEVEL env untouched for an alias", () => {
+ // The app reads LOG_LEVEL through Python's logging module, which does
+ // accept WARN β€” only the Uvicorn argument is narrowed.
+ const env = buildBackendLogEnv({
+ automation: true,
+ env: { LOG_LEVEL: "WARN" },
+ });
+
+ expect(env.LOG_LEVEL).toBe("WARN");
+ expect(env.AUTOMATION_LOG_LEVEL).toBe("WARN");
+ });
+ });
+
+ it("gives the agent-server the quiet default without an opt-out needed", () => {
+ const env = buildAgentServerEnv(baseConfig(), { env: {} });
+
+ expect(env.LOG_LEVEL).toBe("WARNING");
+ });
+
+ it("raises the agent-server to DEBUG under --verbose", () => {
+ const env = buildAgentServerEnv(baseConfig(), { env: {}, verbose: true });
+
+ expect(env.LOG_LEVEL).toBe("DEBUG");
+ });
+});
+
describe("buildMarsWebEnv", () => {
it("puts the bridge on the ingress behind the session key, off the static child", () => {
const config = { sessionApiKey: "stack-key", marsWebBridge: true } as never;
diff --git a/__tests__/scripts/docker-log-level.test.ts b/__tests__/scripts/docker-log-level.test.ts
new file mode 100644
index 0000000000..6b15c22d41
--- /dev/null
+++ b/__tests__/scripts/docker-log-level.test.ts
@@ -0,0 +1,184 @@
+// @vitest-environment node
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../..",
+);
+const entrypoint = readFileSync(
+ path.join(repoRoot, "docker/entrypoint.sh"),
+ "utf-8",
+);
+const blockStart = "# >>> backend-log-level";
+const blockEnd = "# <<< backend-log-level";
+
+function logLevelBlock(): string {
+ const start = entrypoint.indexOf(blockStart);
+ const end = entrypoint.indexOf(blockEnd);
+ if (start === -1 || end === -1) {
+ throw new Error("Docker backend-log-level markers are missing");
+ }
+ return entrypoint.slice(start, end);
+}
+
+/** Resolve LOG_LEVEL / AUTOMATION_LOG_LEVEL exactly as the entrypoint does. */
+function resolveLogLevels(env: Record<string, string>): {
+ LOG_LEVEL?: string;
+ AUTOMATION_LOG_LEVEL?: string;
+} {
+ const script = [
+ "set -uo pipefail",
+ logLevelBlock(),
+ 'printf "LOG_LEVEL=%s\\n" "${LOG_LEVEL:-}"',
+ 'printf "AUTOMATION_LOG_LEVEL=%s\\n" "${AUTOMATION_LOG_LEVEL:-}"',
+ ].join("\n");
+
+ const result = spawnSync("bash", ["-c", script], {
+ env: { PATH: process.env.PATH ?? "", ...env },
+ encoding: "utf-8",
+ });
+
+ if (result.status !== 0) {
+ throw new Error(`bash failed: ${result.stderr}`);
+ }
+
+ const parsed: Record<string, string> = {};
+ for (const line of result.stdout.trim().split("\n")) {
+ const [key, value] = line.split("=");
+ parsed[key] = value;
+ }
+ return parsed;
+}
+
+/** Narrow a level exactly as the entrypoint does, via the marked block. */
+function uvicornLogLevel(level: string): string {
+ const script = [
+ "set -uo pipefail",
+ logLevelBlock(),
+ 'uvicorn_log_level "$1"',
+ ].join("\n");
+
+ const result = spawnSync("bash", ["-c", script, "bash", level], {
+ env: { PATH: process.env.PATH ?? "" },
+ encoding: "utf-8",
+ });
+
+ if (result.status !== 0) {
+ throw new Error(`bash failed: ${result.stderr}`);
+ }
+ return result.stdout;
+}
+
+describe("Docker backend log level", () => {
+ it("quiets both backends by default", () => {
+ const levels = resolveLogLevels({});
+
+ expect(levels.LOG_LEVEL).toBe("WARNING");
+ expect(levels.AUTOMATION_LOG_LEVEL).toBe("WARNING");
+ });
+
+ it("honors an explicit LOG_LEVEL and applies it to the automation service", () => {
+ const levels = resolveLogLevels({ LOG_LEVEL: "DEBUG" });
+
+ expect(levels.LOG_LEVEL).toBe("DEBUG");
+ expect(levels.AUTOMATION_LOG_LEVEL).toBe("DEBUG");
+ });
+
+ it("lets AUTOMATION_LOG_LEVEL diverge from LOG_LEVEL", () => {
+ const levels = resolveLogLevels({
+ LOG_LEVEL: "ERROR",
+ AUTOMATION_LOG_LEVEL: "INFO",
+ });
+
+ expect(levels.LOG_LEVEL).toBe("ERROR");
+ expect(levels.AUTOMATION_LOG_LEVEL).toBe("INFO");
+ });
+
+ it("passes the resolved level to every uvicorn invocation", () => {
+ // The automation service's --log-level governs the startup banner and
+ // per-request access lines, which LOG_LEVEL alone does not cover. The
+ // invocation must route the level through uvicorn_log_level, which both
+ // lowercases it and narrows it to a name Uvicorn accepts.
+ const code = entrypoint
+ .split("\n")
+ .filter((line) => !line.trimStart().startsWith("#"))
+ .join("\n");
+
+ // Each invocation is a backslash-continued command ending in `&`.
+ const invocations = code.match(
+ /uvicorn openhands\.automation\.app:app[\s\S]*?&\n/g,
+ );
+
+ expect(invocations).toHaveLength(2);
+ for (const invocation of invocations ?? []) {
+ expect(invocation).toContain("--log-level");
+ expect(invocation).toContain('uvicorn_log_level "${LOG_LEVEL}"');
+ }
+ });
+
+ // Uvicorn validates --log-level with a click.Choice and exits 2 on anything
+ // outside its set; the entrypoint runs without `set -e`, so a rejected value
+ // would leave Canvas shipped with the automation service unavailable.
+ describe("narrows --log-level to a value Uvicorn accepts", () => {
+ const UVICORN_ACCEPTS = [
+ "critical",
+ "error",
+ "warning",
+ "info",
+ "debug",
+ "trace",
+ ];
+
+ it("keeps every level Uvicorn already accepts", () => {
+ for (const level of UVICORN_ACCEPTS) {
+ expect(uvicornLogLevel(level)).toBe(level);
+ expect(uvicornLogLevel(level.toUpperCase())).toBe(level);
+ }
+ });
+
+ it("maps the Python aliases Uvicorn rejects", () => {
+ expect(uvicornLogLevel("WARN")).toBe("warning");
+ expect(uvicornLogLevel("FATAL")).toBe("critical");
+ });
+
+ it("maps numeric levels onto the nearest Uvicorn name", () => {
+ expect(uvicornLogLevel("50")).toBe("critical");
+ expect(uvicornLogLevel("40")).toBe("error");
+ expect(uvicornLogLevel("30")).toBe("warning");
+ expect(uvicornLogLevel("20")).toBe("info");
+ expect(uvicornLogLevel("10")).toBe("debug");
+ expect(uvicornLogLevel("5")).toBe("trace");
+ });
+
+ it("falls back to Uvicorn's own default for unrepresentable values", () => {
+ expect(uvicornLogLevel("NOTSET")).toBe("info");
+ expect(uvicornLogLevel("0")).toBe("info");
+ expect(uvicornLogLevel("")).toBe("info");
+ expect(uvicornLogLevel("bogus")).toBe("info");
+ });
+
+ it("never returns a value outside Uvicorn's accepted set", () => {
+ // Includes a value too large for `[` to compare as a signed integer,
+ // which would otherwise error out and emit nothing.
+ const inputs = [
+ "WARN",
+ "FATAL",
+ "NOTSET",
+ "30",
+ "030",
+ "0",
+ "",
+ "bogus",
+ "999999999999999999999",
+ ];
+ for (const input of inputs) {
+ expect(UVICORN_ACCEPTS).toContain(uvicornLogLevel(input));
+ }
+ });
+ });
+});
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 009f294876..20b7af955d 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -296,6 +296,55 @@ export OH_EXTRA_PYTHON_PATH="${OH_EXTRA_PYTHON_PATH:-/opt/agent-canvas/tools}"
export EXTENSIONS_PATH="${EXTENSIONS_PATH:-/opt/agent-canvas/node_modules/@openhands/extensions}"
AGENT_SERVER_IMPORT_MODULES="canvas_ui_tool"
+# Both backends default LOG_LEVEL to INFO, at which level they emit
+# library-internal startup chatter β€” the automation service alone prints
+# several hundred lines of SQLAlchemy ORM model-mapping output β€” that buries
+# the service URLs and readiness lines a user actually needs. Default to
+# WARNING so a plain `docker run` is readable, while an explicit LOG_LEVEL
+# still raises verbosity for troubleshooting.
+#
+# >>> backend-log-level: extracted by __tests__/scripts/docker-log-level.test.ts
+# >>> β€” keep the markers.
+export LOG_LEVEL="${LOG_LEVEL:-WARNING}"
+export AUTOMATION_LOG_LEVEL="${AUTOMATION_LOG_LEVEL:-${LOG_LEVEL}}"
+
+# Narrow a logging level to something Uvicorn's `--log-level` accepts.
+#
+# The app reads LOG_LEVEL through Python's logging module, which also
+# understands the aliases WARN/FATAL/NOTSET and numeric levels; Uvicorn
+# validates the flag with a click.Choice over the names below and exits 2 on
+# anything else, which would take the automation service down. Unrepresentable
+# values fall back to `info`, Uvicorn's own default.
+uvicorn_log_level() {
+ local _uvicorn_level
+ _uvicorn_level="$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')"
+ case "${_uvicorn_level}" in
+ critical | error | warning | info | debug | trace) printf '%s' "${_uvicorn_level}" ;;
+ warn) printf 'warning' ;;
+ fatal) printf 'critical' ;;
+ '' | *[!0-9]*) printf 'info' ;;
+ *)
+ # Strip leading zeros so `030` reads as 30. Only two digits can fall
+ # below 50, so anything longer is clamped β€” `[` compares as a signed
+ # integer and errors out on a value it cannot hold.
+ while [ "${#_uvicorn_level}" -gt 1 ] && [ "${_uvicorn_level#0}" != "${_uvicorn_level}" ]; do
+ _uvicorn_level="${_uvicorn_level#0}"
+ done
+ # Python's NOTSET is 0 and means "inherit", not "most verbose".
+ if [ "${_uvicorn_level}" = "0" ]; then printf 'info'
+ elif [ "${#_uvicorn_level}" -gt 2 ]; then printf 'critical'
+ elif [ "${_uvicorn_level}" -ge 50 ]; then printf 'critical'
+ elif [ "${_uvicorn_level}" -ge 40 ]; then printf 'error'
+ elif [ "${_uvicorn_level}" -ge 30 ]; then printf 'warning'
+ elif [ "${_uvicorn_level}" -ge 20 ]; then printf 'info'
+ elif [ "${_uvicorn_level}" -ge 10 ]; then printf 'debug'
+ else printf 'trace'
+ fi
+ ;;
+ esac
+}
+# <<< backend-log-level
+
# Track child PIDs so we can clean up on exit.
PIDS=()
@@ -360,12 +409,14 @@ fi
if command -v uvicorn >/dev/null 2>&1; then
uvicorn openhands.automation.app:app \
--host 0.0.0.0 \
- --port "$AUTOMATION_PORT" &
+ --port "$AUTOMATION_PORT" \
+ --log-level "$(uvicorn_log_level "${LOG_LEVEL}")" &
PIDS+=($!)
elif python -c "import openhands.automation" 2>/dev/null; then
python -m uvicorn openhands.automation.app:app \
--host 0.0.0.0 \
- --port "$AUTOMATION_PORT" &
+ --port "$AUTOMATION_PORT" \
+ --log-level "$(uvicorn_log_level "${LOG_LEVEL}")" &
PIDS+=($!)
else
log "WARNING: Automation server not found, skipping."
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index e3401391a9..1f79b0f816 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -806,6 +806,130 @@ export function buildAgentServerTelemetryEnv(env = process.env) {
return result;
}
+/**
+ * Default log level for the backends Canvas launches.
+ *
+ * Both the agent-server and the automation service read `LOG_LEVEL` and default
+ * it to `INFO`. At `INFO` they emit library-internal startup chatter β€” most
+ * visibly SQLAlchemy's ORM model-mapping output, several hundred lines of it
+ * from the automation service alone β€” that buries the few lines a user needs
+ * (service URLs, readiness, real warnings). `WARNING` keeps actionable signals
+ * such as the automation workspace-retention warning while dropping the rest.
+ */
+export const DEFAULT_BACKEND_LOG_LEVEL = "WARNING";
+
+/**
+ * The log level to use for a backend Canvas spawns, before it is applied to
+ * any particular variable.
+ *
+ * Exported so the Uvicorn `--log-level` flag (which takes a lowercase name and
+ * governs the startup banner and per-request access lines, separately from the
+ * app's `LOG_LEVEL`) can be kept in step with the service level.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - Raise to DEBUG.
+ * @param {Record<string, string | undefined>} [options.env] - Source environment.
+ * @returns {string} An uppercase logging level name
+ */
+export function backendLogLevel(options = {}) {
+ const { verbose = false, env = process.env } = options;
+ return verbose ? "DEBUG" : env.LOG_LEVEL || DEFAULT_BACKEND_LOG_LEVEL;
+}
+
+/** The only names Uvicorn's `--log-level` accepts; anything else exits 2. */
+export const UVICORN_LOG_LEVELS = [
+ "critical",
+ "error",
+ "warning",
+ "info",
+ "debug",
+ "trace",
+];
+
+// Python logging aliases that `logging.getLevelNamesMapping()` accepts but
+// Uvicorn does not.
+const UVICORN_LEVEL_ALIASES = { warn: "warning", fatal: "critical" };
+
+// Python level numbers, highest first, mapped to the Uvicorn name at or below
+// them (Uvicorn's `trace` sits below `debug`).
+const UVICORN_LEVEL_BY_NUMBER = [
+ [50, "critical"],
+ [40, "error"],
+ [30, "warning"],
+ [20, "info"],
+ [10, "debug"],
+ [5, "trace"],
+];
+
+/**
+ * Narrow a logging level to something Uvicorn's `--log-level` accepts.
+ *
+ * The app reads `LOG_LEVEL` through Python's logging module, which also
+ * understands `WARN`, `FATAL`, numeric levels and `NOTSET`; Uvicorn validates
+ * the flag with a `click.Choice` over {@link UVICORN_LOG_LEVELS} and exits 2 on
+ * anything else, taking the service β€” and with it the dev stack β€” down. So the
+ * env value keeps its raw form and only the Uvicorn argument is narrowed here.
+ *
+ * Values Uvicorn cannot represent fall back to `info`, Uvicorn's own default,
+ * which is what the launchers passed before they set the flag at all.
+ *
+ * @param {string | number | undefined} level
+ * @returns {string} A name from {@link UVICORN_LOG_LEVELS}
+ */
+export function uvicornLogLevel(level) {
+ const name = String(level ?? "")
+ .trim()
+ .toLowerCase();
+
+ if (UVICORN_LOG_LEVELS.includes(name)) return name;
+ if (UVICORN_LEVEL_ALIASES[name]) return UVICORN_LEVEL_ALIASES[name];
+
+ if (/^\d+$/.test(name)) {
+ const numeric = Number(name);
+ // Python's NOTSET is 0 and means "inherit", not "most verbose"; treat it
+ // like the `notset` name and fall back to Uvicorn's own default. Uvicorn's
+ // lowest name is `trace`, which covers everything below `debug`.
+ if (numeric === 0) return "info";
+ const match = UVICORN_LEVEL_BY_NUMBER.find(([value]) => numeric >= value);
+ return match ? match[1] : "trace";
+ }
+
+ return "info";
+}
+
+/**
+ * Logging environment for a backend Canvas spawns.
+ *
+ * Defaults to {@link DEFAULT_BACKEND_LOG_LEVEL} so a plain launch is readable,
+ * while any explicit `LOG_LEVEL` / `AUTOMATION_LOG_LEVEL` in the caller's
+ * environment still wins, so troubleshooting needs no code change. `--verbose`
+ * opts back into `DEBUG`.
+ *
+ * `AUTOMATION_LOG_LEVEL` is set only for the automation service: the
+ * agent-server does not read it, and setting it there would be misleading.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - Raise both services to DEBUG.
+ * @param {boolean} [options.automation] - Also set AUTOMATION_LOG_LEVEL.
+ * @param {Record<string, string | undefined>} [options.env] - Source environment.
+ * @returns {Record<string, string>} Logging env vars for the backend process
+ */
+export function buildBackendLogEnv(options = {}) {
+ const { verbose = false, automation = false, env = process.env } = options;
+ const level = backendLogLevel({ verbose, env });
+
+ return {
+ LOG_LEVEL: level,
+ ...(automation
+ ? {
+ AUTOMATION_LOG_LEVEL: verbose
+ ? "DEBUG"
+ : env.AUTOMATION_LOG_LEVEL || level,
+ }
+ : {}),
+ };
+}
+
/**
* Build the environment variables object for spawning the agent-server process.
*
@@ -826,15 +950,17 @@ export function buildAgentServerTelemetryEnv(env = process.env) {
* opts in without one.
*
* @param {ReturnType<typeof buildSafeDevConfig>} config - Config from buildSafeDevConfig
- * @param {{vscodeBasePath?: string | null, env?: Record<string, string | undefined>}} [options]
+ * @param {{vscodeBasePath?: string | null, env?: Record<string, string | undefined>, verbose?: boolean}} [options]
* @param {string | null} [options.vscodeBasePath] - Opt into prefix-mode by
* passing the path prefix the caller also routes to `config.vscodePort`.
* @param {Record<string, string | undefined>} [options.env] - Source
* environment for the telemetry mapping (defaults to `process.env`).
+ * @param {boolean} [options.verbose] - Raise the agent-server to DEBUG
+ * logging instead of the default `WARNING` (see buildBackendLogEnv).
* @returns {Record<string, string>} Environment variables for agent-server
*/
export function buildAgentServerEnv(config, options = {}) {
- const { vscodeBasePath = null, env = process.env } = options;
+ const { vscodeBasePath = null, env = process.env, verbose = false } = options;
const conversationRuntimeEnv = Object.fromEntries(
[
"OH_CONVERSATION_RUNTIME",
@@ -850,6 +976,7 @@ export function buildAgentServerEnv(config, options = {}) {
);
return {
...buildAgentServerTelemetryEnv(env),
+ ...buildBackendLogEnv({ verbose, env }),
...conversationRuntimeEnv,
...(env.VITE_ENABLE_BROWSER_TOOLS === "false"
? { OH_ENABLE_BROWSER: env.OH_ENABLE_BROWSER || "false" }
diff --git a/scripts/dev-static.mjs b/scripts/dev-static.mjs
index 26628c3d81..f13621335c 100644
--- a/scripts/dev-static.mjs
+++ b/scripts/dev-static.mjs
@@ -47,6 +47,9 @@ import {
buildAgentServerCommand,
buildSafeDevConfig,
buildAgentServerEnv,
+ backendLogLevel,
+ uvicornLogLevel,
+ buildBackendLogEnv,
formatMissingUvxGuidance,
isPortBusy,
releaseStaleConversationLeases,
@@ -171,7 +174,7 @@ OPTIONS:
--automation-ref <ref> Git ref for automation backend (default: main)
--automation-repo <url> Git repo URL for automation
--skip-build Reuse existing build/ directory (faster restart)
- -v, --verbose Show detailed output
+ -v, --verbose Set backend log level to DEBUG (default: WARNING)
-h, --help Show this help
ENVIRONMENT VARIABLES:
@@ -179,6 +182,11 @@ ENVIRONMENT VARIABLES:
OH_AUTOMATION_GIT_REF Alternative to --automation-ref
OH_AGENT_SERVER_GIT_REF Git ref for agent-server SDK
OH_SECRET_KEY Secret key for sessions
+ LOG_LEVEL Log level for both backends (default: WARNING)
+ Python names and aliases both work; aliases and
+ numbers are mapped onto Uvicorn's own set.
+ AUTOMATION_LOG_LEVEL Log level for the automation service only
+ (default: LOG_LEVEL)
ACCESS POINTS:
Main UI: http://localhost:PORT/
@@ -341,6 +349,7 @@ function startAgentServer(config) {
// same prefix against `config.vscodePort`.
...buildAgentServerEnv(safeConfig, {
vscodeBasePath: config.vscodeBasePath,
+ verbose: config.verbose,
}),
...buildAgentServerAutomationEnv(config),
};
@@ -373,6 +382,8 @@ function buildAutomationBackendEnv(config, env = process.env) {
AUTOMATION_WORKSPACE_BASE: join(config.stateDir, "workspaces"),
AUTOMATION_LOCAL_API_KEY: config.sessionApiKey,
...buildAutomationTelemetryEnv(env),
+ // Quiet the automation service by default; see buildBackendLogEnv.
+ ...buildBackendLogEnv({ verbose: config.verbose, automation: true, env }),
AUTOMATION_CORS_ORIGINS: `http://localhost:${config.ingressPort},http://127.0.0.1:${config.ingressPort},http://localhost:3001,http://127.0.0.1:3001`,
FILE_STORE: "local",
LOCAL_STORAGE_PATH: join(config.stateDir, "storage"),
@@ -399,6 +410,10 @@ function startAutomationBackend(config) {
"0.0.0.0",
"--port",
config.autoBackendPort.toString(),
+ // Uvicorn's own level; see uvicornLogLevel. Uvicorn rejects the Python
+ // aliases and numeric levels the app itself accepts, so narrow it.
+ "--log-level",
+ uvicornLogLevel(backendLogLevel({ verbose: config.verbose })),
],
{
cwd: config.stateDir,
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index d0ff0fab7e..1a957ab414 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -57,6 +57,9 @@ import {
buildAgentServerCommand,
buildSafeDevConfig,
buildAgentServerEnv,
+ buildBackendLogEnv,
+ backendLogLevel,
+ uvicornLogLevel,
buildNpmScriptCommand,
buildRuntimeServicesInfo,
buildUvxPythonArgs,
@@ -260,7 +263,7 @@ OPTIONS:
--dynamic Force Vite dev server when a wrapper defaults static
--frontend-only Start only the frontend behind ingress
--backend-only Start only agent-server + automation behind ingress
- -v, --verbose Show detailed output
+ -v, --verbose Set backend log level to DEBUG (default: WARNING)
-h, --help Show this help
ENVIRONMENT VARIABLES:
@@ -273,6 +276,11 @@ ENVIRONMENT VARIABLES:
OH_AGENT_SERVER_GIT_REF Git ref for agent-server SDK (overrides default version)
OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server
OH_SECRET_KEY Secret key for sessions
+ LOG_LEVEL Log level for both backends (default: WARNING)
+ Python names and aliases both work; aliases and
+ numbers are mapped onto Uvicorn's own set.
+ AUTOMATION_LOG_LEVEL Log level for the automation service only
+ (default: LOG_LEVEL)
SECRETS:
The session API key is automatically seeded into agent-server secrets
@@ -967,6 +975,7 @@ function startAgentServer(config) {
// advertises resolves to the editor port on the canvas origin.
...buildAgentServerEnv(safeConfig, {
vscodeBasePath: config.vscodeBasePath,
+ verbose: config.verbose,
}),
...buildAgentServerAutomationEnv(config),
OPENHANDS_REMOTE_WS_READY_REQUIRED:
@@ -1000,6 +1009,32 @@ function startAgentServer(config) {
);
}
+/**
+ * Extra CLI arguments for the automation service, on top of the uvicorn
+ * invocation the command builder already produced.
+ *
+ * `--log-level` is Uvicorn's own level, separate from the app's `LOG_LEVEL`: it
+ * governs the startup banner and per-request access lines. Keeping it in step
+ * with the service level means a default launch is quiet while `--verbose`
+ * still shows request traffic. The value is narrowed by
+ * {@link uvicornLogLevel}, since Uvicorn rejects the Python aliases and numeric
+ * levels the app itself accepts.
+ *
+ * @param {{autoBackendPort: number, verbose?: boolean}} config
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function buildAutomationLogArgs(config, env = process.env) {
+ return [
+ "--host",
+ "127.0.0.1",
+ "--port",
+ config.autoBackendPort.toString(),
+ "--log-level",
+ uvicornLogLevel(backendLogLevel({ verbose: config.verbose, env })),
+ ];
+}
+
function startAutomationBackend(config) {
logService(
"automation",
@@ -1010,22 +1045,23 @@ function startAutomationBackend(config) {
const automationCmd = buildAutomationCommand(process.env);
logService("automation", `Using ${automationCmd.source}`, c.dim);
+ // Quiet the automation service by default; see buildBackendLogEnv.
+ const logEnv = buildBackendLogEnv({
+ verbose: config.verbose,
+ automation: true,
+ });
+
return spawnService(
"automation",
automationCmd.command,
- [
- ...automationCmd.args,
- "--host",
- "127.0.0.1",
- "--port",
- config.autoBackendPort.toString(),
- ],
+ [...automationCmd.args, ...buildAutomationLogArgs(config)],
{
cwd: config.stateDir,
env: {
// Force UTF-8 for all Python file I/O (same reason as agent-server;
// see buildAgentServerEnv in dev-safe.mjs).
PYTHONUTF8: "1",
+ ...logEnv,
OPENHANDS_REMOTE_WS_READY_REQUIRED:
process.env.OPENHANDS_REMOTE_WS_READY_REQUIRED || "false",
// The URL the automation backend itself uses to call the