> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Lanes

# 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:

| File or state | Default location |
| - | - |
| `AGENTS.md` | shared persona workspace |
| `SOUL.md` | shared persona workspace |
| `IDENTITY.md` | shared persona workspace |
| `TOOLS.md` | shared persona workspace |
| `HEARTBEAT.md` | shared persona workspace |
| `USER.md` | lane workspace |
| `BOOTSTRAP.md` | lane workspace when copied on creation |
| `MEMORY.md` and `memory.md` | lane workspace |
| Generated files, downloads, artifacts | lane workspace on adopted runtime paths |
| Workspace-local skills | shared persona workspace by default |

`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:

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "support",
        workspaceLanes: {
          enabled: true,
        },
      },
    ],
  },
}
```

Most deployments should also set an explicit persona workspace:

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "support",
        workspace: "~/.openclaw/workspaces/support",
        workspaceLanes: {
          enabled: true,
          strategy: "hybrid",
          laneKey: "canonical-identity",
          rootTemplate: "~/.openclaw/agents/{agentId}/lanes/{laneId}/workspace",
          create: "on-first-message",
        },
      },
    ],
  },
}
```

`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:

| Value | Behavior |
| - | - |
| `canonical-identity` | Uses `session.identityLinks` when available. On channel turns it falls back to channel/account/peer identity; gateway (web client) turns have no fallback — the sender must be a linked device. |
| `account-channel-peer` | Uses account id, channel, and sender or conversation identity. |
| `channel-peer` | Uses channel and sender or conversation identity. |

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](https://docs.wednesdayai.dev/next/admin/gateway/identity).

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](https://docs.wednesdayai.dev/next/admin/gateway/sandboxing.md) 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.

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "support",
        workspaceLanes: { enabled: true },
        sandbox: {
          mode: "all",
          workspaceAccess: "rw",
          fenceToLane: true,
        },
      },
    ],
  },
}
```

`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](https://docs.wednesdayai.dev/next/users/tools/subagents.md)).

### Bootstrap hooks

`agent:bootstrap` hook context can include:

```ts theme={"dark"}
workspaceLane?: WorkspaceLaneResolution;
```

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:

```ts theme={"dark"}
canonicalIdentity?: string;
laneId?: string;
workspaceLane?: WorkspaceLaneResolution;
```

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:

```text theme={"dark"}
providerConversationId + (laneId ?? canonicalIdentity ?? hashedUserId ?? sessionKey) + turnId + (entryId ?? cursor.entryId ?? rawSha256)
```

`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:

```typescript theme={"dark"}
// Example: log token usage per lane in a model_call_ended hook
// laneId lives on the hook CONTEXT (second arg), not the event itself.
export default async function (event, ctx) {
  const laneId = ctx.laneId ?? ctx.runtimeIdentity?.laneId; // "lane-<sha256-24>" or undefined
  if (laneId) {
    metricsClient.record("tokens.used", event.usage?.total, { lane: laneId });
  }
}
```

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.