@exagone313/dsh-podman 0.2.0-rc.2

package/docs/architecture.md

@@ -0,0 +1,173 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Architecture
+
+dsh-podman has three components:
+
+| Component                 | Runs                                      | What it does                                                                                           |
+| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `@exagone313/dsh-podman`  | Inside dsh itself                         | Registers `ctx.subprocess` and `ctx.fs` backed by the orchestrator                                     |
+| `dsh-podman-guest-agent`  | Inside every guest container              | Serves the exec/filesystem gRPC API for one workspace                                                  |
+| `dsh-podman-orchestrator` | A container with access to the Podman API | Owns the control socket and persisted state; creates/removes guest containers; builds workspace images |
+
+The plugin auto-creates a missing workspace using its configured default image
+and a single read-write project mount; `container_mount_update` can remount that
+mount read-only. It never falls back to host execution.
+
+## Control plane
+
+The plugin connects to the orchestrator over a Unix socket at
+`<socketsRoot>/orchestrator.sock` and talks gRPC. Requests carry the shared
+token (`DSH_PODMAN_ORCHESTRATOR_TOKEN`) as an `authorization: bearer` header.
+
+The orchestrator service exposes these gRPC methods (backing both the UI and the
+tools): `ListContainers` (returns only the guest containers the orchestrator
+created — containers it does not own are never exposed),
+`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env,
+paths}`
+(creates or replaces a container in the workspace's pod; an empty `container`
+targets the default container and other names are validated),
+`RecreateContainer{workspace_slug, container, image_id, mounts, env, paths}`
+(stops, removes, and recreates a container, optionally with a new image, project
+mounts, environment, or PATH additions; an empty `image_id` keeps the
+workspace's current image), `RemoveContainer`, `AddContainerMount`,
+`RemoveContainerMount`, `SetContainerPaths`, `AddContainerSecret`, and
+`RemoveContainerSecret`.
+
+## Workspaces and pods
+
+Each workspace maps to a **podman pod** (`dsh-podman-<slug>`, where `<slug>` is
+the workspace UUID) so its containers share a network namespace. Every workspace
+has a **default container** (`dsh-podman-<slug>-default`); additional, named
+containers (`dsh-podman-<slug>-<name>`) can be created inside the same pod.
+Containers' root filesystems are mounted read-only, with podman's read-write
+tmpfs on `/tmp`, `/var/tmp`, and `/run` (and `/dev` and `/dev/shm` left
+writable). All other writable state lives in the project bind mount, named
+volumes, or tmpfs mounts. `/tmp` and `/var/tmp` are reachable through the guest
+file API, and the guest agent spills oversized command output under
+`/tmp/dsh-podman`. Oversized tool results are spilled there too, under
+`/tmp/dsh-podman/spill/<session>/`, by the plugin's `ctx.spillStore` — so the
+model reads the artifact back with the container file tools instead of a host
+path the container cannot reach.
+
+A workspace's pod is torn down when its last container is removed, or directly
+through `RemoveWorkspace` (the settings card's **Remove pod** action), which
+stops the containers' daemons, removes the pod and its containers, cleans their
+socket directories, and drops the stored workspace. Volumes, secrets, and
+project data are left untouched.
+
+Beyond project mounts, a container can mount named volumes (prefixed
+`DSH_PODMAN_VOLUME_PREFIX`, default `dsh-podman-`, and auto-created by podman on
+first use), secrets, or tmpfs at arbitrary container paths — except where they
+would overlap a reserved path:
+
+- `DSH_PODMAN_PROJECTS_ROOT`, reserved for project mounts;
+- `DSH_PODMAN_SOCKETS_ROOT`, which carries the guest agent's socket;
+- `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`, which the container runs its entry point
+  from;
+- `/tmp`, which podman mounts as the read-write tmpfs the guest file API reaches
+  and where command output is spilled.
+
+A destination that contains a reserved path is refused as well as one that sits
+inside it, since it would hide everything beneath it.
+
+Commands run through the guest exec API get `/dev/null` on stdin unless the
+caller explicitly asks for a pipe, so a command that reads stdin sees EOF
+instead of blocking (a bare `rg`/`grep` with no path therefore searches the
+working directory rather than reading an empty pipe). `container_glob` and
+`container_grep` also pass their resolved path to ripgrep as the search
+directory, never as a `--glob` pattern (a path containing `/` would never match
+one), and a ripgrep failure (exit code 2) is reported as a tool error rather
+than an empty result. Ripgrep anchors a `--glob` pattern containing `/` to the
+process working directory, so a discovery listing the harness starts with an
+absolute search root runs from that root: `glob`'s `pattern` then anchors to its
+`path` while the printed paths stay absolute.
+
+Project mounts resolve through symlinks and are confined to the projects root,
+so a symlink inside a writable project cannot redirect the bind mount to a path
+outside it. Symlinks with absolute targets are never followed; name the other
+project directly instead.
+
+## Guest agent and daemons
+
+The orchestrator starts the guest agent inside each container over the
+container's socket directory. The guest agent serves the exec/filesystem gRPC
+API for that workspace, runs and supervises background **daemons**, and reads
+and writes files. Each guest container gets exactly one socket directory
+bind-mounted into it, so a guest never sees the orchestrator's control socket
+nor any other workspace's socket directory.
+
+Commands and daemons inherit the guest agent's environment, minus the reserved
+`DSH_PODMAN` namespace: the agent's own token stays with the agent instead of
+being copied into everything it starts. A daemon started with `inheritEnv=false`
+instead receives only the `PATH`/`HOME` baseline plus its own `env`.
+
+Each container also carries ordered **PATH additions**. The orchestrator
+persists them (`SetContainerPaths`) and hands them to the guest agent as
+`DSH_PODMAN_GUEST_PATHS` on every create or recreate; the agent holds them in
+memory (`SetPaths`/`GetPaths` over its gRPC API) and prepends them to the PATH
+of every process it starts, including the plugin's `ctx.subprocess` provider, so
+the built-in shell and filesystem tools see them too. Changing the list does not
+recreate the container, so daemons started earlier keep their old PATH.
+
+Under `read-only` permission the harness sandbox cannot confine commands (the
+plugin replaces `ctx.subprocess`/`ctx.fs` and unwraps the `landlock-run`
+wrapper), so the plugin enforces the mode itself: a shell or file tool runs only
+when every mount that carries a mode is `read_only`. Otherwise the plugin asks
+through the approval service under the reserved tool name
+`dsh_podman_builtin_remount_read_only` — which the browser half renders with its
+own **Remount & run** labels — and, on approval, recreates the container with
+the read-write mounts forced read-only before running the tool. The harness's
+`sandbox_permissions` escalation is granted without prompting for the same
+reason: the widening it asks for has no effect here.
+
+Recreating a container or shutting down the orchestrator first asks the
+container's guest agent to gracefully stop its daemons (SIGTERM, ~10s grace)
+before podman tears the container down.
+
+## Images
+
+The orchestrator builds workspace images through Podman (see
+[Usage](usage.md#image-model) for the primitive/base/custom tiers). Base images
+are built locally from their primitive reference (or pulled when
+`DSH_PODMAN_BASE_IMAGE_PREFIX` points at a registry) without any guest-agent
+binary. The guest agent is provided at container creation by mounting its own
+image read-only into the container (see [Configuration](configuration.md)).
+Custom images are layered on top of a parent image and add extra packages. Every
+build streams its context to the Podman API as a tar holding the generated
+Containerfile, so a build writes nothing to the orchestrator's state directory.
+
+`image_rebuild_all` first ensures every base image (building locally or pulling
+from a public registry per `DSH_PODMAN_BASE_IMAGE_PREFIX`), then rebuilds the
+stored custom images **in dependency order** — each parent before the images
+derived from it. An image whose rebuild fails, and every image that depends on
+it, is reported in `skipped` while the rest continue.
+
+When a host cache is configured (`DSH_PODMAN_HOST_*_CACHE`, mounted into both
+the build container and the orchestrator), builds reuse downloaded packages. The
+settings card reports each cache's size and can clean it — keep the newest
+version of every package, or empty the cache. The builder serializes a cleanup
+against builds with a read/write lock, so a cleanup never deletes a package out
+from under a running build.
+
+## Settings card transport
+
+The card talks to the host over one authenticated fetch route below the harness
+API path (`/api/podman/card`), registered on the connection service so the
+carrier applies its Host/Origin fence and browser authentication first:
+
+- `GET` returns the live orchestrator snapshot (containers, images, workspaces,
+  volumes, secrets, caches), built fresh on every request.
+- `POST` runs exactly one command (`remove` / `recreate` / `create` /
+  `image_rebuild` / `image_rebuild_all` / volume / secret / secret-env / mount
+  ops) against the orchestrator and returns the notice to show.
+
+The settings namespace therefore holds **only real preferences**: the default
+image, the sockets root, and the card's active locale (`uiLocale`, so the host
+can render approval text in the session language — see
+[Approval](usage.md#approval)). Nothing derived from the orchestrator is
+persisted, and no command round-trips through the settings document.

package/docs/architecture.zh.md

@@ -0,0 +1,129 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 架构
+
+dsh-podman 由三个组件组成：
+
+| 组件                      | 运行位置                     | 功能                                                                   |
+| ------------------------- | ---------------------------- | ---------------------------------------------------------------------- |
+| `@exagone313/dsh-podman`  | dsh 内部                     | 注册由 orchestrator 提供支撑的 `ctx.subprocess` 和 `ctx.fs`            |
+| `dsh-podman-guest-agent`  | 每个 guest 容器内部          | 为一个工作区提供 exec/filesystem gRPC API                              |
+| `dsh-podman-orchestrator` | 一个可访问 Podman API 的容器 | 持有 control socket 和持久化状态；创建/删除 guest 容器；构建工作区镜像 |
+
+该插件会自动使用其配置的默认镜像和单个读写项目挂载来创建缺失的工作区；`container_mount_update`
+可将该挂载重新挂载为只读。它绝不会回退到主机执行。
+
+## 控制平面
+
+插件通过位于 `<socketsRoot>/orchestrator.sock` 的 Unix socket 连接
+orchestrator（编排器）并通信 gRPC。请求携带共享
+token（`DSH_PODMAN_ORCHESTRATOR_TOKEN`）作为 `authorization: bearer` 标头。
+
+orchestrator 服务公开以下 gRPC 方法（同时支撑 UI
+和工具）：`ListContainers`（仅返回 orchestrator 创建的 guest
+容器——它不拥有的容器永远不会被暴露）、`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env, paths}`（在工作区的
+pod 中创建或替换容器；空的 `container`
+指向默认容器，其他名称会被校验）、`RecreateContainer{workspace_slug, container, image_id, mounts, env, paths}`（停止、删除并重新创建容器，可选择使用新镜像、项目挂载、环境或
+PATH 附加项；空的 `image_id`
+保留工作区当前的镜像）、`RemoveContainer`、`AddContainerMount`、`RemoveContainerMount`、`SetContainerPaths`、`AddContainerSecret`
+和 `RemoveContainerSecret`。
+
+## 工作区与 pod
+
+每个工作区映射到一个 **podman pod**（`dsh-podman-<slug>`，其中 `<slug>` 是工作区
+UUID），因此其容器共享一个网络命名空间。每个工作区都有一个
+**默认容器**（`dsh-podman-<slug>-default`）；可以在同一个 pod
+内创建额外的、命名的容器（`dsh-podman-<slug>-<name>`）。容器的根文件系统以只读方式挂载，`/tmp`、`/var/tmp`
+和 `/run` 上是 podman 的可写 tmpfs（`/dev` 和 `/dev/shm`
+保持可写）。所有其他可写状态都存在于项目绑定挂载、命名卷或 tmpfs 挂载中。guest
+文件 API 可以访问 `/tmp`，而 guest agent 会把超出上限的命令输出写入
+`/tmp/dsh-podman` 下的溢出文件。
+
+工作区的 Pod 会在其最后一个容器被移除时拆除，也可直接通过
+`RemoveWorkspace`（设置卡片中的 **移除 Pod**
+操作）拆除：它会停止各容器的守护进程、移除 Pod 及其容器、清理它们的 socket
+目录，并删除存储的工作区记录。卷、机密和项目数据保持不变。
+
+除了项目挂载之外，容器还可以在任意容器路径挂载命名卷（以
+`DSH_PODMAN_VOLUME_PREFIX` 为前缀，默认 `dsh-podman-`，由 podman
+在首次使用时自动创建）、机密或 tmpfs——除非它们会与保留路径重叠：
+
+- `DSH_PODMAN_PROJECTS_ROOT`，保留给项目挂载；
+- `DSH_PODMAN_SOCKETS_ROOT`，承载 guest agent 的 socket；
+- `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`，容器从其运行入口点；
+- `/tmp`，podman 在其中挂载 guest 文件 API 可访问的可写
+  tmpfs，命令输出也溢出写入其中。
+
+包含保留路径的目标会被拒绝，位于其内部的目标同样会被拒绝，因为它会隐藏其下的所有内容。
+
+项目挂载会解析符号链接并被限制在 projects root
+内，因此可写项目中的符号链接不能将绑定挂载重定向到其外部的路径。带有绝对目标的符号链接永远不会被跟随；请直接命名另一个项目。
+
+## Guest agent 与守护进程
+
+orchestrator 通过容器的套接字目录在每个容器内启动 guest agent（来宾代理）。guest
+agent 为该工作区提供 exec/filesystem gRPC
+API，运行并监督后台**守护进程**，并读取和写入文件。每个 guest
+容器恰好获得一个绑定挂载到其中的套接字目录，因此 guest 永远不会看到 orchestrator
+的 control socket，也不会看到任何其他工作区的套接字目录。
+
+命令和守护进程继承 guest agent 的环境，减去保留的 `DSH_PODMAN` 命名空间：agent
+自身的 token 保留在 agent 中，而不会被复制到它所启动的每个东西中。以
+`inheritEnv=false` 启动的守护进程则只接收 `PATH`/`HOME` 基线以及自身的 `env`。
+
+每个容器还携带有序的 **PATH 附加项**。orchestrator
+会持久化它们（`SetContainerPaths`），并在每次创建或重建时以
+`DSH_PODMAN_GUEST_PATHS` 交给 guest agent；agent 将它们保存在内存中（通过其 gRPC
+API 的 `SetPaths`/`GetPaths`），并添加到它启动的每个进程的 PATH 之前，包括插件的
+`ctx.subprocess` 提供者，因此内置的 shell
+和文件系统工具也能看到它们。更改列表不会重建容器，因此先前启动的守护进程仍使用旧的
+PATH。
+
+在 `read-only` 权限下，harness 沙箱无法约束命令（插件替换了
+`ctx.subprocess`/`ctx.fs` 并解开了 `landlock-run`
+包装），因此由插件自行执行该模式：只有当所有带模式的挂载都是 `read_only`
+时，shell 或文件工具才能运行。否则插件会以保留的工具名
+`dsh_podman_builtin_remount_read_only` 通过审批服务询问——浏览器端会用其自己的
+**重新挂载并运行**
+按钮渲染该提示——并在获准后以强制只读的挂载重建容器，再运行该工具。出于同样的原因，harness
+的 `sandbox_permissions` 升权会被直接授予而不询问：它请求的放宽在此处没有效果。
+
+重新创建容器或关闭 orchestrator 时，会先要求容器的 guest agent
+优雅地停止其守护进程（SIGTERM，约 10 秒宽限期），然后 podman 才会拆除该容器。
+
+## 镜像
+
+orchestrator 通过 Podman 构建工作区镜像（有关原始/基础/自定义分层，请参阅
+[使用](usage.zh.md#镜像模型)）。基础镜像在其原始引用的基础上在本地构建（或在
+`DSH_PODMAN_BASE_IMAGE_PREFIX` 指向注册表时拉取），不包含任何 guest-agent
+二进制。guest agent 在创建容器时通过将其自身镜像只读挂载到容器中来提供（请参阅
+[配置](configuration.zh.md)）。自定义镜像在父镜像之上分层并添加额外的软件包。
+每次构建都会以包含所生成 Containerfile 的 tar 形式将构建上下文流式传输给 Podman
+API，因此构建不会向 orchestrator 的状态目录写入任何内容。
+
+`image_rebuild_all` 首先确保每个基础镜像（根据 `DSH_PODMAN_BASE_IMAGE_PREFIX`
+在本地构建或从公共注册表拉取），然后**按依赖顺序**重建存储的自定义镜像——每个父镜像都在从它派生的镜像之前。重建失败的镜像以及依赖它的每个镜像都会被报告在
+`skipped` 中，其余镜像继续。
+
+配置了主机缓存时（`DSH_PODMAN_HOST_*_CACHE`，同时挂载到构建容器和 orchestrator
+中），构建会复用已下载的软件包。设置卡片会报告每个缓存的大小并可清理它——保留每个软件包的最新版本，或清空缓存。构建器用读写锁将清理与构建串行化，因此清理绝不会在构建进行时删除其正在使用的软件包。
+
+## 设置卡片传输
+
+卡片通过 harness API 路径（`/api/podman/card`）之下的一个已认证 fetch
+路由与主机通信；该路由注册在 connection 服务上，因此承载层会先应用其 Host/Origin
+校验和浏览器认证：
+
+- `GET` 返回 orchestrator
+  的实时快照（容器、镜像、工作区、卷、机密、缓存），每次请求都重新构建。
+- `POST` 针对 orchestrator 恰好执行一个命令（`remove` / `recreate` / `create` /
+  `image_rebuild` / `image_rebuild_all` / volume / secret / secret-env / mount
+  操作），并返回要显示的提示。
+
+因此设置命名空间中**只保留真正的偏好**：默认镜像、sockets
+根目录，以及卡片的当前语言（`uiLocale`，以便主机以会话语言呈现审批文本——参见[审批](usage.zh.md#审批)）。orchestrator
+派生的任何内容都不会被持久化，也不会有命令经由设置文档往返。

package/docs/configuration.md

@@ -0,0 +1,160 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Configuration
+
+Environment variables use the `DSH_PODMAN_` prefix and are listed under the
+component that reads them (a variable read by several components appears in each
+of their sections). The plugin also exposes a few **UI settings** in the dsh
+**Settings → Plugins** card, listed separately from env vars.
+
+The plugin reads its configuration from, in order: the plugin `config` in
+cordis, then the environment variables below, then built-in defaults.
+
+## Plugin (dsh client) — environment variables
+
+| Variable                        | Default                 | Description                                                                                      |
+| ------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `DSH_PODMAN_IMAGE_PREFIX`       | `localhost/dsh-podman/` | Prefix prepended to workspace image references                                                   |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                       | Shared secret authenticating control-plane gRPC calls; see [Variable details](#variable-details) |
+| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`             | Project root used to resolve session working directories into a workspace                        |
+| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman`       | Socket root the plugin derives the orchestrator control socket (`orchestrator.sock`) from        |
+
+`projectsRoot` and `imagePrefix` are env-only so they match the orchestrator;
+`controlToken` comes from the plugin `config` or
+`DSH_PODMAN_ORCHESTRATOR_TOKEN`.
+
+## Plugin (dsh client) — UI settings
+
+Editable in the card's **Settings → Plugins → Podman** panel (the Configuration
+section and the images' Set-default popup):
+
+| Setting        | Default                   | Description                                                                                                |
+| -------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `defaultImage` | `archlinux`               | Image **short name** used for new workspaces; chosen from base and custom images via the Set-default popup |
+| `socketsRoot`  | `DSH_PODMAN_SOCKETS_ROOT` | Socket root the plugin uses to reach the orchestrator; falls back to the env var                           |
+
+| Variable                                       | Default                       | Description                                                                                                                                                                                                        |
+| ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DSH_PODMAN_BASE_IMAGE_PREFIX`                 | `localhost/dsh-podman/base/`  | Prefix under which base images are tagged; a `localhost/` prefix builds them locally, otherwise they are pulled from a public registry                                                                             |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE`                 | —                             | Guest-agent image mounted read-only into every guest container; unset disables the feature; see [Variable details](#variable-details)                                                                              |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`       | `/bin/dsh-podman-guest-agent` | Path of the guest agent binary inside the guest-agent image; the container command is `<mount>/<agent_bin>`; see [Variable details](#variable-details)                                                             |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`           | `/opt/dsh-podman/guest-agent` | Container-internal directory where the guest-agent image is mounted read-only; see [Variable details](#variable-details)                                                                                           |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG` | `false`                       | When truthy, the guest-agent image reference uses the orchestrator's git version as its tag (replacing the tag in `DSH_PODMAN_GUEST_AGENT_IMAGE`, or adding one when absent); a digest reference panics at startup |
+| `DSH_PODMAN_HOST_APK_CACHE`                    | —                             | Host-absolute directory mounted at `/etc/apk/cache` to persist downloaded packages across apk builds; unset disables caching                                                                                       |
+| `DSH_PODMAN_HOST_APT_CACHE`                    | —                             | Host-absolute directory mounted at `/var/cache/apt/archives` to persist downloaded packages across apt builds; unset disables caching                                                                              |
+| `DSH_PODMAN_HOST_GUEST_AGENT_BIN`              | —                             | Host-side guest agent binary path; bind-mounted when set; see [Variable details](#variable-details)                                                                                                                |
+| `DSH_PODMAN_HOST_PACMAN_CACHE`                 | —                             | Host-absolute directory mounted at `/var/cache/pacman/pkg` to persist downloaded packages across pacman builds; unset disables caching                                                                             |
+| `DSH_PODMAN_HOST_PROJECTS_ROOT`                | `DSH_PODMAN_PROJECTS_ROOT`    | Host-side projects root used as the source of bind mounts                                                                                                                                                          |
+| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | `DSH_PODMAN_SOCKETS_ROOT`     | Host-side sockets root for guest socket bind mounts                                                                                                                                                                |
+| `DSH_PODMAN_IMAGE_PREFIX`                      | `localhost/dsh-podman/`       | Prefix prepended to built workspace image references                                                                                                                                                               |
+| `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET`        | required                      | Podman API socket, e.g. `unix:///run/podman/podman.sock`                                                                                                                                                           |
+| `DSH_PODMAN_ORCHESTRATOR_STATE`                | `/var/lib/dsh-orchestrator`   | Persisted state directory                                                                                                                                                                                          |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN`                | —                             | Shared secret authenticating control-plane gRPC calls; see [Variable details](#variable-details)                                                                                                                   |
+| `DSH_PODMAN_PROJECTS_ROOT`                     | `/projects`                   | Project root inside every guest container                                                                                                                                                                          |
+| `DSH_PODMAN_SECRET_PREFIX`                     | `dsh-podman-`                 | Prefix applied to managed podman secrets (see [Usage](usage.md#secrets))                                                                                                                                           |
+| `DSH_PODMAN_SOCKETS_ROOT`                      | `/run/dsh-podman`             | Socket root directory (bind-mounted from the host); holds `orchestrator.sock` and per-workspace guest sockets; see [Variable details](#variable-details)                                                           |
+| `DSH_PODMAN_VOLUME_PREFIX`                     | `dsh-podman-`                 | Prefix applied to managed named volumes (see [Usage](usage.md#mounts-and-volumes))                                                                                                                                 |
+
+## Guest agent (`dsh-podman-guest-agent`)
+
+| Variable                   | Default     | Description                                                                                 |
+| -------------------------- | ----------- | ------------------------------------------------------------------------------------------- |
+| `DSH_PODMAN_GUEST_SOCKET`  | required    | Unix socket the guest agent serves on; the orchestrator sets it when starting the container |
+| `DSH_PODMAN_GUEST_TOKEN`   | —           | Bearer token required on every gRPC call; see [Variable details](#variable-details)         |
+| `DSH_PODMAN_PROJECTS_ROOT` | `/projects` | Root where the workspace's project(s) are mounted                                           |
+
+## Variable details
+
+### `DSH_PODMAN_BASE_IMAGE_PREFIX`
+
+Prefix under which base images are tagged, as
+`BASE_IMAGE_PREFIX + <short> +
+":latest"`. When the prefix starts with
+`localhost/`, base images are **built locally** by the orchestrator from their
+upstream primitive reference; any other prefix marks them as **public**, in
+which case the orchestrator **pulls** the tagged base images from that registry
+instead of building them. The built-in base images are `archlinux` (pacman),
+`ubuntu` (apt), and `alpine` (apk); their short names are reserved and cannot be
+built over, rebuilt, or removed as custom images.
+
+### `DSH_PODMAN_GUEST_AGENT_IMAGE` and `DSH_PODMAN_HOST_GUEST_AGENT_BIN`
+
+When `DSH_PODMAN_GUEST_AGENT_IMAGE` is set, the orchestrator mounts that image
+read-only into every guest container at `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`
+(default `/opt/dsh-podman/guest-agent`) and runs the guest agent binary from
+`<mount>/<agent_bin>` — that path is the container command (see the next section
+for the binary path and mount location).
+
+`DSH_PODMAN_HOST_GUEST_AGENT_BIN` is the path _on the host_ of a guest agent
+binary. Setting it bind-mounts that binary read-only to the same in-container
+path instead of mounting the guest-agent image; it is an optional development
+fallback and takes precedence over the image mount. It is unset by default.
+
+If neither variable is configured, the guest container has no guest agent to
+run, and creating a workspace container fails.
+
+### `DSH_PODMAN_GUEST_AGENT_IMAGE`, `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`, `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT` and `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG`
+
+The guest-agent image provides the agent at container creation: the orchestrator
+mounts it **read-only** into every guest container at
+`DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT` (default `/opt/dsh-podman/guest-agent`)
+using podman's image-mount mechanism, and the container command is
+`<mount>/<agent_bin>`. Podman image volumes are always mounted read-only.
+
+The mount is **hidden** — the orchestrator injects it itself, so it is not
+listed among the user mounts. Because the agent is provided at runtime,
+rebuilding base images is no longer needed when the guest-agent version changes.
+
+`DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN` is the path of the binary inside the
+guest-agent image (default `/bin/dsh-podman-guest-agent`).
+
+With `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG` set to a truthy value, the
+orchestrator uses its own git version as the image tag instead of the one in
+`DSH_PODMAN_GUEST_AGENT_IMAGE` (which may omit the tag entirely). Because a
+digest reference cannot be overridden, the orchestrator fails to start when that
+variable is set alongside a digest-style `DSH_PODMAN_GUEST_AGENT_IMAGE`.
+
+### `DSH_PODMAN_GUEST_TOKEN`
+
+Shared secret required on every guest-agent gRPC call, carried as the gRPC
+metadata header `authorization: bearer <token>`. In practice the orchestrator
+generates a fresh random token for each workspace and injects it into the guest
+container (via `DSH_PODMAN_GUEST_TOKEN`), handing the same value to the plugin
+together with the guest socket path — so it normally needs no manual
+configuration.
+
+### `DSH_PODMAN_ORCHESTRATOR_TOKEN`
+
+An arbitrary shared secret string that the orchestrator and the plugin must
+agree on; every control-plane request carries it as the gRPC metadata header
+`authorization: bearer <token>`. Use a long, random value — for example
+`openssl rand -hex 32` — and set the same value on both sides. When the
+orchestrator has no token set, it accepts unauthenticated control-plane calls
+(relying on the socket's file permissions instead); when a token is set,
+requests without the matching header are rejected with `Unauthenticated`.
+
+### `DSH_PODMAN_SOCKETS_ROOT` and `DSH_PODMAN_HOST_SOCKETS_ROOT`
+
+`DSH_PODMAN_SOCKETS_ROOT` is the socket root directory shared by the
+orchestrator and the guest containers. It holds the orchestrator control socket
+(`orchestrator.sock`) and one subdirectory per workspace, where each guest agent
+creates its `guest.sock`.
+
+The directory needs to be bind-mounted in the orchestrator container. Its mode
+must be `0700`: the orchestrator refuses to start when the socket root is group-
+or world-accessible, since the control plane is a full-privilege interface onto
+the Podman API and the socket's own mode only helps while the directory above it
+stays private.
+
+Each guest container gets exactly one socket directory bind-mounted into it: the
+host directory `<DSH_PODMAN_HOST_SOCKETS_ROOT>/<container>` is mounted at
+`<DSH_PODMAN_SOCKETS_ROOT>/<container>` inside the container. Because only that
+single per-workspace directory is mounted, a guest container never sees the
+orchestrator's `orchestrator.sock` nor any other workspace's socket directory.
+Both the control socket and each guest socket are created with mode `0600`, and
+both processes set a `0077` umask at startup so the socket is never briefly
+reachable between `bind` and `chmod`.

package/docs/configuration.zh.md

@@ -0,0 +1,147 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 配置
+
+环境变量使用 `DSH_PODMAN_`
+前缀，并按读取它们的组件分组列出（被多个组件读取的变量会出现在每个组件的对应章节中）。插件还在
+dsh 的 **设置 → 插件** 卡片中暴露了一些 **UI 设置**，与环境变量分开列出。
+
+插件按以下顺序读取其配置：先是 cordis 中的插件
+`config`，然后是下方列出的环境变量，最后是内置默认值。
+
+## 插件（dsh 客户端）— 环境变量
+
+| 变量                            | 默认值                  | 说明                                                                      |
+| ------------------------------- | ----------------------- | ------------------------------------------------------------------------- |
+| `DSH_PODMAN_IMAGE_PREFIX`       | `localhost/dsh-podman/` | 前置到工作区镜像引用上的前缀                                              |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN` | —                       | 用于认证控制平面 gRPC 调用的共享机密；见[变量详解](#变量详解)             |
+| `DSH_PODMAN_PROJECTS_ROOT`      | `/projects`             | 用于将会话工作目录解析为工作区的项目根目录                                |
+| `DSH_PODMAN_SOCKETS_ROOT`       | `/run/dsh-podman`       | 插件据此推导 orchestrator 控制套接字（`orchestrator.sock`）的套接字根目录 |
+
+`projectsRoot` 和 `imagePrefix` 仅来自环境变量，以确保与 orchestrator
+一致；`controlToken` 来自插件 `config` 或 `DSH_PODMAN_ORCHESTRATOR_TOKEN`。
+
+## 插件（dsh 客户端）— UI 设置
+
+可在卡片中的 **设置 → 插件 → Podman** 面板内编辑（配置部分和镜像的 Set-default
+弹窗）：
+
+| 设置           | 默认值                    | 说明                                                                              |
+| -------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| `defaultImage` | `archlinux`               | 用于新工作区的镜像**短名称**；可通过 Set-default 弹窗从基础镜像和自定义镜像中选择 |
+| `socketsRoot`  | `DSH_PODMAN_SOCKETS_ROOT` | 插件用于连接 orchestrator 的套接字根目录；回退到环境变量                          |
+
+| 变量                                           | 默认值                        | 说明                                                                                                                                                                |
+| ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DSH_PODMAN_BASE_IMAGE_PREFIX`                 | `localhost/dsh-podman/base/`  | 基础镜像的标签前缀；以 `localhost/` 开头的前缀会在本地构建它们，否则从公共镜像仓库拉取                                                                              |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE`                 | —                             | 以只读方式挂载到每个 guest 容器中的 guest-agent 镜像；未设置时禁用该功能；见[变量详解](#变量详解)                                                                   |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`       | `/bin/dsh-podman-guest-agent` | guest-agent 镜像中 guest agent 二进制的路径；容器命令为 `<mount>/<agent_bin>`；见[变量详解](#变量详解)                                                              |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`           | `/opt/dsh-podman/guest-agent` | guest-agent 镜像以只读方式挂载到的容器内部目录；见[变量详解](#变量详解)                                                                                             |
+| `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG` | `false`                       | 为真值时，guest-agent 镜像引用使用 orchestrator 的 git 版本作为其标签（替换 `DSH_PODMAN_GUEST_AGENT_IMAGE` 中的标签，或在缺失时添加一个）；摘要引用会在启动时 panic |
+| `DSH_PODMAN_HOST_APK_CACHE`                    | —                             | 挂载在 `/etc/apk/cache` 的主机绝对路径目录，用于在 apk 构建之间持久化已下载的软件包；未设置时禁用缓存                                                               |
+| `DSH_PODMAN_HOST_APT_CACHE`                    | —                             | 挂载在 `/var/cache/apt/archives` 的主机绝对路径目录，用于在 apt 构建之间持久化已下载的软件包；未设置时禁用缓存                                                      |
+| `DSH_PODMAN_HOST_GUEST_AGENT_BIN`              | —                             | 主机侧的 guest agent 二进制路径；设置后会绑定挂载；见[变量详解](#变量详解)                                                                                          |
+| `DSH_PODMAN_HOST_PACMAN_CACHE`                 | —                             | 挂载在 `/var/cache/pacman/pkg` 的主机绝对路径目录，用于在 pacman 构建之间持久化已下载的软件包；未设置时禁用缓存                                                     |
+| `DSH_PODMAN_HOST_PROJECTS_ROOT`                | `DSH_PODMAN_PROJECTS_ROOT`    | 用作绑定挂载源的主机侧项目根目录                                                                                                                                    |
+| `DSH_PODMAN_HOST_SOCKETS_ROOT`                 | `DSH_PODMAN_SOCKETS_ROOT`     | 用于 guest 套接字绑定挂载的主机侧套接字根目录                                                                                                                       |
+| `DSH_PODMAN_IMAGE_PREFIX`                      | `localhost/dsh-podman/`       | 前置到已构建的工作区镜像引用上的前缀                                                                                                                                |
+| `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET`        | required                      | Podman API 套接字，例如 `unix:///run/podman/podman.sock`                                                                                                            |
+| `DSH_PODMAN_ORCHESTRATOR_STATE`                | `/var/lib/dsh-orchestrator`   | 持久化状态目录                                                                                                                                                      |
+| `DSH_PODMAN_ORCHESTRATOR_TOKEN`                | —                             | 用于认证控制平面 gRPC 调用的共享机密；见[变量详解](#变量详解)                                                                                                       |
+| `DSH_PODMAN_PROJECTS_ROOT`                     | `/projects`                   | 每个 guest 容器内的项目根目录                                                                                                                                       |
+| `DSH_PODMAN_SECRET_PREFIX`                     | `dsh-podman-`                 | 应用于受管 podman 机密的前缀（见[使用](usage.zh.md#机密)）                                                                                                          |
+| `DSH_PODMAN_SOCKETS_ROOT`                      | `/run/dsh-podman`             | 套接字根目录（从主机绑定挂载）；包含 `orchestrator.sock` 和每个工作区的 guest 套接字；见[变量详解](#变量详解)                                                       |
+| `DSH_PODMAN_VOLUME_PREFIX`                     | `dsh-podman-`                 | 应用于受管命名卷的前缀（见[使用](usage.zh.md#挂载与卷)）                                                                                                            |
+
+## Guest agent（`dsh-podman-guest-agent`）
+
+| 变量                       | 默认值      | 说明                                                                |
+| -------------------------- | ----------- | ------------------------------------------------------------------- |
+| `DSH_PODMAN_GUEST_SOCKET`  | required    | guest agent 提供服务的 Unix 套接字；orchestrator 在启动容器时设置它 |
+| `DSH_PODMAN_GUEST_TOKEN`   | —           | 每次 gRPC 调用所需的 Bearer 令牌；见[变量详解](#变量详解)           |
+| `DSH_PODMAN_PROJECTS_ROOT` | `/projects` | 工作区的项目被挂载到的根目录                                        |
+
+## 变量详解
+
+### `DSH_PODMAN_BASE_IMAGE_PREFIX`
+
+基础镜像的标签前缀，格式为 `BASE_IMAGE_PREFIX + <short> + ":latest"`。当前缀以
+`localhost/` 开头时，orchestrator
+会从其上游原始引用**本地构建**基础镜像；任何其他前缀则将其标记为**公共**镜像，此时
+orchestrator
+会从该镜像仓库**拉取**带标签的基础镜像，而不是构建它们。内置基础镜像为
+`archlinux`（pacman）、`ubuntu`（apt）和
+`alpine`（apk）；它们的短名称是保留的，不能作为自定义镜像覆盖、重建或删除。
+
+### `DSH_PODMAN_GUEST_AGENT_IMAGE` and `DSH_PODMAN_HOST_GUEST_AGENT_BIN`
+
+当设置了 `DSH_PODMAN_GUEST_AGENT_IMAGE` 时，orchestrator
+会将该镜像以只读方式挂载到每个 guest 容器的
+`DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`（默认 `/opt/dsh-podman/guest-agent`），并从
+`<mount>/<agent_bin>` 运行 guest agent
+二进制——该路径就是容器命令（二进制路径和挂载位置见下一节）。
+
+`DSH_PODMAN_HOST_GUEST_AGENT_BIN` 是 guest agent
+二进制在_主机上_的路径。设置它会将该二进制以只读方式绑定挂载到容器内相同路径，而不是挂载
+guest-agent 镜像；这是一个可选的开发回退方案，优先于镜像挂载。默认情况下未设置。
+
+如果两个变量都未配置，guest 容器将没有可运行的 guest
+agent，创建工作区容器将会失败。
+
+### `DSH_PODMAN_GUEST_AGENT_IMAGE`, `DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN`, `DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT` and `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG`
+
+guest-agent 镜像在容器创建时提供 agent：orchestrator 使用 podman
+的镜像挂载机制，将其**只读**挂载到每个 guest 容器的
+`DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`（默认
+`/opt/dsh-podman/guest-agent`），容器命令为 `<mount>/<agent_bin>`。Podman
+镜像卷始终以只读方式挂载。
+
+该挂载是**隐藏的**——由 orchestrator 自行注入，因此不会列在用户挂载中。由于 agent
+是在运行时提供的，guest-agent 版本变化时不再需要重建基础镜像。
+
+`DSH_PODMAN_GUEST_AGENT_IMAGE_AGENT_BIN` 是 guest-agent 镜像内二进制的路径（默认
+`/bin/dsh-podman-guest-agent`）。
+
+当 `DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG` 设置为真值时，orchestrator
+使用自己的 git 版本作为镜像标签，而不是 `DSH_PODMAN_GUEST_AGENT_IMAGE`
+中的标签（该标签可以完全省略）。由于摘要引用无法被覆盖，当该变量与摘要式的
+`DSH_PODMAN_GUEST_AGENT_IMAGE` 一起设置时，orchestrator 将无法启动。
+
+### `DSH_PODMAN_GUEST_TOKEN`
+
+每次 guest-agent gRPC 调用所需的共享机密，以 gRPC 元数据头
+`authorization: bearer <token>` 传递。实际上，orchestrator
+会为每个工作区生成一个新的随机令牌，并通过 `DSH_PODMAN_GUEST_TOKEN` 注入到 guest
+容器中，同时将相同的值连同 guest 套接字路径一起交给插件——因此通常无需手动配置。
+
+### `DSH_PODMAN_ORCHESTRATOR_TOKEN`
+
+orchestrator 和插件必须约定的任意共享机密字符串；每个控制平面请求都以 gRPC
+元数据头 `authorization: bearer <token>` 携带它。请使用一个长且随机的值——例如
+`openssl rand -hex 32`——并在两端设置相同的值。当 orchestrator
+未设置令牌时，它接受未经认证的控制平面调用（转而依赖套接字的文件权限）；当设置了令牌时，不带匹配头的请求会被以
+`Unauthenticated` 拒绝。
+
+### `DSH_PODMAN_SOCKETS_ROOT` and `DSH_PODMAN_HOST_SOCKETS_ROOT`
+
+`DSH_PODMAN_SOCKETS_ROOT` 是 orchestrator 与 guest
+容器共享的套接字根目录。它包含 orchestrator
+控制套接字（`orchestrator.sock`）和每个工作区的一个子目录，每个 guest agent
+在其中创建自己的 `guest.sock`。
+
+该目录需要绑定挂载到 orchestrator 容器中。其权限模式必须是
+`0700`：当套接字根目录对组或其他用户可访问时，orchestrator
+拒绝启动，因为控制平面是通往 Podman API
+的全权限接口，且只有在其上层目录保持私有时，套接字自身的权限模式才有作用。
+
+每个 guest 容器恰好绑定挂载一个套接字目录：主机目录
+`<DSH_PODMAN_HOST_SOCKETS_ROOT>/<container>` 被挂载到容器内的
+`<DSH_PODMAN_SOCKETS_ROOT>/<container>`。由于只挂载了这一个按工作区划分的目录，guest
+容器永远看不到 orchestrator 的
+`orchestrator.sock`，也看不到任何其他工作区的套接字目录。控制套接字和每个 guest
+套接字都以权限模式 `0600` 创建，两个进程都会在启动时设置 `0077`
+umask，这样套接字在 `bind` 和 `chmod` 之间永远不会被短暂访问。