Skip to main content

Workspace Lanes

Workspace lanes are an opt-in substrate for agents that may serve multiple people. They let one agent persona keep shared persona files in the configured agent workspace while giving each user a separate lane workspace for user-specific files and generated state. Current scope: this release adds the core resolver, config schema, first-use seeding, lane-aware bootstrap loading, hook/plugin context, reply-path adoption, reset/session-memory lane routing, lane-local remote media staging, and a real two-user route proof. Do not treat workspace lanes as complete hosted multi-tenant isolation yet.

For Users

Most local users do not need workspace lanes. If you are the only person talking to your assistant, leave workspaceLanes unset and WednesdayAI keeps the existing single-workspace behavior. Workspace lanes matter when the same persona may answer more than one person. Without a lane model, files such as USER.md, MEMORY.md, generated notes, and downloaded artifacts can become shared context. With lanes enabled and adopted by a runtime path, WednesdayAI can keep the persona stable while separating user-specific context by lane. The default lane model is hybrid: workspaceLanes.create: "manual" never creates the lane directory on the reply path. Operators must provision the resolved lane directory first; otherwise WednesdayAI denies the lane for that turn and does not run the reply in the shared persona workspace. workspaceLanes.skills defaults to "shared". "lane" switches skill discovery, skill snapshots, and skill environment loading to the effective lane workspace. "both" is accepted as configuration for forward compatibility, but currently behaves like "shared" until precedence and conflict handling are specified and tested. Session isolation is separate. If multiple people can DM the bot, also configure session.dmScope: "per-channel-peer" or per-account-channel-peer. Session keys control conversation history. Workspace lanes control workspace files and bootstrap context.

For Administrators

Enable lanes only on personas that are intended to serve more than one user:
Most deployments should also set an explicit persona workspace:
enabled: true is per agent. There is no global default lane setting in this slice.

Lane keys

laneKey controls which actor fields choose a lane: Lane ids are deterministic digests, not raw sender ids. Missing actor fields deny the lane instead of falling back to an anonymous shared lane. Lane keys also decide which run paths can reach an agent at all:
  • Agent-RPC runs (subagents, sessions_send, announces, OpenAI-compatible HTTP, CLI, Discord voice) carry no channel sender of their own, so they are always denied on channel-peer and account-channel-peer lane agents.
  • account-channel-peer lane agents are unreachable from gateway clients: a gateway turn has no channel account.
  • On canonical-identity lane agents, a channel user who is not in session.identityLinks can no longer spawn or sessions_send into the agent — the run identity is validated against identityLinks keys, so an unlinked user’s delegations are denied instead of running in the shared persona workspace.

Linking gateway devices

Gateway turns (web client, Control UI) are sent by the verified device, so their sender id is device:<deviceId> — not the app id. Link each device to a person, and every turn from that device resolves the person’s canonical lane. From ADR 0104 on, the person is also the sender name: the model’s Sender block reads "label": "Alice (device:…)", "name": "Alice", with the client’s display name (for example MentraOS glasses) as a separate client provenance field. Link with wednesdayai devices link <deviceId> --identity <key>, or pair with wednesdayai qr --client <id> --identity <key> (or wednesdayai identity link <key> --qr) so the first connect links the device; wednesdayai devices remove also unlinks. See Identities. Get device ids with wednesdayai devices list --json (the deviceId field of each entry under paired). A device-less gateway turn is denied on every lane key; an unlinked device is denied on canonical-identity and account-channel-peer (see channel-peer below). The reason is shown to the requester:
  • Device not linked: This assistant keeps a private workspace for each person, and this device isn't linked to a person yet. Ask your administrator to link it: wednesdayai devices link <deviceId> --identity <your name>
  • No paired device: This assistant keeps a private workspace for each person, and this connection has no paired device identity, so it can't be linked to a person. Connect from a paired device.
  • account-channel-peer agent: This assistant keeps a workspace per channel account, so it can't be used from this app. Message it on its channel instead.
  • Otherwise (a linked turn the runtime still cannot serve): This assistant's private workspace isn't available. Ask your administrator to check the gateway log.
A Control UI running with gateway.controlUi.dangerouslyDisableDeviceAuth is treated as device-less — any presented device block is ignored — so it is denied on lane agents. Under channel-peer a device gets an isolated per-device lane (channel:webchat:peer:device:<deviceId>) whether or not it is linked.

Upgrading from app-id lanes (before the device sender)

Builds before the device sender keyed gateway turns on the app id, producing lanes named lane-<hash> with the preimage agent:<agentId>:channel:<channel>:account:<accountId>:peer:openclaw-user-client. Those lanes are shared by every web user of the agent and become orphaned once the device sender is live. Find each one by hashing its preimage — laneId = "lane-" + sha256(preimage).hex.slice(0, 24) (Node: crypto.createHash("sha256").update(preimage).digest("hex").slice(0, 24)) — then merge it into the person’s canonical lane (agent:<agentId>:canonical:<identityLinks key>) by hand: one app-id lane may hold several people’s data, so do not wholesale-rename without reviewing the files.

Root templates

rootTemplate accepts only {agentId} and {laneId} placeholders. {laneId} is required so two users cannot collapse into the same workspace. Templates with traversal segments, blank values, unsupported placeholders, or malformed braces are denied. Keep lane roots under controlled WednesdayAI state unless you have an operator-managed storage plan. Avoid broad roots such as the home directory. When a resolved lane path already exists, it must be a directory; regular files, symlinks, and other non-directory entries are denied.

Creation and seed files

create: "on-first-message" creates the effective lane workspace when first resolved, unless a non-directory entry already exists at that path. create: "manual" requires the lane directory to exist before the turn starts; a missing path or non-directory entry denies the lane. Default seed files are:
  • USER.md
  • BOOTSTRAP.md
Seed files are copied from the persona workspace only when the lane is created. Existing lane files are not overwritten, and persona files added or changed after creation are not propagated into existing lanes: a lane that deletes its BOOTSTRAP.md after completing onboarding does not get it back on later turns. Symlink and hardlink aliases that escape the persona workspace are skipped, and dangling symlinks in the lane are treated as existing rather than followed. Creation is atomic: the lane directory is seeded in a hidden temporary sibling of the lane path, named .<lane directory name>.creating-<uuid> (under the default root template: .workspace.creating-<uuid> inside lanes/<laneId>/), and renamed into place only after every seed file has been written. A failed seed write removes the temporary directory and fails that turn; the next turn retries creation, so a published lane always has its seed files. A leftover .<lane directory name>.creating-<uuid> directory can only come from a crash mid-creation and is safe to delete. Each lane completes onboarding independently: the lane’s agent deletes its own BOOTSTRAP.md copy when the ritual is done, and the shared persona workspace keeps its BOOTSTRAP.md as the seed template for new lanes.

Supported strategies

The config schema accepts reserved strategy names for forward compatibility, but runtime support in this slice is hybrid only. Other values are denied by policy until a later task implements them.

Sandbox lane fencing

When sandboxing is enabled, set fenceToLane: true in the agent’s sandbox config to bind the sandbox tool filesystem to the user’s effective lane workspace instead of the shared persona root. Without this flag, a sandboxed multi-lane agent can still traverse up to the persona root and reach sibling lane directories via the workspace mount.
workspaceAccess: "rw" is required for complete lane isolation. With "none" or "ro", the sandbox uses a scope-keyed workspace directory seeded from the lane directory — two sessions that share the same scope key across lanes can read each other’s seeded files. WednesdayAI logs a warning at session setup when fenceToLane: true and workspaceAccess is not "rw". The fence only restricts tool filesystem access. Bootstrap resolution still happens before sandbox entry, but it is not persona-only: lane-aware bootstrap loading can still select lane-local files such as AGENTS.md, with persona fallback where applicable. The fence takes effect only when workspace lanes are enabled, the lane is resolved, and the policy decision is "allowed" — it has no effect in single-user (mode: "single") or denied configurations.

Migration notes

Existing per-agent workspaces keep working when workspaceLanes is unset. To migrate an existing persona, keep the current workspace path as the persona workspace, enable lanes on that agent, and let first-use seeding copy USER.md and BOOTSTRAP.md into each lane. Review any existing MEMORY.md, memory/, downloads, and generated files before enabling lanes; move user-specific content into the correct lane rather than leaving it in the shared persona root. Feishu-style dynamic agents remain on the legacy-compatible per-agent workspace path unless their resolved agent config enables workspaceLanes. Do not use lanes to replace dynamic-agent selection; use lanes only to separate user-specific files inside a persona that may be shared by multiple users.

For Developers

Workspace lane data is additive. Existing hooks and plugins continue to run without lane fields.

Gateway senders and lane denials

Gateway turns (chat.send, sessions.steer, talk) carry SenderId: "device:<deviceId>" when the connect frame has a verified device block, and the app id (for example openclaw-user-client) only when it does not. A Control UI running with gateway.controlUi.dangerouslyDisableDeviceAuth counts as device-less: any presented device block is ignored. A device:<id> sender resolves to the person recorded as the device’s owner on its pairing record (devices link, or a setup code with --identity), never to a device: value in session.identityLinks; nothing re-derives identity from the session key or the delivery route. For a linked device the sender name (ADR 0104) is the identityLinks key; the raw device:<id> stays the sender id and the client display name is the Sender-block client field. A lane-enabled agent resolves the lane from the validated run identity on every path. A run that cannot be attributed to a linked identity fails closed with WorkspaceLaneDeniedError (message is user-facing, agentId names the agent):
  • Gateway turns: the denial message is broadcast to the requesting client as the turn’s error, and no assistant message is appended to chat.history. sessions.steer checks lane admission before it touches the active run, so a denied requester cannot abort another person’s turn and receives the reason as an RPC error.
  • agent RPC (sessions_send, subagents, announces, Discord voice) and the CLI: the gateway agent error frame carries details.reason: "workspace_lane_denied", agent.wait ends with status: "error" and the message, and the CLI prints the denial and exits 1 instead of falling back to an embedded run.
  • OpenAI-compatible HTTP: /v1/chat/completions answers 403 with { "error": { "message": …, "type": "permission_error" } }, /v1/responses with { "error": { "code": "permission_error", "message": … } }; streams carry Error: <message> content / response.failed respectively.
For canonical-identity agents the agent-RPC denial reads: Agent "<agentId>" keeps a private workspace for each person, and this run is not attributed to a linked identity in session.identityLinks. For channel-peer and account-channel-peer agents every agent-RPC run is denied, because those runs have no channel sender: Agent "<agentId>" keeps a workspace per channel sender, so runs without a channel sender (subagents, sessions_send, HTTP, CLI) can't use it. Trust boundary: lane isolation holds against narrow-scope clients (the user client). operator.write callers of the agent RPC are trusted to assert inheritedCanonicalIdentity, which is only checked against identityLinks keys. Denials on channel turns (Telegram, Discord, …) stay silent — an unlinked stranger gets no reply — and this is unchanged.

Lane admission and resolution API

src/agents/workspace-lanes.ts is the resolver seam:
  • checkWorkspaceLaneAdmission({ cfg, agentId, personaWorkspaceDir, actor }) is the side-effect-free admission check: the policy decision plus the on-disk gates (create: "manual" and non-directory paths). Pre-checks must call it instead of resolveWorkspaceLane so a pre-check admits exactly what the turn admits. sessions.steer uses it before touching the active run.
  • resolveWorkspaceLaneForTurn(...) runs the same admission and then creates and seeds the lane when create is "on-first-message". The reply path calls it with the actor built by buildWorkspaceLaneActor (src/auto-reply/reply/workspace-lane-actor.ts): a gateway turn keys the lane on the device: sender only, and channel turns keep their channel actor fields.
  • WorkspaceLaneResolution carries mode, agentId, laneId, laneKeySource, actor, personaWorkspaceDir, effectiveWorkspaceDir, created, and policy: { decision, reason? }. workspaceLaneCorrelationId exposes laneId only for an allowed multi-lane run.

Agent-RPC lane resolution and skills

resolveAgentCommandWorkspace (src/commands/agent/workspace-lane.ts) is the seam every agent-RPC run path shares: the gateway agent method, sessions_send, subagent spawns and announces, Discord voice, and the CLI agent command.
  • A non-lane agent keeps the persona workspace for the run and for skills; nothing changes.
  • A lane-enabled agent resolves the run identity with resolveRunSenderIdentity — the same inputs the run itself uses, so the lane identity equals the run identity — and keys the lane on that identity alone. The request’s channel, to, and accountId are delivery targets, and inheritedSenderId is an unvalidated wire value; neither keys a lane.
  • An unattributed run throws WorkspaceLaneDeniedError before any model call. An allowed run gets ensureAgentWorkspace on the lane directory (bootstrap files are not seeded) and a workspaceLane resolution to forward to the embedded or CLI runner.
  • skillWorkspaceDir is the lane directory when the agent sets workspaceLanes.skills: "lane", otherwise the persona directory. The reply path derives it the same way. Skill snapshots record their source directory (skillWorkspaceDir on the snapshot) and are rebuilt when the current run has a different one, so one lane never reuses another lane’s skills. A snapshot without the field predates this change and counts as persona-built: only a run whose skill source is a lane directory rebuilds it, so non-lane agents never rebuild on the legacy shape.

The lane denial marker

Every lane denial carries details.reason: "workspace_lane_denied" on the gateway error frame (WORKSPACE_LANE_DENIED_REASON, a dependency-free constant in src/agents/workspace-lane-denied-reason.ts). Read it back from a rejected gateway client request with gatewayErrorReason(err) (src/gateway/client.ts) instead of matching the message text. Core behavior keys on the marker: the CLI agent command skips its embedded fallback, sessions_send reports status: "error" with the denial instead of waiting out a timeout, and a denied subagent announce settles without retry (see Sub-agents).

Bootstrap hooks

agent:bootstrap hook context can include:
When present, workspaceDir is the effective workspace for the current bootstrap pass and workspaceLane.personaWorkspaceDir points at the shared persona workspace. Denied lane resolutions are not exposed to bootstrap hooks.

Plugin runtime context

Plugin agent-hook and tool context can include:
Treat these fields as optional. A plugin should keep its current behavior when workspaceLane is undefined. The message_received plugin hook still runs before workspace-lane resolution, so it does not receive workspaceLane in this slice. Message-hook types keep the optional fields for future lane-aware message surfaces and compatibility, but plugins must not rely on them for message_received.

Reading workspace files

Lane-aware bootstrap loading reads shared files from personaWorkspaceDir and lane-local files from effectiveWorkspaceDir. This applies to embedded runs and CLI-provider runs that receive an allowed workspaceLane. Custom project context paths use POSIX-style / separators for source-plan matching; backslashes are treated as literal filename characters. Root-level variants such as ./AGENTS.md are matched by basename, while nested paths such as notes/AGENTS.md stay lane-local unless that full path or a parent directory is explicitly listed in sharedFiles.

Sandbox context and lane fencing

resolveSandboxContext accepts an optional workspaceLane parameter. When a sandbox config has fenceToLane: true, passing the resolved WorkspaceLaneResolution causes the sandbox workspace to be bound to workspaceLane.effectiveWorkspaceDir instead of the agent workspace root. Embedded compact sessions (compactEmbeddedPiSessionDirect) thread the lane through to sandbox setup automatically when workspaceLane is included in the compact params. Plugin and hook authors do not need to wire this themselves — the runtime handles it. It is documented here for authors building custom compact flows or sandbox integrations that call resolveSandboxContext directly.

Correlating by lane

providerConversationId is the opaque provider/cache session identity derived from agentId + (sessionKey || sessionId). It is NOT lane-specific: in a multi-user group agent with workspace lanes, several lane users can share one providerConversationId. To partition correctly per lane, consumers (e.g. brain/background/cache systems) should dedupe on the composite key:
laneId is the opaque lane-<hash> digest, present only for an allowed multi-lane turn and undefined for single-user and denied resolutions. Never correlate on raw identityLinks or a lane hash preimage — they are intentionally stripped from runtime metadata.

Do not overclaim isolation

Workspace lanes provide product-context isolation for mostly trusted users. They are not hostile multi-tenant sandboxing, an auth system, organization model, billing boundary, quota system, or cloud-storage mapper. Hosted frameworks should carry lane metadata into their own storage, authorization, audit, and runtime policies.

Per-lane usage accounting

The model_call_ended hook’s context (ctx) carries a laneId field (available since the lane-correlation SDK surface, Slice 1) with the opaque lane-<hash> identifier for every turn in an allowed multi-lane session. Operators can use this field to partition token counts by lane for billing, auditing, or per-user cost attribution:
laneId is undefined for single-user agents or denied resolutions — these fall through to existing non-lane accounting. providerConversationId is NOT per-lane (it is provider/cache session identity shared by all lanes of a session); use laneId for per-lane attribution.