Skip to Content
User GuideManaged Agent server configuration reference

Managed Agent server configuration reference

Every setting of the Managed Agent control plane, qwen-managed-agent-server. The page is generated from the server build’s configuration metadata, the packaged application.yml and packages/managed-agent-server/configuration-descriptions.json; edit that file, not this page, and regenerate:

mvn -f packages/managed-agent-server/pom.xml -DskipTests clean process-classes && node scripts/generate-managed-agent-configuration-reference.mjs
  • Variable is the environment variable the packaged application.yml maps to the property, which server.env sets. A property without one is set in config/application.yml, which the launchers load when it exists; see the deployment guide.
  • Default is what the packaged application.yml sets, or else the server’s own default. (empty) is an empty value, follows names the property whose value is the default, and — means no value: the description says what applies then.
  • A duration is a number with a unit, such as 500ms, 30s, 10m, 24h or 30d. Always write the unit: a bare number does not mean the same unit everywhere.
  • A list takes comma-separated values in a variable. A YAML list or YAML map can only be set in a configuration file.

Database and listener

Spring settings the packaged application.yml maps to variables, and the listener port.

PropertyVariableTypeDefaultDescription
server.addressQWEN_MANAGED_AGENT_SERVER_ADDRESSstring127.0.0.1The address the public HTTP listener binds to. A non-loopback address needs qwen.managed-agent.auth.mode=signed; under auto or open mode startup refuses it unless qwen.managed-agent.auth.allow-insecure-bind is true. While the internal routes share this listener (no qwen.managed-agent.internal-server.port) and the Session Store or tool publication is on, a non-loopback address also needs qwen.managed-agent.session-store.binding-key unless qwen.managed-agent.auth.allow-insecure-bind is true. The managed-local profile refuses any non-loopback address.
server.portSERVER_PORTinteger8080The port of the public listener the API and /actuator/health are served on. Spring Boot reads it from SERVER_PORT.
spring.datasource.druid.max-activeQWEN_MANAGED_AGENT_DB_MAX_POOL_SIZEinteger20How many connections the control plane’s Druid database pool may hold at most. When all are busy, a request for a connection waits up to 30 seconds and then fails. Ignored under the managed-local profile, whose pool is fixed at 20.
spring.datasource.passwordSPRING_DATASOURCE_PASSWORDstring(empty)The password of spring.datasource.username. A secret: keep it in a private environment file such as server.env, not on a command line.
spring.datasource.urlSPRING_DATASOURCE_URLstringjdbc:mysql://127.0.0.1:3306/qwen_managed_agentThe JDBC URL of the MySQL 8 database that holds the control plane’s state; Flyway applies the schema migrations to it at startup. The managed-local profile replaces it with a private H2 file database and refuses any other URL.
spring.datasource.usernameSPRING_DATASOURCE_USERNAMEstringqwenThe database user the control plane connects as. Besides rights on the control plane’s database, it needs SELECT on performance_schema.user_variables_by_thread, which the preflight --check verifies.

qwen.managed-agent

Top-level settings of the Managed Agent server: the built-in agent revision, what stored AgentDefinitions may select, the Session model catalog, the trusted actor header and the service account, alongside the nested sections.

PropertyVariableTypeDefaultDescription
agent-revisionQWEN_MANAGED_AGENT_REVISIONstring1The revision label of the built-in qwen-code agent, pinned on each Session that uses it; a request naming any other revision of qwen-code is refused. Must be 1 to 128 characters (startup refusal).
child-relay.scan-delay—duration2sHow long the child result relay waits between passes; each pass drives child agent and workflow runs whose creation or result delivery to the parent Session is unfinished. Does nothing unless qwen.managed-agent.runtime-broker.enabled is true. Accepts a duration such as 2s; a plain number is milliseconds.
child-workspace.scan-delay—duration2sHow long the child Workspace pass waits between runs; each run resumes unfinished child Workspace Git steps (prepare, merge, apply, discard). Does nothing unless qwen.managed-agent.runtime-broker.child-workspaces-enabled is true. Accepts a duration such as 2s; a plain number is milliseconds.
definition-modelsQWEN_MANAGED_AGENT_DEFINITION_MODELSlist(empty)The model IDs a stored AgentDefinition may name in model.id, as a comma-separated list; a Session whose definition names any other model is refused at admission. Each ID should match a model provider route configured in the Harness. Empty admits only definitions without a model.
definition-tool-profilesQWEN_MANAGED_AGENT_DEFINITION_TOOL_PROFILESlisthosted-workspace-files/1The hosted tool profiles a stored AgentDefinition may select in tools, as a comma-separated list (such as hosted-workspace-files/1, hosted-workspace-shell/1 or hosted-workspace-mcp/1); a Session whose definition selects another profile is refused at admission. hosted-workspace-team-lead/1 and Shell profiles other than hosted-workspace-shell/1 are always refused, as is a Shell profile whose approval mode is yolo. Preflight checks that the Harness supports each listed profile.
message-relay.scan-delay—duration2sHow long the Session message relay waits between passes; each pass moves pending messages between Sessions (handover, receipt, acceptance) and settles those that cannot be delivered. Skipped on a node without an available Hosted Harness. Accepts a duration such as 2s; a plain number is milliseconds.
model-catalog—YAML list(empty)The models offered for Sessions of the built-in qwen-code agent, selectable at Session creation and changeable later by a Workspace operator. A list of objects with model-id (a model ID configured in the Harness; required, unique, at most 512 bytes) and label (display name, defaults to model-id, at most 512 characters); an invalid or duplicate entry is refused at startup. Set it in a YAML configuration file; there is no environment variable. Selection also needs qwen.managed-agent.harness.workspace-files-enabled and Harness support.
model-config-base-urls—YAML list(empty)Exact HTTP(S) base URLs permitted for complete Session model configurations, set as a YAML list. Empty disables admission of new configurations. Public creation accepts model_config; WebShell creation accepts modelConfig. Requires the Session Store, Harness capability session-model-config/1 and a SecretProtector (provided by the enabled Runtime Broker and its credential key ring in the standard server). Model IDs and API keys need no Harness registration. See the Session model configuration design.
service-userQWEN_MANAGED_AGENT_SERVICE_USERstring(empty)The operating-system account the server runs as. Only the preflight check reads it: it confirms the account exists and checks that the configuration and credentials files are readable by that account rather than by the account running preflight. Empty checks access as the account running preflight.
session-worktree.scan-delay—duration1000How long the Session worktree pass waits between runs; each run resumes pending per-Session Git worktree steps and fails the initial Turns of Sessions whose worktree could not be prepared. Accepts a duration such as 1s; a plain number is milliseconds.
trusted-actor-headerQWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADERstring(empty)The name of a request header (for example X-Qwen-Actor-Id) whose value is trusted as the caller’s actor ID, together with X-Qwen-Tenant-Id, when no upstream principal is present. Used only in open authentication mode; combining it with signed mode is refused at startup. In open mode, qwen.managed-agent.runtime-broker.local-directory-import-enabled requires it. Never set it where untrusted clients can reach the server. Empty disables it.
wake-recovery.scan-delay—duration2sHow long the wake recovery scan waits between passes; each pass finds up to eight Sessions holding committed inputs that no writer owns and reattaches them so their wake runs. Runs only with qwen.managed-agent.session-store.enabled and an available Hosted Harness. Accepts a duration such as 2s; a plain number is milliseconds.

qwen.managed-agent.artifacts

Projection of Hosted Shell tool results into public tool results and downloadable stdout/stderr artifacts, and the limits on reading their content.

PropertyVariableTypeDefaultDescription
enabled—booleanfalseWhether tool results are projected into public tool results and artifacts, and whether the artifact read API is served. Reads answer not found unless qwen.managed-agent.tool-publication.enabled is also true, and they require an authenticated actor. Even while it is false, committed tool receipts are still recorded for projection, so turning it on later also projects the tool results recorded while it was off. Sessions created through the private CSI lane (the csi-session admin command) are the exception: their receipts are never recorded, so their tool results are never projected.
max-concurrent-reads—integer4How many artifact content downloads this server process serves at once; a download beyond that gets HTTP 429 artifact_read_limit with Retry-After: 1. Must be at least 1 (startup refusal).
projection-interval—duration1000How often the tool-result projection pass runs; each pass projects up to 8 pending tool results into public tool results and artifacts. A plain number is milliseconds; a value with a unit such as 1s is also accepted. The pass does nothing unless qwen.managed-agent.artifacts.enabled is true.
publish-original—booleanfalseWhether projection publishes the sealed stdout and stderr streams of a tool result as downloadable artifacts, and whether an actor who can read the Session may download them. Requires qwen.managed-agent.artifacts.enabled.
publish-preview—booleanfalseWhether a projected tool result also carries a short text preview (at most the first 8 KiB of one stream, with ANSI and control characters removed) that every Session reader sees. Requires qwen.managed-agent.artifacts.publish-original.
read-revalidation-interval—duration5sHow often an in-flight artifact download re-checks the caller’s access (Workspace grant, read policy, Session state); PT0S checks before every chunk. After a revocation, what is written before the next check still reaches the client: up to one window’s worth of a streaming download, or a whole Range response of at most 1 MiB, which is written in one piece after its last check. Once a check denies, nothing more is written. A bare number is seconds.
read-timeout—duration2mHow long one artifact content download may take in total; the limit is checked between chunks: a download that exceeds it before its first chunk gets 503 artifact_unavailable, and one already streaming is cut off mid-body. Whatever this value, the download also ends the same way when its stream from storage receives nothing for 50 seconds (the OSS client’s default socket timeout, which no setting changes; a request to open the object that times out is first retried up to three times while this limit allows), or when the gap between two chunks lets its lease on the stored output lapse: the lease is renewed as chunks are read, so a gap of more than 90 seconds can end it and one of two minutes always does. Must be positive (startup refusal). A bare number is seconds.

qwen.managed-agent.auth

How the public API authenticates requests, open or HMAC-signed, and the startup guards that refuse unauthenticated or plaintext exposure beyond loopback.

PropertyVariableTypeDefaultDescription
allow-insecure-bindQWEN_MANAGED_AGENT_AUTH_ALLOW_INSECURE_BINDbooleanfalseWhether to override the startup guards against unauthenticated or plaintext exposure: it lets open or auto mode serve a non-loopback server.address, the internal surface leave loopback without qwen.managed-agent.session-store.binding-key, and qwen.managed-agent.harness.base-url or qwen.managed-agent.tool-publication.service-base-url use plaintext http to a remote host. It does not lift the Harness pool TLS rule or the local directory import loopback rule. The preflight check warns while it is set.
allowed-driftQWEN_MANAGED_AGENT_AUTH_ALLOWED_DRIFTduration5mHow far the X-Qwen-Signature-Timestamp of a signed request may differ from the server clock, in either direction, before the request is rejected with 401. Used only in signed mode and compared in whole seconds. Startup refuses less than 1s. A number without a unit is read as milliseconds.
max-signed-body-bytes—integer10485760The largest request body, in bytes, that signed mode buffers to verify its signature; a larger body is answered 413 payload_too_large. Extension archive uploads have their own 100 MiB limit. Startup refuses a value below 1 in signed mode.
modeQWEN_MANAGED_AGENT_AUTH_MODEstringautoHow public API requests are authenticated, case-insensitive: open trusts the tenant header (and the optional trusted actor header), signed requires an HMAC-SHA256 signature keyed by qwen.managed-agent.auth.signing-key, and auto acts as open on a loopback server.address (an unset address counts as non-loopback). Startup refuses auto or open on any other address unless qwen.managed-agent.auth.allow-insecure-bind is true, and refuses other values. The managed-local profile requires signed.
signing-keyQWEN_MANAGED_AGENT_AUTH_SIGNING_KEYstring(empty)The secret HMAC-SHA256 key with which signed clients sign each public request (X-Qwen-Signature). Read only in signed mode, where startup refuses a key shorter than 32 bytes (UTF-8), a key equal to qwen.managed-agent.session-store.binding-key, and any qwen.managed-agent.trusted-actor-header.

qwen.managed-agent.automation

The automation runtime: the scanner that fires scheduled automation definitions, its lease, its slot window and its concurrency.

PropertyVariableTypeDefaultDescription
concurrency—integer4How many unfinished runs one automation definition with overlap policy allow may hold at once; a further due slot is recorded skipped with reason count_limit. Startup refuses a value below 1 when qwen.managed-agent.automation.enabled is true.
enabledQWEN_MANAGED_AGENT_AUTOMATION_ENABLEDbooleanfalseWhether the automation scanner runs and the automation create, update, retire and run routes are admitted; while off, those routes answer 409 automation_unavailable and the read routes still answer. Those routes also need qwen.managed-agent.session-store.enabled. When on, startup refuses non-positive automation counts and durations.
late-toleranceQWEN_MANAGED_AGENT_AUTOMATION_LATE_TOLERANCEduration5mHow late a due slot may be when the scanner sees it and still fire as scheduled. An older slot follows the definition’s catch-up policy (none, latest or bounded) and is otherwise recorded missed. Startup refuses a non-positive value when automation is enabled. A plain number is milliseconds.
leaseQWEN_MANAGED_AGENT_AUTOMATION_LEASEduration60sHow long a scanner or a manual run holds an automation definition’s lease, counted from its claim of that definition; once it lapses another node may claim the definition, and from that claim on the earlier holder’s writes to it are refused. Startup refuses a non-positive value when automation is enabled. A plain number is milliseconds.
lookbackQWEN_MANAGED_AGENT_AUTOMATION_LOOKBACKduration24hHow far back the scanner derives a definition’s due slots; slots older than this, or older than the definition’s arming, are neither fired nor recorded, which bounds every catch-up. Startup refuses a non-positive value when automation is enabled. A plain number is milliseconds.
max-slots-per-tick—integer1000How many due slots the scanner keeps per definition in one tick; when the lookback window holds more, the oldest are cut and a warning is logged. The limit does not shorten the scan itself: the scanner still checks every minute from where its previous tick for the definition stopped, up to the whole lookback window. Startup refuses a value below 1 when qwen.managed-agent.automation.enabled is true.
scan-delayQWEN_MANAGED_AGENT_AUTOMATION_SCAN_DELAYduration10sHow long the automation scanner waits between the end of one tick and the start of the next. Startup refuses a non-positive value when automation is enabled. A plain number is milliseconds.
scanner-threads—integer4How many definition rows one scanner tick works in parallel; the tick waits for all of them before the next tick starts. Because a lease is not counted from the tick’s start (see qwen.managed-agent.automation.lease), a long tick hands out no already-expired lease. Startup refuses a value below 1 when qwen.managed-agent.automation.enabled is true.

qwen.managed-agent.channels

The trusted channel adapter surface on the internal listener and the lease on outbound delivery claims.

PropertyVariableTypeDefaultDescription
claim-leaseQWEN_MANAGED_AGENT_CHANNELS_CLAIM_LEASEduration10mHow long a channel adapter’s claim on an outbound delivery stays valid without a receipt. Once it lapses, the reconcile pass records the delivery’s outcome as unknown and never resends it automatically. A plain number is seconds.
enabledQWEN_MANAGED_AGENT_CHANNELS_ENABLEDbooleanfalseWhether the trusted channel adapter routes under /internal/managed-channels/ (register, disconnect, inbound events, delivery claims, receipts and resends) are served. They authenticate by the tenant header alone, so startup refuses it unless qwen.managed-agent.internal-server.port sets a separate internal listener.
scan-delay—duration30sHow long the channel reconcile pass waits between runs; each run settles up to 50 outbound delivery claims older than qwen.managed-agent.channels.claim-lease as unknown. Accepts a duration such as 30s; a plain number is milliseconds.

qwen.managed-agent.dispatch

Leases, retry backoff and retry budgets for the work the control plane hands to the Hosted Harness, such as Turns, Session lifecycle operations and Action responses.

PropertyVariableTypeDefaultDescription
lease-duration—duration60sHow long a node’s lease on dispatched work (a Turn, Session lifecycle operation, Action response, task cancel, rename or context compression) lasts before another node may take it over; Turn, lifecycle operation, Action response and task cancel holders renew it while working, but a rename or context compression does not. Startup refuses a value below twice qwen.managed-agent.dispatch.lease-renew-interval. A plain number is seconds.
lease-renew-interval—duration20sHow often a node renews its lease on a Turn it is running; Action response delivery renews at this interval or a third of qwen.managed-agent.dispatch.lease-duration, whichever is shorter. Startup refuses a value under one millisecond or above half the lease duration. A plain number is seconds.
max-operation-retries—integer10How many failed delivery attempts a Session lifecycle operation (such as close) or an Action response gets before it is recorded as failed; a close whose request already reached the Harness gets four times as many, and a close still waiting on a live journal writer, a Harness restart or the daemon is shown as blocked and keeps retrying instead. Startup refuses a negative value.
max-post-admission-retries—integer10How many failed attempts a Turn gets after its submission to the Hosted Harness was attempted; past it the Turn fails, normally with hosted_harness_unavailable_after_admission, because it may already have run. Startup refuses a negative value or one below qwen.managed-agent.dispatch.max-pre-admission-retries.
max-pre-admission-retries—integer5How many failed attempts a Turn gets before its submission to the Hosted Harness is attempted; past it the Turn fails, normally with hosted_harness_unavailable. It also bounds how often a Turn is deferred while Workspace files are unavailable. Startup refuses a negative value or one above qwen.managed-agent.dispatch.max-post-admission-retries.
retry-initial-delay—duration1sHow long dispatch work waits before its first retry; each further retry doubles the wait up to qwen.managed-agent.dispatch.retry-max-delay. Used for Turns, Session lifecycle operations, Action responses, task cancels and renames. Startup refuses a zero or negative value. A plain number is seconds.
retry-max-delay—duration1mHow long dispatch work waits at most between retries; the doubling backoff that starts at qwen.managed-agent.dispatch.retry-initial-delay stops growing here. Startup refuses a value below the initial delay. A plain number is seconds.
scan-delay—duration1sHow long the dispatch recovery passes wait between runs. Each run re-drives due work: retryable or expired Turns, Session lifecycle operations, Action responses, task cancels, renames, context compressions, parked operations and owed Hosted cleanup. Accepts a duration such as 1s; a plain number is milliseconds.

qwen.managed-agent.event-transport

The optional RocketMQ LiteTopic event transport that publishes committed Session events across nodes and runs the wake and materialization consumers.

PropertyVariableTypeDefaultDescription
capability-probe-group—stringqwen-managed-journal-capability-probeThe RocketMQ consumer group the startup LiteTopic capability probe subscribes in. Pre-create it as a LITE group bound to qwen.managed-agent.event-transport.topic; startup fails when the probe cannot subscribe.
enabled—booleanfalseWhether committed Session journal records and public events are also published to a RocketMQ LiteTopic broker, whose consumers carry wakes and materialization notices between nodes. Needs RocketMQ 5.5.0 or later with enableLmq and a pre-created LITE topic and groups; startup fails when the broker cannot serve them. The private CSI lane refuses work while it is on.
endpoints—string(empty)The RocketMQ proxy gRPC endpoint the event transport connects to, as host:port (for example host:8081). Required when qwen.managed-agent.event-transport.enabled is true; startup fails when the broker is unreachable or is not a gRPC (RocketMQ 5) proxy.
owner-group—stringqwen-managed-session-ownerThe RocketMQ consumer group, shared by every node, in which each node subscribes to the LiteTopics of the Sessions it holds, so a Session’s notices reach its owner. Pre-create it as a LITE group bound to qwen.managed-agent.event-transport.topic.
owner-reconcile-interval—duration1sHow often a node re-aligns its owner-group subscriptions with the Sessions it holds, subscribing to newly held ones and dropping released ones. A plain number is seconds.
topic—string(empty)The parent RocketMQ topic under which each Session’s LiteTopic and the wake bootstrap LiteTopic live. Required when qwen.managed-agent.event-transport.enabled is true. Pre-create it as a LITE topic (message.type=LITE); startup fails when it refuses a LiteTopic message.
wake-bootstrap-group—stringqwen-managed-wake-bootstrapThe RocketMQ consumer group, shared by every node, that consumes qwen.managed-agent.event-transport.wake-bootstrap-lite-topic, one member at a time. Pre-create it as a LITE group bound to qwen.managed-agent.event-transport.topic; startup fails when it cannot subscribe.
wake-bootstrap-lite-topic—stringqwen-wake-bootstrapThe LiteTopic under qwen.managed-agent.event-transport.topic that every wake.requested envelope is also sent to, so any node can learn of a wake that no node owns yet. Choose a name that cannot equal a Session id (a UUID).

qwen.managed-agent.events

Session event streams (SSE), batching of Harness output into Session events, message materialization and the replay floor.

PropertyVariableTypeDefaultDescription
batch-interval—duration75msHow long streamed text output from the Hosted Harness is buffered before it is written to the Session’s events as one batch; a batch is written sooner on reaching qwen.managed-agent.events.batch-max-events or qwen.managed-agent.events.batch-max-bytes. Startup refuses a zero or negative value. A plain number is milliseconds.
batch-max-bytes—integer65536How many bytes of streamed text output one event batch may collect before it is written early, estimated as each delta’s UTF-8 text plus 128 bytes. Startup refuses a zero or negative value.
batch-max-events—integer64How many streamed text deltas one event batch may collect before it is written early; the queue between the Harness stream reader and the writer also holds twice this many, at least 128. Startup refuses a zero or negative value.
heartbeat-interval—duration15sHow often an idle Session event stream (SSE) sends a keepalive comment. A plain number is seconds.
materialize-interval—duration100msHow often the message materializer folds newly committed Session events into the message view that message and transcript queries read. A plain number is milliseconds.
poll-interval—duration5sHow long an open Session event stream waits for an in-process event notification before it re-reads the Session’s events from the database, catching anything the notification missed. It also bounds how long an idle stream takes to notice a revoked read grant. A plain number is seconds.
read-grant-recheck-interval—duration5sHow often an open Session event stream re-verifies that its subscriber may still read the Session; 0s checks before every event. A revoked grant stops delivery within this interval, and an idle stream closes within it plus qwen.managed-agent.events.poll-interval. A plain number is seconds.
replay-floor-enabledQWEN_MANAGED_AGENT_REPLAY_FLOOR_ENABLEDbooleanfalseWhether a scheduled pass raises each Session’s replay floor up to what its message view already covers, never past an unfinished Turn. Event cursors below the floor then get 409 cursor_expired, or one agent.session.resync_required frame on a stream. No event is deleted either way. The pass runs every qwen.managed-agent.events.replay-floor-interval.
replay-floor-intervalQWEN_MANAGED_AGENT_REPLAY_FLOOR_INTERVALduration60sHow long the replay-floor pass waits between runs; each run works through every eligible Session, and it does nothing unless qwen.managed-agent.events.replay-floor-enabled is true. Accepts a duration such as 60s; a plain number is milliseconds.
stream-timeout—duration30mHow long one Session event stream (SSE) connection may stay open before the server ends it; the client must reconnect to keep receiving events. A plain number is seconds.

qwen.managed-agent.extensions

Publishing and managing Workspace extension packages, and which actors may do so.

PropertyVariableTypeDefaultDescription
allowed-actorsQWEN_MANAGED_AGENT_EXTENSION_ALLOWED_ACTORSlist(empty)The actor IDs allowed to publish extension packages, save their settings, and select or apply them for Sessions, as a comma-separated list; * allows every actor. The actor also needs Workspace OPERATOR access. Empty allows nobody.
artifact-directoryQWEN_MANAGED_AGENT_EXTENSION_ARTIFACT_DIRECTORYstring(empty)The directory that stores published extension package archives, in one private (0700) subdirectory per tenant and Workspace. Empty disables extension management. A symbolic link at the root or at a subdirectory makes archives unavailable. Replicas must share this directory.
enabledQWEN_MANAGED_AGENT_EXTENSION_PACKAGES_ENABLEDbooleanfalseWhether extension packages can be published and managed for Workspaces through the public extensions API. Management also needs qwen.managed-agent.extensions.artifact-directory, an actor in qwen.managed-agent.extensions.allowed-actors and Workspace OPERATOR access. With qwen.managed-agent.runtime-broker.enabled, startup refuses qwen.managed-agent.managed-extensions.enabled without it; otherwise extension execution simply stays off.

qwen.managed-agent.harness

The connection to the Hosted Harness (qwen serve --profile hosted-harness) that runs Sessions: its address and shared credentials, call timeouts, the approval policy, and which Workspace tools Sessions are created with.

PropertyVariableTypeDefaultDescription
approval-modeQWEN_MANAGED_AGENT_APPROVAL_MODEstringyoloThe approval mode Hosted Sessions start with, case-insensitive: yolo, default or auto-edit, plus plan and auto while Workspace files are off. Unbound built-in Sessions follow the current value; Workspace-bound Sessions pin it at creation. While qwen.managed-agent.harness.workspace-files-enabled is true, startup refuses any mode but the first three, and with qwen.managed-agent.harness.workspace-shell-enabled it refuses yolo too. Any other value fails the Harness connector, at startup for a single Harness.
approval-timeoutQWEN_MANAGED_AGENT_APPROVAL_TIMEOUTduration10mHow long a tool permission request waits for an answer before it expires and the tool call is refused. It is sent to the Harness when a Session is created. Startup refuses values outside 1s to 24h; a number without a unit is read as seconds.
base-urlQWEN_MANAGED_AGENT_HARNESS_BASE_URLstringhttp://127.0.0.1:4170The URL of the single Hosted Harness the control plane calls. Must be an absolute http or https URL without credentials, query or fragment while qwen.managed-agent.harness.enabled is true: a single Harness is refused at startup, and under qwen.managed-agent.harness.pool.enabled every pool member fails to join instead, so keep a valid value there even though the pool does not route by it. Startup refuses plaintext http to a non-loopback host unless qwen.managed-agent.auth.allow-insecure-bind is true. The managed-local profile requires a loopback http URL.
capability-digestQWEN_MANAGED_AGENT_CAPABILITY_DIGESTstring(empty)The capability digest the Harness must advertise, written sha256: plus 64 lowercase hex characters and equal to the Harness’s QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST; a mismatch fails negotiation. Required while qwen.managed-agent.harness.enabled is true unless qwen.managed-agent.harness.credentials-file supplies it; setting both is refused at startup.
connect-timeout—duration5sHow long the control plane waits to open a connection to a Hosted Harness, including Harness pool members. Must be positive; a number without a unit is read as seconds.
credentials-fileQWEN_MANAGED_AGENT_HARNESS_CREDENTIALS_FILEstring(empty)Path to the Harness’s own environment file, read instead of setting the shared credentials here: it must set QWEN_SERVER_TOKEN and QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST, and may set QWEN_MANAGED_RUNTIME_BROKER_URL and QWEN_MANAGED_RUNTIME_BROKER_TOKEN together. Read only while qwen.managed-agent.harness.enabled is true. Startup refuses it beside qwen.managed-agent.harness.token or qwen.managed-agent.harness.capability-digest, a file Broker token beside qwen.managed-agent.runtime-broker.token, an unreadable file, and any line systemd and a shell would read differently.
enabledQWEN_MANAGED_AGENT_HARNESS_ENABLEDbooleanfalseWhether the control plane runs Sessions on a Hosted Harness. When false, no Harness connector is created and Session execution fails as Harness disabled. When true, startup requires qwen.managed-agent.session-store.enabled, the Harness token and capability digest (directly or through qwen.managed-agent.harness.credentials-file), and for a single Harness a valid qwen.managed-agent.harness.base-url. The packaged configuration makes qwen.managed-agent.session-store.enabled follow it.
heartbeat-interval—duration30sHow often the control plane sends a keepalive heartbeat for each attached Harness Session. 0 turns scheduled heartbeats off; negative values are refused. A number without a unit is read as seconds.
load-timeoutQWEN_MANAGED_AGENT_HARNESS_LOAD_TIMEOUTduration120sHow long a takeover load of a Harness Session may take, since it can settle parked Runtime executions; ordinary attach loads use qwen.managed-agent.harness.request-timeout. Must be positive while qwen.managed-agent.harness.enabled is true: a single Harness is refused at startup, and under qwen.managed-agent.harness.pool.enabled every pool member fails to join instead; a number without a unit is read as seconds.
request-timeout—duration30sHow long a single ordinary call to the Hosted Harness may take, including attach loads that are not takeovers. Task cancellation attempts get at least four times this value, and never less than 5 minutes. Must be positive; a number without a unit is read as seconds.
tokenQWEN_MANAGED_AGENT_HARNESS_TOKENstring(empty)The bearer token the control plane sends to the Hosted Harness, equal to the Harness’s QWEN_SERVER_TOKEN; a secret. Required while qwen.managed-agent.harness.enabled is true unless qwen.managed-agent.harness.credentials-file supplies it; setting both is refused at startup. The preflight check fails a value still starting with the template placeholder replace-.
turn-deadlineQWEN_MANAGED_AGENT_HARNESS_TURN_DEADLINEduration30mHow long an admitted Turn may run before the Harness settles it as a deadline failure, so a stalled model stream cannot hold a Session forever. It is sent with each Turn. Values outside 1ms to about 24.8 days are refused while qwen.managed-agent.harness.enabled is true: a single Harness is refused at startup, and under qwen.managed-agent.harness.pool.enabled every pool member fails to join instead; a number without a unit is read as seconds.
workspace-child-agents-enabledQWEN_MANAGED_AGENT_WORKSPACE_CHILD_AGENTS_ENABLEDbooleantrueWhether qualified Workspace Shell Sessions created while it is on may delegate work to public child agents: built-in qwen-code Sessions, and AgentDefinition Sessions too while managed extension execution is on. It takes effect only with qwen.managed-agent.harness.workspace-shell-enabled, qwen.managed-agent.runtime-broker.durable-local-process, qwen.managed-agent.runtime-broker.provisioner=local-process, qwen.managed-agent.runtime-broker.bound-session-isolation-class=session and a Harness that supports it; otherwise it stays off without an error. Setting it false stops further child launches.
workspace-files-enabledQWEN_MANAGED_AGENT_WORKSPACE_FILES_ENABLEDbooleanfalseWhether Workspace-bound Sessions get the Hosted Workspace file tools (hosted-workspace-files/1) and the Workspace file routes, which otherwise answer 409 workspace_files_disabled. Startup requires the Harness, the Session Store and qwen.managed-agent.runtime-broker.enabled; a local-process Broker with session isolation and Workspace mounts, a creation root, verified Workspace recovery or SSH nodes (or an exclusive resident CSI setup); and approval mode yolo, default or auto-edit. External Runtime provisioners refuse it.
workspace-shell-enabledQWEN_MANAGED_AGENT_WORKSPACE_SHELL_ENABLEDbooleanfalseWhether built-in qwen-code Workspace Sessions are created with the hosted-workspace-shell/1 profile: the file tools plus a foreground Shell. Startup requires qwen.managed-agent.harness.workspace-files-enabled and approval mode default or auto-edit, and refuses it with resident Workspaces or an external Runtime provisioner. Turning it off refuses fresh Turns on existing Shell Sessions with 409 workspace_unavailable.

qwen.managed-agent.harness.pool

Placing Sessions on several Hosted Harness instances instead of the single qwen.managed-agent.harness.base-url, with static or Kubernetes discovery and mutual TLS to the members.

PropertyVariableTypeDefaultDescription
discovery—stringstaticHow the Harness pool finds its members: static reads qwen.managed-agent.harness.pool.instances; kubernetes watches the EndpointSlices of the Service named by qwen.managed-agent.harness.pool.namespace, qwen.managed-agent.harness.pool.service-name and qwen.managed-agent.harness.pool.service-uid. Startup refuses any other value, kubernetes together with static instances, and kubernetes without the mTLS key and trust stores. Membership is refreshed every 5 seconds.
enabled—booleanfalseWhether Sessions are placed on a pool of Hosted Harness instances, each Session staying on its member, instead of the single qwen.managed-agent.harness.base-url. Read only while qwen.managed-agent.harness.enabled is true. Startup requires qwen.managed-agent.session-store.enabled, qwen.managed-agent.session-store.binding-key, the Harness token and a sha256: capability digest, and refuses qwen.managed-agent.runtime-broker.provisioner=kubernetes-workspace. Members must advertise harness-pool-owner/1 and harness-instance-lifecycle/1 with identical capabilities.
instances—YAML list(empty)The static pool members, used when qwen.managed-agent.harness.pool.discovery is static; set in a configuration file (YAML). Each entry has instance-id (1 to 128 letters, digits, ., _, : or -, unique, equal to the instance ID that Harness reports) and base-url (an http or https origin without path, credentials, query or fragment). Startup refuses an empty list, more than 256 entries, and a non-loopback member without https and the pool’s mTLS stores.
key-store-file—string(empty)Path to the PKCS12 key store with the client certificate and key the control plane presents to Harness pool members (mutual TLS). Must be set together with qwen.managed-agent.harness.pool.trust-store-file, or startup is refused. Required for kubernetes discovery and for any non-loopback member; with both stores empty, no client certificate is sent.
key-store-password-file—string(empty)Path to a file holding the password of qwen.managed-agent.harness.pool.key-store-file, also used as the key password. The file holds a secret. At most 4096 bytes; trailing whitespace is removed; empty means an empty password. Startup refuses a file that cannot be read or is too large.
kubernetes-api-url—stringhttps://kubernetes.default.svcThe Kubernetes API server origin that kubernetes discovery reads the Harness Service and its EndpointSlices from. Must be an https origin without path, credentials, query or fragment, or startup is refused. Read only when qwen.managed-agent.harness.pool.discovery is kubernetes.
kubernetes-ca-file—string/var/run/secrets/kubernetes.io/serviceaccount/ca.crtPath to the X.509 CA certificates (PEM or DER) used to verify the Kubernetes API server for kubernetes discovery. Startup refuses a file that cannot be read or holds no certificate. Read only when qwen.managed-agent.harness.pool.discovery is kubernetes.
kubernetes-token-file—string/var/run/secrets/kubernetes.io/serviceaccount/tokenPath to the bearer token file that kubernetes discovery sends to the Kubernetes API, normally the Pod’s service account token. The file holds a secret and is read again for every request; it must be one non-empty line of at most 64 KiB, otherwise discovery fails and the pool places no further Sessions until it recovers.
namespace—string(empty)The Kubernetes namespace of the Harness Service and its EndpointSlices for kubernetes discovery. Must be a DNS label (lowercase letters, digits and -, at most 63 characters); startup refuses anything else when qwen.managed-agent.harness.pool.discovery is kubernetes.
port-name—stringhttpsThe name of the TCP port in the Harness EndpointSlices that serves the Harness; kubernetes discovery calls each Pod at https://<pod IP>:<port> and uses the Pod UID as its instance ID. Must be a DNS label (startup refusal otherwise); a slice that lacks the port or lists it twice makes discovery fail.
service-name—string(empty)The name of the Kubernetes Service whose EndpointSlices list the Harness Pods for kubernetes discovery. Must be a DNS label; startup refuses anything else when qwen.managed-agent.harness.pool.discovery is kubernetes.
service-uid—string(empty)The metadata.uid of the Harness Service, which pins kubernetes discovery to that exact Service: a Service or EndpointSlice owner with another UID makes discovery fail and offers no members. Required, at most 256 characters, when qwen.managed-agent.harness.pool.discovery is kubernetes; startup refuses it empty.
trust-store-file—string(empty)Path to the PKCS12 trust store with the CA certificates used to verify Harness pool members’ server certificates. Must be set together with qwen.managed-agent.harness.pool.key-store-file, or startup is refused; that property says when the stores are required.
trust-store-password-file—string(empty)Path to a file holding the password of qwen.managed-agent.harness.pool.trust-store-file. The file holds a secret. At most 4096 bytes; trailing whitespace is removed; empty means an empty password. Startup refuses a file that cannot be read or is too large.

qwen.managed-agent.internal-server

An optional separate listener for the internal routes (/internal/**), such as the Session Store the Harness calls, so they do not share the public listener.

PropertyVariableTypeDefaultDescription
addressQWEN_MANAGED_AGENT_INTERNAL_SERVER_ADDRESSstring127.0.0.1The address the separate internal listener binds when qwen.managed-agent.internal-server.port is set; empty means 127.0.0.1. Startup refuses an address that does not resolve, and a non-loopback address without qwen.managed-agent.session-store.binding-key unless qwen.managed-agent.auth.allow-insecure-bind. The listener is always plaintext, and the server warns when it leaves loopback. The managed-local profile requires a loopback address.
portQWEN_MANAGED_AGENT_INTERNAL_SERVER_PORTinteger0The port of a separate listener for the internal routes (/internal/**, including the Session Store); 0 or less serves them on the public listener. When set, each listener answers 404 for the other’s routes. Startup refuses a port equal to server.port, and qwen.managed-agent.channels.enabled requires a port. The listener never inherits server.ssl.

qwen.managed-agent.managed-extensions

Running the processes of selected extension packages inside Workspace Runtime workers under the managed extension execution profile.

PropertyVariableTypeDefaultDescription
cache-directoryQWEN_MANAGED_AGENT_EXTENSION_CACHE_DIRECTORYstring(empty)The absolute directory where Runtime workers cache the extension packages they run; keep it private and outside every Workspace. Required when qwen.managed-agent.managed-extensions.enabled is true: a relative or empty path is refused at startup when the Runtime Broker uses local-process or SSH workers.
cgroup-rootQWEN_MANAGED_AGENT_EXTENSION_CGROUP_ROOTstring(empty)The absolute path of a writable, delegated cgroup v2 subtree under which Linux Runtime workers contain extension processes. Required for Linux workers when qwen.managed-agent.managed-extensions.enabled is true (a Runtime launch fails without it); must be empty in developer-process-group mode.
enabledQWEN_MANAGED_AGENT_EXTENSION_EXECUTION_ENABLEDbooleanfalseWhether Workspace Runtimes run with the managed extension execution profile, which lets selected extension packages run their processes (such as Hooks and MCP servers) in Runtime workers. Requires qwen.managed-agent.extensions.enabled (startup refusal) and qwen.managed-agent.managed-extensions.cache-directory, plus qwen.managed-agent.managed-extensions.cgroup-root on Linux.
modeQWEN_MANAGED_AGENT_EXTENSION_EXECUTION_MODEstringlinux-cgroupThe extension execution mode: linux-cgroup contains extension processes in a delegated cgroup v2 subtree, and developer-process-group is a weaker process-group mode for native macOS development. Linux workers always use linux-cgroup; a macOS worker is refused unless this is developer-process-group.

qwen.managed-agent.runtime-broker

The embedded Runtime Broker: its private HTTP listener for the Hosted Harness, the provisioner that places and recovers the Runtime workers that run Hosted tools, their Workspace mounts and isolation, and the keys that encrypt the Runtime credentials it persists.

PropertyVariableTypeDefaultDescription
allow-non-loopbackQWEN_MANAGED_AGENT_RUNTIME_BROKER_ALLOW_NON_LOOPBACKbooleanfalseWhether the embedded Runtime Broker may bind a non-loopback address in qwen.managed-agent.runtime-broker.host, such as 0.0.0.0; without it, startup refuses such an address. The listener serves one global bearer token over plaintext HTTP, with no per-tenant authorization, so enable it only behind a layer that terminates TLS and authorizes callers: restricting the network alone still sends the token in clear text, and whoever reads it can drive every execution the Broker admits. The managed-local profile refuses a non-loopback host regardless.
bound-session-isolation-class—stringsessionHow Runtime workers are shared among Sessions bound to a mounted local Workspace: session gives each Session its own worker, workspace lets the Sessions of one Workspace share one. Startup refuses other values. workspace requires the local-process provisioner with qwen.managed-agent.runtime-broker.durable-local-process and cannot combine with qwen.managed-agent.runtime-broker.child-workspaces-enabled; Session worktrees and public child agents need session. SSH-bound Sessions always use session.
child-snapshots-enabled—booleanfalseWhether Hosted Sessions may also launch read-only snapshot child agents, which read a frozen, always-discarded copy of the parent’s Workspace through a tool profile without writing tools. Requires qwen.managed-agent.runtime-broker.child-workspaces-enabled; startup refuses it alone, and also refuses it with an external provisioner.
child-workspace-git—stringgitThe Git executable that child Workspace and Session worktree steps run; a bare name is looked up on the server’s PATH. It must be Git 2.40 or later. With qwen.managed-agent.runtime-broker.child-workspaces-enabled, startup probes its version and refuses an older Git.
child-workspace-git-timeout—duration2mHow long each Git command of a child Workspace or Session worktree step may run before it is killed. A suffix-less number binds as milliseconds, so write the unit. With qwen.managed-agent.runtime-broker.child-workspaces-enabled, startup refuses values outside 1s to 1h.
child-workspaces-enabled—booleanfalseWhether Hosted Sessions may run child agents in isolated child Workspaces: Git worktrees inside the parent’s storage, merged back or discarded after the child Session closes. Startup requires qwen.managed-agent.runtime-broker.enabled, the local-process provisioner, session in qwen.managed-agent.runtime-broker.isolation-class, qwen.managed-agent.runtime-broker.durable-local-process, qwen.managed-agent.runtime-broker.workspace-mounts or qwen.managed-agent.runtime-broker.workspace-creation-root, Git 2.40 or later, a UTF-8 locale and a non-Windows host, and refuses workspace in qwen.managed-agent.runtime-broker.bound-session-isolation-class.
credential-keyQWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEYstring(empty)The active Runtime credential key: a base64-encoded 32-byte AES-256-GCM key that encrypts the Runtime provision seeds, worker lease tokens and managed extension settings stored in the database. A secret. Required when qwen.managed-agent.runtime-broker.enabled is on; startup refuses an empty value, invalid base64 or a length other than 32 bytes. Generate one with openssl rand -base64 32.
credential-key-idQWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY_IDstring(empty)The ID of the active Runtime credential key, stored beside every ciphertext it writes so that reads pick the matching key. Not a secret. Required when qwen.managed-agent.runtime-broker.enabled is on; startup refuses an empty value, one over 512 characters, or an ID also listed in qwen.managed-agent.runtime-broker.previous-credential-keys. Changing the ID and key is a rotation: keep the old pair in that map.
durable-local-processQWEN_MANAGED_AGENT_RUNTIME_DURABLE_LOCAL_PROCESSbooleantrueWhether the local-process provisioner registers every Runtime worker launch in qwen.managed-agent.runtime-broker.state-directory so that a restarted Broker adopts the same live worker; when off, workers stop with the Broker. Needs Linux, or macOS with qwen.managed-agent.runtime-broker.trusted-local-reboot-recovery off, and a state directory outside every Workspace root; startup refuses otherwise. Trusted reboot recovery, child Workspaces, Workspace creation, local directory import and workspace bound-Session isolation require it.
enabledQWEN_MANAGED_AGENT_RUNTIME_BROKER_ENABLEDbooleanfalseWhether the control plane runs the embedded Runtime Broker, which places the Runtime workers that execute Hosted tools and serves the Hosted Harness on qwen.managed-agent.runtime-broker.host and qwen.managed-agent.runtime-broker.port. When on, startup requires qwen.managed-agent.runtime-broker.token, qwen.managed-agent.runtime-broker.credential-key-id, qwen.managed-agent.runtime-broker.credential-key, qwen.managed-agent.runtime-broker.workspace-cwd and qwen.managed-agent.harness.capability-digest. Hosted Workspace files and child Workspaces require it.
environment—YAML map(empty)Extra environment variables for Runtime workers, as a map from variable name to value, set in a configuration file (YAML). No provisioner passes them on: startup refuses a non-empty map with the local-process provisioner, and the other provisioners ignore it.
external-provider-idQWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_IDstringexternalThe provider ID that the external-scratch and external-workspace provisioners record in every Runtime handle and digest into its identity. With either provisioner, startup refuses an empty value or one over 512 characters. Set it once before the first Session: changing it later invalidates every existing external binding.
external-provider-tokenQWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_TOKENstring(empty)The bearer token the Broker sends to the external Runtime provider’s provision and observe routes. A secret. With an external provisioner, startup refuses a value that is not 16 to 4096 characters of letters, digits and ._~+/=-, or that starts with replace-, the shipped template placeholder.
external-provider-urlQWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_URLstring(empty)The base URL of the operator-run external Runtime provider; the Broker POSTs to its provision and observe routes below this path and follows no redirects. Required with the external-scratch and external-workspace provisioners: startup refuses anything but an HTTP(S) URL with a host and no credentials, query or fragment. Use HTTPS outside a trusted network.
external-request-timeoutQWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_REQUEST_TIMEOUTduration30sHow long one HTTP call to the external Runtime provider may take before it fails; establishing the connection is separately bounded at 5 seconds. A suffix-less number binds as seconds. Read only with an external provisioner, where startup refuses a value under 1ms.
external-startup-timeoutQWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_STARTUP_TIMEOUTduration2mHow long the Broker keeps polling the external provider’s observe route after provision for the provisioned worker to report ready; when it lapses, the placement fails with the retryable runtime_external_unavailable. A suffix-less number binds as seconds. Read only with an external provisioner, where startup refuses a value under 1ms.
hostQWEN_MANAGED_AGENT_RUNTIME_BROKER_HOSTstring127.0.0.1The address the embedded Runtime Broker’s HTTP listener binds; the Hosted Harness reaches it through its own QWEN_MANAGED_RUNTIME_BROKER_URL. A non-loopback address, including 0.0.0.0, requires qwen.managed-agent.runtime-broker.allow-non-loopback, and the managed-local profile refuses one regardless. Preflight compares the Broker URL in the Harness credentials file with this listener.
isolation-classQWEN_MANAGED_AGENT_RUNTIME_ISOLATIONstringsessionHow the Broker shares Runtime workers among Sessions with no Workspace binding: session gives each Hosted Session its own worker, workspace shares one across the configured Workspace. Startup refuses workspace with Hosted Workspace files on local-process, child Workspaces or an external provisioner, and refuses session with the static or kubernetes-workspace provisioner. Workspace-bound Sessions use qwen.managed-agent.runtime-broker.bound-session-isolation-class instead.
local-directory-import-enabledQWEN_MANAGED_AGENT_LOCAL_DIRECTORY_IMPORT_ENABLEDbooleanfalseWhether WebShell may import an existing directory on this host as a Workspace, registering its parent as storage and granting the importing actor OWNER access. For a trusted single-user host: startup requires a loopback server.address with signed authentication or qwen.managed-agent.trusted-actor-header, plus qwen.managed-agent.harness.workspace-files-enabled, qwen.managed-agent.runtime-broker.durable-local-process and qwen.managed-agent.runtime-broker.verified-workspace-recovery-enabled.
node-executableQWEN_MANAGED_AGENT_NODE_EXECUTABLEstring(empty)The path of the Node.js executable that runs the local Runtime worker (qwen.managed-agent.runtime-broker.worker-entry) and the helper processes for local Workspace file reads and uploads. Required with the local-process provisioner; startup refuses it empty. Preflight checks that it is executable.
operator-recovery-enabledQWEN_MANAGED_AGENT_RUNTIME_OPERATOR_RECOVERY_ENABLEDbooleanfalseWhether the offline operator-recovery command (bin/qwen-managed-agent-operator-recovery) may run its inspect, prepare and complete steps for a Hosted Shell capture that kept a Workspace lease. Set it for that maintenance process: the command refuses to run unless it is on with qwen.managed-agent.runtime-broker.durable-local-process, the local-process provisioner and qwen.managed-agent.runtime-broker.state-directory. The server refuses it at startup with an external provisioner.
portQWEN_MANAGED_AGENT_RUNTIME_BROKER_PORTinteger4182The TCP port of the embedded Runtime Broker’s HTTP listener; the Hosted Harness’s QWEN_MANAGED_RUNTIME_BROKER_URL must reach it, directly on a loopback address or through the TLS-terminating proxy in front of a non-loopback bind. Startup fails when the listener cannot bind it. Preflight checks that the port is free, or listening with --online, and compares it with the Broker URL in the Harness credentials file.
previous-credential-keys—YAML map(empty)Earlier Runtime credential keys kept after a rotation, as a map from key ID to base64-encoded 32-byte key, so rows encrypted under them stay readable; writes use only the active key. Secrets. Set it in a configuration file (YAML), each ID in brackets, such as '[old-v1]': <key>; environment variables cannot supply it. Startup refuses a key that is not 32 bytes or an ID equal to qwen.managed-agent.runtime-broker.credential-key-id.
provider-options—YAML map{}Provider-specific string settings passed to the selected Runtime factory, configured as a YAML map. Their meaning and validation belong to that provider; built-in backends continue to use their existing settings. Defaults to an empty map.
provisionerQWEN_MANAGED_AGENT_RUNTIME_PROVISIONERstringlocal-processThe installed factory kind that places Runtime workers: local-process (local Node.js workers), ssh-process (registered SSH Workspaces), static (a preconfigured worker), external-scratch or external-workspace (an operator-run HTTP provider), or kubernetes-workspace (resident CSI Workspaces). A trusted additional provider may register its own kind. With the Broker enabled, missing or duplicate kinds fail before resources are created; kubernetes remains reserved and rejected. Embedding hosts must explicitly include the selected backend artifact.
resident-kubernetes-api-url—string(empty)The HTTPS origin of the Kubernetes API server that the kubernetes-workspace provisioner calls for qwen.managed-agent.runtime-broker.resident-workspaces, together with qwen.managed-agent.runtime-broker.resident-kubernetes-token-file and qwen.managed-agent.runtime-broker.resident-kubernetes-ca-file. Startup refuses resident Workspaces without it, and refuses a URL that is not https or has a path, credentials, query or fragment. The resident-retirement maintenance command reads it too.
resident-kubernetes-ca-file—string(empty)Path to a PEM or DER file of X.509 CA certificates that the server trusts, instead of the JVM defaults, for TLS to the Kubernetes API named by qwen.managed-agent.runtime-broker.resident-kubernetes-api-url. Required when qwen.managed-agent.runtime-broker.resident-workspaces is set; an unreadable file or one without certificates fails startup. The resident-retirement admin command reads it too.
resident-kubernetes-token-file—string(empty)Path to a file holding the bearer token the server sends to the Kubernetes API to manage resident Workspace Pods. The file holds a secret; it is re-read on every request, so the token can be rotated in place, and it must contain at most 16 KiB of letters, digits and ._~-. Required when qwen.managed-agent.runtime-broker.resident-workspaces is set; the resident-retirement admin command reads it too.
resident-workspaces—YAML list(empty)The Workspaces served by dedicated resident Kubernetes Pods on CSI storage, set in a configuration file (YAML) as a list. Each entry has workspace-id, workspace-generation (1 or more), registration (the registered CSI storage: tenant-id, storage-id, cluster-domain, namespace, pvc-name, pvc-uid, pv-name, pv-uid, driver, volume-handle, backend-domain, disk-serial, mount-root, revision), protection (namespace-uid, policy-name, policy-uid, policy-generation, binding-name, binding-uid, binding-generation), image (pinned as name@sha256:<64 hex>), command (1 to 32 arguments: the executable and CLI path) and artifacts (up to 48 ConfigMaps, each with config-map-name, uid and sha256). A non-empty list needs the kubernetes-workspace provisioner with its three resident-kubernetes-* settings, workspace isolation and Workspace files, and refuses Workspace mounts, SSH nodes, trusted reboot or verified Workspace recovery, child Workspaces and Workspace Shell. Each tenant Workspace and each volume may appear once, and each registration must match a registered CSI storage record.
session-create-warm—booleanfalseWhether creating a Workspace-bound Session without initial input starts its Runtime worker right away instead of at the first Turn. Requires qwen.managed-agent.runtime-broker.bound-session-isolation-class set to workspace and no qwen.managed-agent.runtime-broker.ssh.nodes; startup refuses it otherwise and with external provisioners. Has no effect while Workspace files are unavailable.
session-worktrees-enabled—booleanfalseWhether a Workspace Session may be created in its own Git worktree of the Workspace repository, checked out from an optional local base ref under .qwen-managed-worktrees on a new worktree-managed-<id> branch. Takes effect only with qwen.managed-agent.runtime-broker.enabled, qwen.managed-agent.runtime-broker.durable-local-process, the local-process provisioner and qwen.managed-agent.runtime-broker.bound-session-isolation-class set to session, on a non-Windows host whose JVM uses UTF-8 file names; otherwise worktree requests are refused with worktree_unsupported.
state-directoryQWEN_MANAGED_AGENT_RUNTIME_STATE_DIRECTORYstring(empty)The directory where the local-process Broker keeps worker registrations and recovery records; workers also run with it as their working directory. Required when qwen.managed-agent.runtime-broker.provisioner is local-process. With qwen.managed-agent.runtime-broker.durable-local-process it is created if missing, provided its parent exists, and must be owned by the server account with mode 0700, have no symlinks in its path, and lie outside qwen.managed-agent.runtime-broker.workspace-cwd, qwen.managed-agent.runtime-broker.workspace-creation-root and every qwen.managed-agent.runtime-broker.workspace-mounts root; startup refuses otherwise. A relative path resolves against the server’s working directory.
static-endpointQWEN_MANAGED_AGENT_STATIC_RUNTIME_ENDPOINTstring(empty)The HTTP(S) origin of the already-running Runtime worker that the static provisioner hands to every Session; an origin only, without path, credentials, query or fragment. Required, with qwen.managed-agent.runtime-broker.static-token, when qwen.managed-agent.runtime-broker.provisioner is static, which also requires qwen.managed-agent.runtime-broker.isolation-class set to workspace and qwen.managed-agent.runtime-broker.trusted-local-reboot-recovery set to false.
static-epoch—integer1The lease epoch of the static Runtime worker; the Broker sends it with each request and the worker’s attestation must report the same value. Startup refuses a negative value. Read only when qwen.managed-agent.runtime-broker.provisioner is static.
static-lease-id—stringstandalone-leaseThe lease ID of the static Runtime worker; the Broker sends it with each request and the worker’s attestation must report the same value. A non-empty string of at most 512 characters. Read only when qwen.managed-agent.runtime-broker.provisioner is static.
static-runtime-instance-id—stringstandalone-runtimeThe Runtime instance ID of the static Runtime worker’s lease; the worker’s attestation must report the same value. A non-empty string of at most 512 characters. Read only when qwen.managed-agent.runtime-broker.provisioner is static.
static-tokenQWEN_MANAGED_AGENT_STATIC_RUNTIME_TOKENstring(empty)The bearer token the Broker presents to the static Runtime worker. A secret; saved bindings store it encrypted with the Runtime credential key (qwen.managed-agent.runtime-broker.credential-key). Required when qwen.managed-agent.runtime-broker.provisioner is static; at most 512 characters.
tokenQWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKENstring(empty)The bearer token the Hosted Harness presents to the embedded Runtime Broker’s private listener; it also authorizes the loopback-only external storage registration endpoint. A secret. Required when qwen.managed-agent.runtime-broker.enabled is true; at most 512 characters. It can come from qwen.managed-agent.harness.credentials-file (QWEN_MANAGED_RUNTIME_BROKER_TOKEN) instead; setting it in both places is refused at startup.
trusted-local-reboot-recoveryQWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERYbooleantrueWhether, after a whole-host reboot on Linux, the Broker treats the changed kernel boot ID as proof that the original local workers stopped, and clears the holders of their saved Runtime bindings once every execution is terminal. It scans 8 saved bindings every 5 seconds and never starts a replacement worker or replays an execution. Requires qwen.managed-agent.runtime-broker.durable-local-process and the local-process provisioner; startup refuses it otherwise, on macOS and with resident Workspaces.
v3-result-windowQWEN_MANAGED_AGENT_RUNTIME_BROKER_V3_RESULT_WINDOWduration30mHow long the Runtime Broker keeps waiting for the worker’s result of a dispatched Shell or Monitor execution that publishes its output (Tool v3, with qwen.managed-agent.tool-publication.enabled) before marking it UNKNOWN; a value shorter than the longest such call turns that call into UNKNOWN. Other tool executions do not use this window. A value above 30m buys nothing on the shipped path: the Hosted Harness stops waiting for a Tool v3 execution after its own fixed 30 minutes. A suffix-less number binds as seconds. Startup refuses a value below 1s.
verified-workspace-recovery-enabledQWEN_MANAGED_AGENT_RUNTIME_VERIFIED_WORKSPACE_RECOVERY_ENABLEDbooleanfalseWhether LOCAL Workspace execution is gated on a verified physical storage registration: before tools, file access or child Git run, the server checks that the Workspace root still matches its registered identity and marker, and otherwise refuses with 409 workspace_unavailable. Required by qwen.managed-agent.runtime-broker.workspace-creation-root and qwen.managed-agent.runtime-broker.local-directory-import-enabled; without qwen.managed-agent.runtime-broker.workspace-mounts it also satisfies the Workspace source that qwen.managed-agent.harness.workspace-files-enabled needs. Startup refuses it with external provisioners and resident Workspaces.
worker-entryQWEN_MANAGED_AGENT_RUNTIME_WORKER_ENTRYstring(empty)Path to the built Qwen Code CLI bundle (for example dist/cli.js) that qwen.managed-agent.runtime-broker.node-executable runs with managed-runtime-worker to start local-process workers; LOCAL Workspace file-reference checks and uploads also run through it. Required when qwen.managed-agent.runtime-broker.provisioner is local-process; a relative path resolves against the server’s working directory.
workspace-creation-rootQWEN_MANAGED_AGENT_WORKSPACE_CREATION_ROOTstring(empty)An existing canonical directory the server account can write, under which it creates new empty Workspaces in per-tenant subdirectories when users start a Workspace from scratch; empty disables Workspace creation. It must not overlap any qwen.managed-agent.runtime-broker.workspace-mounts root, qwen.managed-agent.runtime-broker.state-directory or qwen.managed-agent.runtime-broker.workspace-cwd, and requires qwen.managed-agent.harness.workspace-files-enabled, qwen.managed-agent.runtime-broker.durable-local-process and qwen.managed-agent.runtime-broker.verified-workspace-recovery-enabled; startup refuses otherwise and with external provisioners. Any authenticated tenant actor can then allocate storage there and becomes its owner.
workspace-cwdQWEN_MANAGED_AGENT_WORKSPACE_CWDstring(empty)The working directory of the Broker’s default Workspace, used by Sessions that are not bound to a registered Workspace. Required when qwen.managed-agent.runtime-broker.enabled is true. With local-process it must exist and is resolved to its canonical path, from which the default workspace ID is derived (for the Session Store too, even while the Broker is disabled); kubernetes-workspace needs an absolute normalized path, and external provisioners an absolute normalized worker-side path other than /.
workspace-generationQWEN_MANAGED_AGENT_WORKSPACE_GENERATIONstring1The generation of the Broker’s default Workspace, carried in the Runtime scope of Sessions that are not bound to a registered Workspace. A non-empty string of at most 512 characters; required when qwen.managed-agent.runtime-broker.enabled is true.
workspace-idQWEN_MANAGED_AGENT_WORKSPACE_IDstring(empty)The ID of the Broker’s default Workspace, which Sessions not bound to a registered Workspace share with the Session Store. With local-process, empty derives the first 16 hex characters of the SHA-256 of the canonical qwen.managed-agent.runtime-broker.workspace-cwd, and a set value must equal that hash; other provisioners require it. With the Hosted Harness and Session Store enabled, startup refuses a value that differs from qwen.managed-agent.session-store.workspace-id. Keep it unchanged once Sessions exist, since unbound Sessions resolve their Store scope from it.
workspace-mounts—YAML list(empty)The administrator-mounted Workspace storage roots, set in a configuration file (YAML) as a list of entries with tenant-id, storage-id and root. Each root must be an existing canonical directory; roots must not overlap or alias each other, and each tenant and storage pair may appear once. Requires the local-process provisioner; startup refuses otherwise and with external provisioners or resident Workspaces. Every Broker sharing the database must use the same list.

qwen.managed-agent.runtime-broker.retention

Database cleanup of old terminal Runtime records (tool executions, Runtime Sessions and bindings), run in bounded batches on a dedicated scheduler.

PropertyVariableTypeDefaultDescription
batch-sizeQWEN_MANAGED_AGENT_RUNTIME_RETENTION_BATCH_SIZEinteger100How many records one retention tick may handle: it caps the bindings scanned, the child records scanned and the total rows deleted per tick. Must be between 1 and 1000; checked at startup even while retention is off.
enabledQWEN_MANAGED_AGENT_RUNTIME_RETENTION_ENABLEDbooleanfalseWhether the server periodically deletes old terminal Runtime records (tool executions, Runtime Sessions and bindings) from the database, in bounded batches on its own scheduler. Takes effect only when qwen.managed-agent.runtime-broker.enabled is also true. It never stops workers or deletes Workspace files, and it keeps records that are still referenced, such as recovery records, Workspace holders and unsettled child lineage.
max-ageQWEN_MANAGED_AGENT_RUNTIME_RETENTION_MAX_AGEduration30dHow long a terminal Runtime record must have been inactive before retention may delete it: a binding or Runtime Session is measured from its last activity, a tool execution from when it settled or was abandoned. A suffix-less number binds as days. Must be at least 1ms; checked at startup even while retention is off.
scan-delayQWEN_MANAGED_AGENT_RUNTIME_RETENTION_SCAN_DELAYduration1mHow long the retention job waits after one tick finishes before it starts the next. A suffix-less number binds as milliseconds. Must be at least 1ms; checked at startup even while retention is off.

qwen.managed-agent.runtime-broker.ssh

SSH Runtime nodes: hosts the server reaches over SSH, on which users may register Workspaces whose Runtime workers then run there.

PropertyVariableTypeDefaultDescription
enabled—boolean—Whether SSH Workspaces are offered: an actor listed in a node’s access may browse that node’s allowed roots and register a directory there as a Workspace; while off, those routes answer 404 ssh_runtime_disabled. Startup refuses it without qwen.managed-agent.harness.workspace-files-enabled or without qwen.managed-agent.runtime-broker.ssh.nodes, with an external provisioner, and under the managed-local profile.
nodes—YAML list(empty)The SSH Runtime nodes, set in a configuration file (YAML) as a list. Each entry has node-id and display-name, ssh-host (a host alias of the server account’s SSH configuration), the absolute node paths node-executable, qwen-entry and state-directory, allowed-roots (at least one absolute directory Workspaces may be registered under), publication-port (the node’s loopback port that tool publication is forwarded to over SSH), qwen-version (required; must equal the version the node reports) and access (the tenant-id and actor-id pairs that may use the node). Startup refuses an invalid entry. With nodes set, qwen.managed-agent.tool-publication.service-base-url must be an http URL.

qwen.managed-agent.session-store

The private Managed Session Store through which the Hosted Harness reads and writes Session journals on this server’s internal routes, and the writer credentials and leases that guard it.

PropertyVariableTypeDefaultDescription
allow-insecure-httpQWEN_MANAGED_AGENT_SESSION_STORE_ALLOW_INSECURE_HTTPbooleanfalseWhether a plaintext http qwen.managed-agent.session-store.base-url on a non-loopback host is accepted. Without it startup refuses such a URL, which every Harness would reject; with it the flag is passed to the Harness in each Session’s Store descriptor so its client accepts the URL.
base-urlQWEN_MANAGED_AGENT_SESSION_STORE_BASE_URLstring(empty)The URL at which the Hosted Harness reaches this server’s Session Store routes. Empty derives the loopback http URL of the serving listener (the internal one when qwen.managed-agent.internal-server.port is set) if it binds a blank, wildcard, 127.0.0.1 or ::1 address on a fixed port without TLS; otherwise set it. Startup refuses non-loopback plaintext http unless qwen.managed-agent.session-store.allow-insecure-http, and a loopback URL off the internal port. The managed-local profile requires a loopback http URL.
binding-keyQWEN_MANAGED_AGENT_SESSION_STORE_BINDING_KEYstring(empty)The secret HMAC key from which the control plane issues each Session’s Store writer credential to the Harness; with it the Store rejects any other token, without it the Harness mints its own (first writer wins). At least 32 bytes. Required by the Harness pool, and before the internal surface leaves loopback unless qwen.managed-agent.auth.allow-insecure-bind; must differ from qwen.managed-agent.auth.signing-key.
enabledQWEN_MANAGED_AGENT_SESSION_STORE_ENABLEDbooleanfollows qwen.managed-agent.harness.enabledWhether this server serves the private Session Store routes under /internal/managed-session-store/v1/ and gives Hosted Sessions a Store descriptor. Startup requires it while qwen.managed-agent.harness.enabled is true; Workspace files and the Harness pool need it too. It exposes the internal surface, so leaving loopback then needs qwen.managed-agent.session-store.binding-key unless qwen.managed-agent.auth.allow-insecure-bind is true. Unless set, the packaged configuration follows qwen.managed-agent.harness.enabled.
workspace-idQWEN_MANAGED_AGENT_WORKSPACE_IDstring(empty)The workspace ID that scopes the Store for Sessions not bound to a Workspace; bound Sessions use their own Workspace ID. Empty takes qwen.managed-agent.runtime-broker.workspace-id, otherwise the ID a local-process Broker derives from qwen.managed-agent.runtime-broker.workspace-cwd. Startup refuses it empty while the Harness uses the Store, and different from a set Runtime Broker ID. Keep it unchanged on an existing deployment.
writer-lease-durationQWEN_MANAGED_AGENT_SESSION_STORE_WRITER_LEASE_DURATIONduration60sHow long a Harness’s writer lease on a Session’s Store journal lasts before it must be renewed; also how long Session close or delete admission keeps an already-live writer. Must be between 1s and 300s: a value outside fails each Session’s Harness create or load rather than startup. A number without a unit is read as seconds.

qwen.managed-agent.tool-publication

Durable publication of Hosted Shell tool output to object storage: the storage target, capacity limits, operation and verification deadlines, and garbage collection.

PropertyVariableTypeDefaultDescription
active-captures—integer—How many tool output captures one tenant may have open at the same time; a further reservation is refused until one finishes. Required when qwen.managed-agent.tool-publication.enabled is true; must be at least 1 (startup refusal).
async-verification-enabledQWEN_MANAGED_AGENT_TOOL_PUBLICATION_ASYNC_VERIFICATION_ENABLEDbooleanfalseWhether clients may ask for asynchronous verification of publication operations with the X-Qwen-Tool-Publication-Async: 1 header, receiving HTTP 202 and polling for the outcome; otherwise every operation verifies synchronously. Turning it off stops new asynchronous admissions while already accepted operations still drain.
claim-timeout—duration—How long a server’s claim on an in-progress publication operation lasts; the holder renews it every third of this period, and a retry can take the operation over only after the claim lapses. Required when tool publication is enabled; must be positive and shorter than qwen.managed-agent.tool-publication.operation-timeout (startup refusal). A bare number is seconds.
deletion-graceQWEN_MANAGED_AGENT_TOOL_PUBLICATION_DELETION_GRACEduration24hHow long a retired Session’s tool output and Session resources are kept before garbage collection may delete them. Only takes effect with qwen.managed-agent.tool-publication.gc-enabled; the periodic retention log sample also uses it. Must not be negative (startup refusal when tool publication is enabled). A bare number is seconds.
enabledQWEN_MANAGED_AGENT_TOOL_PUBLICATION_ENABLEDbooleanfalseWhether the server accepts tool output publication: Hosted Shell executions stream their output through the internal /internal/managed-tool-publications API into object storage (Aliyun OSS unless a custom store bean is registered). Startup is refused unless this group’s service URL, capacities and deadlines are set, plus the OSS endpoint, region and bucket. Off a loopback address it also requires qwen.managed-agent.session-store.binding-key, unless qwen.managed-agent.auth.allow-insecure-bind is true.
entry-concurrency—integer—How many tool publication API requests this server process handles at once; a request beyond that gets HTTP 429 managed_tool_publication_busy. Required when tool publication is enabled; must be at least 1 (startup refusal).
execution-bytes—integer—How many bytes of output one tool execution may capture; it is also sent to the Harness as the capture limit for Shell and team-lead executions. Required when tool publication is enabled; must be between 1 byte and 2 TiB (2^41 bytes). Startup is refused if verifying that much output would exceed qwen.managed-agent.tool-publication.max-verification-timeout.
gc-enabledQWEN_MANAGED_AGENT_TOOL_PUBLICATION_GC_ENABLEDbooleanfalseWhether the server garbage-collects retired tool output: capture objects in object storage and the stored resources of retired Sessions, once qwen.managed-agent.tool-publication.deletion-grace has passed. Only read when qwen.managed-agent.tool-publication.enabled is true.
max-verification-timeout—duration—The longest deadline a publication verification may get. Must be positive and at most 25 minutes; startup is refused if qwen.managed-agent.tool-publication.operation-timeout plus the time to verify qwen.managed-agent.tool-publication.execution-bytes (and a fixed producer allowance) at qwen.managed-agent.tool-publication.verification-bytes-per-second exceeds it. Required when tool publication is enabled. A bare number is seconds.
operation-timeout—duration—How long a publication operation (upload, verification or finish) may run before its deadline; verifying stored content adds one second per qwen.managed-agent.tool-publication.verification-bytes-per-second bytes. Required when tool publication is enabled; must be positive and longer than qwen.managed-agent.tool-publication.claim-timeout (startup refusal). A bare number is seconds.
oss-bucket—string(empty)The Aliyun OSS bucket that stores tool output objects. Required when tool publication is enabled with the default OSS store (startup refusal); ignored when a custom ToolPublicationObjectStore bean is registered.
oss-endpoint—string(empty)The Aliyun OSS endpoint for tool output objects. Must be https://oss-<region>.aliyuncs.com for qwen.managed-agent.tool-publication.oss-region, with no path, query or user info (startup refusal otherwise). OSS credentials are secrets read from the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables (plus OSS_SESSION_TOKEN for a temporary token). Required with the default OSS store; ignored when a custom store bean is registered.
oss-region—string(empty)The Aliyun OSS region (for example cn-hangzhou) used for V4 request signing; it must match the qwen.managed-agent.tool-publication.oss-endpoint host. Required with the default OSS store (startup refusal); ignored when a custom store bean is registered.
service-base-url—string(empty)The base URL that Runtimes use to reach this server’s tool publication API; they resolve /internal/managed-tool-publications against it. Must be an absolute http or https URL without path, query or fragment; plaintext http to a non-loopback host is refused unless qwen.managed-agent.auth.allow-insecure-bind is true. Required when tool publication is enabled. With SSH Runtime nodes configured it must be an http URL.
session-bytes—integer—How many bytes of tool output one Session may hold reserved across its captures; each reservation counts its capture size plus a fixed overhead of 4784128 bytes. A reservation that would exceed it is refused. Required when tool publication is enabled; must be at least 1 (startup refusal).
tenant-bytes—integer—How many bytes of tool output one tenant may hold reserved across all its Sessions’ captures; each reservation counts its capture size plus a fixed overhead of 4784128 bytes. A reservation that would exceed it is refused. Required when tool publication is enabled; must be at least 1 (startup refusal).
verification-bytes-per-second—integer—The verification throughput floor in bytes per second: a verification deadline is qwen.managed-agent.tool-publication.operation-timeout plus one second for each this many bytes being verified, and must stay within qwen.managed-agent.tool-publication.max-verification-timeout. Required when tool publication is enabled; must be at least 1 (startup refusal).
verification-concurrencyQWEN_MANAGED_AGENT_TOOL_PUBLICATION_VERIFICATION_CONCURRENCYinteger2How many background threads verify asynchronously admitted publication operations. The verifier keeps running when qwen.managed-agent.tool-publication.async-verification-enabled is turned off, so accepted operations drain. Must be at least 1 (startup refusal when tool publication is enabled).
Last updated on
Run Managed Sessions locallyManaged Session worktrees