@loicngr/kobo 2.1.19 → 2.1.21

package/AGENTS.md

@@ -282,6 +282,21 @@ Traefik network. It persists `/root`, mounts project paths identically on host a
 container, and leaves the Docker socket opt-in. `docs/deployment-vps.md` owns the
 operator walkthrough; `CONFIGURATION.md` compares all Compose topologies.
 
+The VPS launcher `scripts/kobo-vps-entrypoint` bootstraps the dedicated home and
+executes Kōbō as positive `KOBO_UID:KOBO_GID`, adding the socket's numeric group
+when mounted. Keep `HOME=/root` and the existing volume for compatibility. Do not
+chown existing project mounts, follow home symlinks, or resolve root bootstrap
+commands through user-writable skill/tool paths. `--exec` runs operator commands
+as the agent without rescanning ownership. Legacy root Compose entrypoints are
+preserved by the updater and need the documented explicit migration. New installer
+identity fields must not silently reconfigure old completed manifests.
+
+The updater needs the launcher beside its script to build its compatibility layer
+(including netcat/Buildx). `docs/vps-projects-and-skills.md` covers dependency/env
+setup, private registry auth, SSH dev-server access, scoped cleanup, native
+Claude/Codex skills and persistence. Project-specific OS packages and host inotify
+changes are operator-managed; the updater does not preserve arbitrary image layers.
+
 `scripts/kobo-install` guides a fresh installation; it does not adopt existing
 unmanaged stacks. Preserve its read-only `--check`, explicit Docker-socket opt-in,
 managed-file fingerprints, shared updater lock, and durable start phases. Completed

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.21
+
+- feat(vps): introduce non-root runtime launcher and UID/GID support
+
+## 2.1.20
+
+- fix(progress): clarify activity updates and completion
+
 ## 2.1.19
 
 - feat(progress): add session activity bars and improve launch prompts

package/CONFIGURATION.md

@@ -885,10 +885,23 @@ the previous process are interrupted; external reporters may still be running
 elsewhere, so their last state is preserved. A new internal launch uses a new
 reporting identity.
 
-Workspace launch instructions require agents to use these tools for long tasks
-and pass the requirement to subagents. When a restricted subagent cannot access
-the tools, its parent reports the activity on its behalf. Reporting permissions
-do not grant permission to edit project files or complete tasks during a review.
+Workspace launch instructions require the full reporting lifecycle: create a
+bar, keep its returned ID and sequence, update that same bar at actual phase
+changes and meaningful completed milestones, and finish it before the final
+report once the outcome is known. Even without a measurable percentage, agents
+must update the current step; omitting both numeric values preserves
+indeterminate progress. No percentage is inferred from tool calls, elapsed time
+or model activity. Unchanged updates, polling and timer-driven reporting loops
+are not requested.
+
+Parents pass this lifecycle to subagents, which report and finish their own
+activities before returning. When a restricted subagent cannot access the tools,
+its parent reports observed milestones and the outcome on its behalf, without
+duplicate bars. Yielding while background work continues does not mean success.
+Reporting permissions do not grant permission to edit project files or complete
+tasks during a review. These instructions guide the model; they cannot guarantee
+that it reports every milestone. Updated guidance applies on the next launch or
+resume, not retroactively to an already running agent.
 
 The service retains at most 1,000 indicators per session, with at most 32 running
 at once. Hidden records are retained so retries cannot recreate dismissed bars.
@@ -1170,17 +1183,20 @@ Traefik already exists. Build the image from a source checkout before starting.
 All four use the same underlying image (`docker build -t kobo:local .` from the
 repo root). The original three mount provider/Git configuration from the host;
 the VPS example keeps independent credentials in a persistent container home.
-The VPS example overrides the entrypoint to start Node directly; the original
+The VPS example uses `kobo-vps-entrypoint`: it prepares the dedicated home volume
+then drops to `KOBO_UID:KOBO_GID` before starting Node, without `sshd`. The original
 files use the image entrypoint, which starts `sshd` even when port 22 is not published.
+See the [VPS runtime user and migration procedure](./docs/deployment-vps.md#runtime-user-and-existing-installations)
+and [project/skills operations guide](./docs/vps-projects-and-skills.md).
 
 ### The image
 
 Multi-stage `Dockerfile`, `node:24.19.0-slim` base:
 
 - **Build stage**: installs root, client, and PWA deps, then runs `npm run build` (client via Quasar, server via `tsc`).
-- **Runtime stage**: production deps only, plus OS tooling the agents and forge CLIs need — `git`, `openssh-client` + `openssh-server`, `ripgrep`, `fd-find`, `jq`, `curl`, Python + build tools, the Docker CLI and Compose plugin (`docker compose`, talks to a mounted host socket, see [Volumes](#volumes)), `gh`, `glab`, `tmux`, `vim`/`nano`, and more for interactive shell use.
+- **Runtime stage**: production deps only, plus OS tooling the agents and forge CLIs need — `git`, `openssh-client` + `openssh-server`, `ripgrep`, `fd-find`, `jq`, `curl`, Python + build tools, the Docker CLI, Compose and Buildx plugins (talk to a mounted host socket, see [Volumes](#volumes)), netcat (`nc`), `gh`, `glab`, `tmux`, `vim`/`nano`, and more for interactive shell use.
 - **Global CLIs**: `@anthropic-ai/claude-code` and `@openai/codex` are installed globally for interactive login (`claude /login`, `codex login` over SSH) — separate from Kōbō's own bundled SDK/subprocess usage, which needs no global install.
-- **`git config --system --add safe.directory '*'`**: the container runs as root, but bind-mounted project repos keep the *host* user's UID on disk. Git's ownership check (CVE-2022-24765 mitigation) refuses to touch a repo it doesn't "own" unless told otherwise. This line pre-trusts every mounted path — fine for a single-user dev container, not something you'd do on a multi-tenant host.
+- **`git config --system --add safe.directory '*'`**: legacy Compose examples run as root while mounted repos retain the host UID; the VPS example instead uses a matching non-root UID. The image still pre-trusts mounted Git repositories. This broad trust is for a single-user environment, not a multi-tenant host.
 - **`HEALTHCHECK`**: `curl -f http://localhost:$SERVER_PORT/api/health` every 30s. `/api/health` is exempt from the network-access token gate unconditionally (even with `networkAccessBehindProxy` on) — Docker's `HEALTHCHECK` process has no way to supply the runtime-generated token, and without the exemption a "behind a reverse proxy" container never reports healthy, which makes Traefik's Docker provider filter it out of its router table entirely (Traefik drops unhealthy/starting containers from routing).
 - **`EXPOSE 3000`**, `ENV SERVER_PORT=3000`, entrypoint `docker-entrypoint.sh` → `npm start`.
 
@@ -1188,6 +1204,15 @@ Build once: `docker build -t kobo:local .`
 
 ### Environment variables (Docker)
 
+The VPS template accepts `KOBO_UID` and `KOBO_GID` (positive numeric IDs, default
+1000); the installer defaults to the invoking host user's IDs. It retains
+`HOME=/root` for volume compatibility and adds the mounted Docker socket's group
+when applicable. Use `docker compose exec kobo kobo-vps-entrypoint --exec <command>`
+for logins, skills and project tooling as that user. It also sets
+`NODE_ENV=development` and `NPM_CONFIG_INCLUDE=dev` for project subprocesses;
+Kōbō continues serving its prebuilt UI/server. The base image retains its
+production default for other deployment layouts.
+
 Beyond the [general environment variables](#environment-variables), these matter specifically for a container deployment:
 
 | Variable | Where it's set | Purpose |
@@ -1469,6 +1494,10 @@ rules survive restarts and can be removed from the workspace's permission UI.
 
 Each workspace can run its own dev server. The **Tools** panel shows its status, a clickable URL, the live container count, and a logs button. That works only when your project follows a small contract. This section documents the contract so the panel lights up for *your* project, not just Docker-instance projects.
 
+For remote installations, `localhost` in that link is the browser's computer.
+See [VPS dev-server access](./docs/vps-projects-and-skills.md#reach-a-development-server-from-your-pc)
+for SSH forwarding, separate proxy routes and scoped stop/cleanup commands.
+
 ### What the panel actually does
 
 Kōbō treats the dev server in two independent layers:

package/dist/server/services/agent/orchestrator.js

@@ -496,6 +496,7 @@ function readEffectiveSettingsSafe(projectPath) {
 function buildMcpServers(workspaceId, extraEnv, memoryCapability) {
     const mcpServerCompiled = getCompiledMcpServerPath();
     const mcpServerSource = getMcpServerSourcePath();
+    const global = getGlobalSettings();
     return [
         {
             name: 'kobo-tasks',
@@ -508,6 +509,11 @@ function buildMcpServers(workspaceId, extraEnv, memoryCapability) {
                 KOBO_DB_PATH: getDbPath(),
                 KOBO_SETTINGS_PATH: getSettingsPath(),
                 KOBO_BACKEND_URL: `http://127.0.0.1:${backendPort}`,
+                // Behind a proxy, even internal loopback requests require network auth.
+                // Per-launch memory/progress capabilities remain independently required.
+                ...(global.networkAccessBehindProxy && global.networkAccessToken
+                    ? { KOBO_NETWORK_TOKEN: global.networkAccessToken }
+                    : {}),
             },
         },
     ];

package/dist/shared/progress-bar-prompts.js

@@ -2,6 +2,10 @@ export const PROGRESS_BAR_PLAN_EXCEPTION = 'Operational exception in Plan/read-o
 /** Shared across engines, fresh/resumed launches and delegated agents. */
 export const PROGRESS_BAR_PROMPT = `<kobo-progress-reporting>
 ${PROGRESS_BAR_PLAN_EXCEPTION}
-Use Kōbō's create_progress_bar, update_progress_bar and finish_progress_bar for long-running tasks, including tests and delegated work. Give each activity a clear label and stable activity_key; follow tool schemas for ordered updates and retries. Report meaningful steps and measured current/total only when known; otherwise keep progress indeterminate. Never invent percentages or poll these tools. Finish with succeeded or failed only when known. A dismissed bar stays hidden: continue without recreating it; dismissal is not cancellation. Reporting never substitutes for verification, and an interrupted reporter does not prove background work stopped.
-Pass this requirement to all subagents when delegating. Subagents must not schedule or replace workspace wakeups; the parent coordinates follow-up. Each subagent reports its own long task through the inherited Kōbō MCP tools; the parent must not duplicate that activity. If a custom subagent lacks these tools, the parent reports its observed progress accurately instead. After resume, start new activity keys for new work; do not reopen a finished activity.
+For each long-running activity (tests, audits, builds or delegated work), follow this reporting lifecycle:
+1. Call create_progress_bar with a clear label, current step and stable activity_key. Save its returned id and sequence; creating a bar is only the start of reporting.
+2. Call update_progress_bar with that id and an increasing sequence: update the same bar at each actual phase change or meaningful completed milestone, including during a long phase. Even without a measured percentage, report the current step; omit both current and total for step-only updates. Use measured numbers only when known. Never invent percentages, poll, send unchanged updates or start timer-driven reporting loops; follow tool retry guidance.
+3. Call finish_progress_bar on that id before your final report (or return to the parent) when the activity's succeeded/failed outcome is known. Do not declare ongoing background work finished merely because you are yielding control.
+Pass this requirement to all subagents when delegating: each reports and finishes its own long activity through inherited Kōbō MCP tools; the parent must not duplicate it. If a custom subagent lacks these tools, the parent reports its observed milestones and outcome instead. Subagents must not schedule or replace workspace wakeups; the parent coordinates follow-up.
+A dismissed bar stays hidden: continue without recreating it; dismissal is not cancellation. Reporting never substitutes for verification, and an interrupted reporter does not prove background work stopped. After resume, use new activity keys for new work; do not reopen finished activities.
 </kobo-progress-reporting>`;

package/dist/shared/progress-bar-tools.js

@@ -22,15 +22,15 @@ function tools(external) {
         annotations: { readOnlyHint: readOnly, destructiveHint: false, openWorldHint: false },
     });
     return [
-        definition('create_progress_bar', 'Report a labelled long-running activity in this session. Use a new activity_key per activity; identical retries return its current state, including dismissal. Report measured current/total together, or omit both for indeterminate progress. Closing a bar never cancels work.', {
+        definition('create_progress_bar', 'Start reporting a labelled long-running activity. Save the returned id and sequence, update that same bar at actual phase changes and meaningful completed milestones, and finish it before the final report when the outcome is known. Use a new activity_key per activity; identical retries return its current state, including dismissal. Supply measured current/total together or omit both for indeterminate progress. Closing a bar never cancels work.', {
             activity_key: { type: 'string', minLength: 1, maxLength: 100 },
             label: { type: 'string', minLength: 1, maxLength: 200 },
             step,
             current: numberOrNull,
             total: numberOrNull,
         }, ['activity_key', 'label']),
-        definition('update_progress_bar', 'Update absolute measured progress and/or step. Both numbers must be provided together, or both null. At most one accepted running update per second; respect retry guidance. Dismissed bars remain hidden. Never invent a percentage.', { progress_id: id, sequence, step, current: numberOrNull, total: numberOrNull }, ['progress_id', 'sequence']),
-        definition('finish_progress_bar', 'Finish reporting with succeeded or failed. Terminal state is immutable except an exact retry. Success hides after five seconds; failure remains until the user closes it. Reporting does not mark workspace tasks done.', { progress_id: id, sequence, step, outcome: { type: 'string', enum: ['succeeded', 'failed'] } }, ['progress_id', 'sequence', 'outcome']),
+        definition('update_progress_bar', 'Update the existing bar at actual phase changes or meaningful completed milestones, even when no percentage is known. Omit both numbers for step-only updates (previous numeric values are preserved); provide both measured numbers together, or both null to switch to indeterminate. Use the returned id as progress_id and increase sequence. Never invent percentages or send unchanged updates. At most one accepted running update per second; respect retry guidance without polling. Dismissed bars remain hidden.', { progress_id: id, sequence, step, current: numberOrNull, total: numberOrNull }, ['progress_id', 'sequence']),
+        definition('finish_progress_bar', 'Finish the same bar with succeeded or failed before your final report or return to the parent, only once the activity outcome is known. Do not finish ongoing background work merely because you yield control. Increase sequence; terminal state is immutable except an exact retry. Success hides after five seconds; failure remains until the user closes it. Reporting does not mark workspace tasks done.', { progress_id: id, sequence, step, outcome: { type: 'string', enum: ['succeeded', 'failed'] } }, ['progress_id', 'sequence', 'outcome']),
         definition('list_progress_bars', 'Read progress bars in the explicitly selected session, including dismissed/terminal bars. Responses contain bounded pages and serverTime; do not poll without a concrete need.', {
             limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
             offset: { type: 'integer', minimum: 0, default: 0 },

package/docker-compose.vps.yml

@@ -10,10 +10,16 @@ services:
     init: true
     restart: unless-stopped
     # Use the host's SSH and `docker compose exec`; no container SSH daemon.
-    entrypoint: ["node"]
-    command: ["dist/server/index.js"]
+    # Bootstrap permissions as root, then execute Kōbō/agents as this host UID/GID.
+    entrypoint: ["kobo-vps-entrypoint"]
+    command: ["node", "dist/server/index.js"]
     environment:
-      NODE_ENV: production
+      KOBO_UID: ${KOBO_UID:-1000}
+      KOBO_GID: ${KOBO_GID:-1000}
+      HOME: /root
+      # Kōbō serves its built assets; project commands need development dependencies.
+      NODE_ENV: development
+      NPM_CONFIG_INCLUDE: dev
       SERVER_PORT: "3000"
       KOBO_HOME: /root/.config/kobo
       KOBO_NETWORK_ACCESS_ENABLED: "true"

package/docs/deployment-vps.md

@@ -132,11 +132,34 @@ docker build -t kobo:local source
 
 Save [`docker-compose.vps.yml`](../docker-compose.vps.yml) as `/opt/kobo/compose.yaml`
 and [`scripts/kobo-update`](../scripts/kobo-update) as `/opt/kobo/kobo-update`.
+Also copy [`scripts/kobo-vps-entrypoint`](../scripts/kobo-vps-entrypoint) beside the updater as `/opt/kobo/kobo-vps-entrypoint`; the updater includes it in its compatibility image layer.
+
 These files may be newer than the example release above: obtain them from the
 checkout containing this guide, not an older tag that predates them.
 
 ```bash
-chmod 755 /opt/kobo/kobo-update
+chmod 755 /opt/kobo/kobo-update /opt/kobo/kobo-vps-entrypoint
+```
+
+For an older release image without the launcher, build this small compatibility
+layer before starting the current Compose template. Its build context contains
+only the launcher, never the deployment `.env`, projects or credentials:
+
+```bash
+mkdir -p runtime
+cp kobo-vps-entrypoint runtime/
+docker tag kobo:local kobo:release-base
+cat > runtime/Dockerfile <<'DOCKERFILE'
+FROM kobo:release-base
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    util-linux netcat-openbsd docker-compose-plugin docker-buildx-plugin \
+    && rm -rf /var/lib/apt/lists/*
+COPY --chmod=755 kobo-vps-entrypoint /usr/local/bin/kobo-vps-entrypoint
+RUN chmod a+r /app/package.json /app/package-lock.json /app/CHANGELOG.md \
+    && chmod -R a+rX /app/dist /app/src/client/dist
+DOCKERFILE
+docker build -t kobo:local runtime
 ```
 
 Create `/opt/kobo/.env` with your deployment values:
@@ -147,8 +170,12 @@ KOBO_PROJECTS_DIR=/opt/kobo/projects
 TRAEFIK_NETWORK=web
 TRAEFIK_ENTRYPOINT=websecure
 TRAEFIK_CERTRESOLVER=letsencrypt
+KOBO_UID=1000
+KOBO_GID=1000
 ```
 
+Replace `KOBO_UID` and `KOBO_GID` with `id -u` and `id -g` from the host user who owns your projects. Both must be nonzero. The guided installer collects them automatically; `--uid` and `--gid` override them.
+
 The network, entrypoint and resolver names must match **your existing Traefik**;
 `web`, `websecure` and `letsencrypt` are examples. If Traefik uses a preloaded
 certificate rather than an ACME resolver, remove the `tls.certresolver` label.
@@ -173,8 +200,7 @@ remembers the token; treat both that URL and startup logs as credentials.
 the public hostname. Both network access and behind-proxy mode are enabled.
 
 This example publishes no HTTP or SSH ports. Use SSH to the VPS followed by
-`docker compose exec kobo bash` for a container shell. The Compose entrypoint
-starts Node directly, so it does not start the image's optional SSH daemon.
+`docker compose exec kobo kobo-vps-entrypoint --exec bash` for a container shell. The VPS launcher prepares the home permissions, then drops root before starting Node. It does not start the image's optional SSH daemon. `--exec` runs administrative shell/CLI commands as the same non-root user without repeating home migration.
 
 Check routing before starting a mission:
 
@@ -188,13 +214,85 @@ without a token. `/api/health` is intentionally public. Ordinary authenticated
 REST requests use `X-Kobo-Token`; the external MCP endpoint also supports Bearer
 authentication. No additional Traefik route is needed for WebSocket upgrades.
 
+Behind-proxy mode also protects loopback requests. Kōbō supplies the current
+network token to its internal workspace MCP process when launching Claude or
+Codex, so memory, progress bars and other backend calls can authenticate without
+manual MCP configuration. Memory and progress calls still require their separate
+per-launch capabilities. After rotating the network token, stop and resume active
+agent sessions so their MCP processes receive the new token.
+
 ## 3. Authenticate and choose a project
 
+### Runtime user and existing installations
+
+The VPS Compose example runs Kōbō and its agents as `KOBO_UID:KOBO_GID`, not
+root. Claude's bypass mode requires a non-root process; select that permission
+mode explicitly in Kōbō. The launcher's brief root bootstrap creates a matching
+user/group and assigns the dedicated home volume to them. Project directories
+are never recursively chowned. They must already be writable by the chosen UID.
+When the Docker socket is mounted, its numeric group is added to the agent's
+supplementary groups. That access still grants control over the host daemon.
+
+`HOME=/root` and `KOBO_HOME=/root/.config/kobo` deliberately remain unchanged:
+the directory name does not mean the process runs as root. Keeping it avoids
+losing existing sessions, logins, plugin paths and updater backups. Do not put
+additional bind mounts below `/root` in this standalone layout.
+
+Verify the effective identity, then use the same launcher for setup commands:
+
+```bash
+docker compose exec kobo kobo-vps-entrypoint --exec id
+docker compose exec kobo kobo-vps-entrypoint --exec bash
+```
+
+A plain `docker compose exec kobo ...` still defaults to the container's root
+bootstrap user. Installing skills or authenticating that way can create files
+the agent cannot update. Use `kobo-vps-entrypoint --exec` throughout this guide;
+reserve `--user 0` for deliberate OS maintenance. Do not add `user:` to the VPS
+Compose file: that would skip the permission bootstrap of an existing root home.
+
+For an **existing root deployment**, schedule an idle maintenance window and
+back up the full home volume plus the Compose file first. Build an image with
+the new launcher (the updated updater's `--prepare` does this), select your host
+UID/GID in `.env`, and update the service settings below (merge the environment
+with existing settings). `.env` alone does not pass variables into a container:
+
+```yaml
+entrypoint: ["kobo-vps-entrypoint"]
+command: ["node", "dist/server/index.js"]
+environment:
+  KOBO_UID: ${KOBO_UID:-1000}
+  KOBO_GID: ${KOBO_GID:-1000}
+  HOME: /root
+  NODE_ENV: development
+  NPM_CONFIG_INCLUDE: dev
+```
+
+Keep the same named home volume and project mount paths. Recreate the idle
+service, verify `id`, authenticated API access and one agent launch. The initial
+ownership scan takes longer for a large home. Read-only App keys/configuration
+must also be readable by the selected UID; changing the home owner cannot repair
+their host permissions.
+
+The updater preserves existing Compose settings: updating an image alone does
+**not** convert a legacy `entrypoint: ["node"]` deployment to non-root. The
+installer does not migrate completed managed stacks or rewrite their recorded
+fingerprints. Retain their manifest as history and manage an intentional Compose
+migration with the updater/manual procedure; do not rerun the installer to adopt
+the altered files. The other Compose examples retain their historical entrypoint.
+
+The current VPS template needs an image containing `kobo-vps-entrypoint`. For a
+fresh manual installation of an older release, build the compatibility layer in
+step 1. For an existing installation, the updated updater's `--prepare` includes
+it. Do not combine the new template with an unmodified old image.
+
+### Engine and Git login
+
 Authenticate **inside the container**, using the engine you intend to run:
 
 ```bash
-docker compose exec kobo claude auth login
-docker compose exec kobo codex login --device-auth
+docker compose exec kobo kobo-vps-entrypoint --exec claude auth login
+docker compose exec kobo kobo-vps-entrypoint --exec codex login --device-auth
 ```
 
 Follow the browser URL/code printed by your installed CLI. Provider availability
@@ -206,10 +304,10 @@ For a personal GitHub account, complete the CLI's browser login flow from your P
 then connect Git HTTPS credentials to it:
 
 ```bash
-docker compose exec kobo gh auth login --hostname github.com --git-protocol https --web
-docker compose exec kobo gh auth setup-git --hostname github.com
-docker compose exec kobo git config --global user.name "Your Name"
-docker compose exec kobo git config --global user.email "you@example.com"
+docker compose exec kobo kobo-vps-entrypoint --exec gh auth login --hostname github.com --git-protocol https --web
+docker compose exec kobo kobo-vps-entrypoint --exec gh auth setup-git --hostname github.com
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.name "Your Name"
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.email "you@example.com"
 ```
 
 Git commit identity and forge authentication are separate settings. For a GitHub
@@ -219,7 +317,7 @@ instead of an interactive account login.
 Clone your repository in the mounted project directory (replace the repository):
 
 ```bash
-docker compose exec kobo git clone https://github.com/YOUR-ORG/YOUR-REPO.git /opt/kobo/projects/my-project
+docker compose exec kobo kobo-vps-entrypoint --exec git clone https://github.com/YOUR-ORG/YOUR-REPO.git /opt/kobo/projects/my-project
 ```
 
 In the first-run form, **Local project directory** means
@@ -233,9 +331,9 @@ not automatically available inside a container. See [Docker volume persistence](
 
 ## Optional project Docker environments
 
-The image includes the Docker CLI and Compose plugin. Verify with
-`docker compose exec kobo docker compose version`; an older release image may
-need the plugin installed in a derived image. The updater below adds it when missing.
+The image includes the Docker CLI, Compose and Buildx plugins, and netcat (`nc`). Verify with
+`docker compose exec kobo kobo-vps-entrypoint --exec docker compose version`; an older release image may
+need these tools installed in a derived image. The updater below includes them in its compatibility layer.
 
 To let agents manage project containers, explicitly enable the commented
 `/var/run/docker.sock` mount in `compose.yaml` and recreate the service when idle.
@@ -253,6 +351,10 @@ An `npm` development process does not require the Docker socket. Development
 server URLs are separate from Kōbō's dashboard URL; configure their own reachable
 ports or proxy routes. See the [dev-server contract](../CONFIGURATION.md#dev-server).
 
+For project dependencies, private registry login, SSH tunnels, stop/cleanup commands,
+file-watcher troubleshooting and installing Claude/Codex extensions, follow
+[Projects, development servers and skills on a VPS](./vps-projects-and-skills.md).
+
 ## GitHub App bot authentication
 
 A GitHub App installation token expires after one hour. Putting one token in
@@ -348,12 +450,12 @@ Recreate the idle service to apply the mounts, then configure Git inside it:
 ```bash
 docker compose config --quiet
 docker compose up -d --wait --wait-timeout 180 kobo
-docker compose exec kobo kobo-github-app-token --check
-docker compose exec kobo git config --global --replace-all credential.https://github.com.helper ''
-docker compose exec kobo git config --global --add credential.https://github.com.helper '!/usr/local/bin/gh auth git-credential'
-docker compose exec kobo bash -lc 'command -v gh'
-docker compose exec kobo gh repo view YOUR-ORG/YOUR-REPO --json nameWithOwner
-docker compose exec kobo git -C /opt/kobo/projects/my-project ls-remote origin HEAD
+docker compose exec kobo kobo-vps-entrypoint --exec kobo-github-app-token --check
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global --replace-all credential.https://github.com.helper ''
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global --add credential.https://github.com.helper '!/usr/local/bin/gh auth git-credential'
+docker compose exec kobo kobo-vps-entrypoint --exec bash -lc 'command -v gh'
+docker compose exec kobo kobo-vps-entrypoint --exec gh repo view YOUR-ORG/YOUR-REPO --json nameWithOwner
+docker compose exec kobo kobo-vps-entrypoint --exec git -C /opt/kobo/projects/my-project ls-remote origin HEAD
 ```
 
 The empty helper entry resets inherited helpers **only for this HTTPS host**.
@@ -373,7 +475,7 @@ renewals with a bounded lock, and invalidates cached tokens when the configurati
 or key changes. Failed renewal never falls back to an expired token. HTTPS calls
 use the fixed GitHub API endpoint and do not follow redirects.
 
-Use `docker compose exec kobo kobo-github-app-token --check` to validate signing,
+Use `docker compose exec kobo kobo-vps-entrypoint --exec kobo-github-app-token --check` to validate signing,
 GitHub authentication and the cache without exposing a token. It prints a JSON
 status and expiration time. On failure, check file permissions, the key and IDs,
 the App installation's repository access, server clock and outbound HTTPS. Do not
@@ -385,8 +487,8 @@ commits. Configure commit identity separately, for example using your App's bot
 login and its actual GitHub bot-user email:
 
 ```bash
-docker compose exec kobo git config --global user.name 'YOUR-APP[bot]'
-docker compose exec kobo git config --global user.email 'BOT-USER-ID+YOUR-APP[bot]@users.noreply.github.com'
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.name 'YOUR-APP[bot]'
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.email 'BOT-USER-ID+YOUR-APP[bot]@users.noreply.github.com'
 ```
 
 `BOT-USER-ID` is the bot account's user ID, not the App ID or installation ID.
@@ -427,9 +529,11 @@ assuming a particular server. It uses the local Docker daemon; do not point it
 at a remote Docker context. It requires network access to npm, GitHub and image
 build dependencies. It does not update Traefik or install a scheduled auto-updater.
 
+Keep `kobo-vps-entrypoint` beside `kobo-update` when updating the operator scripts (the guided installer places both in `bin/`). This is required even when building an older release.
+
 Both operator scripts explicitly read the deployment directory's `.env` for
 Compose. Exported `KOBO_DOMAIN`, `KOBO_PROJECTS_DIR`, `TRAEFIK_NETWORK`,
-`TRAEFIK_ENTRYPOINT`, `TRAEFIK_CERTRESOLVER` and `COMPOSE_*` variables in the caller's
+`TRAEFIK_ENTRYPOINT`, `TRAEFIK_CERTRESOLVER`, `KOBO_UID`, `KOBO_GID` and `COMPOSE_*` variables in the caller's
 shell cannot override these commands. This applies to validation, start, stop and
 recovery. Docker context selection and forge authentication remain available to
 child processes; other commands such as image builds retain their environment.
@@ -457,7 +561,7 @@ original deadline and prompt stay unchanged. Already stale, never-attempted
 wakeups are not revived.
 It retrieves npm's `latest` version (or the explicit
 stable version), verifies the Git tag's commit and package version, builds a uniquely
-tagged image, ensures Compose is installed and checks native modules. The old
+tagged image, ensures Compose, Buildx, netcat and the non-root launcher are installed and checks native modules. The old
 service stays available during the build. Plan for roughly 5–15 minutes without
 build cache; backup duration depends on the volume size.
 

package/docs/getting-started.md

@@ -12,6 +12,11 @@ No skill plugin, forge CLI, Docker, Notion, Sentry or voice software is needed f
 
 For a remote installation, follow the [VPS and Docker guide](./deployment-vps.md) first: `kobo-install` guides a fresh installation behind existing Traefik and can configure a GitHub App bot. The same guide documents manual setup. The project picker browses the server/container filesystem: select a repository cloned there, not a folder on the PC running your browser. Authenticate the agent and forge tools inside the container too.
 
+The [VPS projects and skills guide](./vps-projects-and-skills.md) explains how to
+prepare environment files/dependencies, open a remote dev server through SSH,
+and install Claude/Codex skills as the non-root agent user. Host/PC installations
+are not automatically inherited by container agents.
+
 ## Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loicngr/kobo",
-  "version": "2.1.19",
+  "version": "2.1.21",
   "description": "Kōbō — local multi-workspace orchestrator for Claude Code and OpenAI Codex, with isolated Git worktrees, live review and optional automation.",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/scripts/kobo-install

@@ -20,7 +20,7 @@ spec = importlib.util.spec_from_loader(loader.name, loader)
 updater = importlib.util.module_from_spec(spec)
 loader.exec_module(updater)
 InstallError = updater.UpdateError
-TOOLS = ('kobo-install', 'kobo-update', 'kobo-github-app-token', 'kobo-gh')
+TOOLS = ('kobo-install', 'kobo-update', 'kobo-github-app-token', 'kobo-gh', 'kobo-vps-entrypoint')
 ENV_KEYS = updater.COMPOSE_ENV_KEYS
 
 
@@ -32,6 +32,10 @@ def safe_path(value):
 
 
 def validate_config(config):
+    for name in ('uid', 'gid'):
+        value = str(config.get(name, 1000))
+        if not re.fullmatch(r'[1-9][0-9]{0,9}', value) or int(value) > 2147483647:
+            raise InstallError('UID and GID must be positive non-root numeric IDs.')
     domain = config['domain']
     if (len(domain) > 253 or '.' not in domain or
             not all(re.fullmatch(r'[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?', label)
@@ -49,6 +53,9 @@ def validate_config(config):
         raise InstallError('Projects must be outside container system paths, /app and /root (for example /opt/kobo/projects).')
     if projects.exists() and not projects.is_dir():
         raise InstallError('The projects path must be a directory.')
+    if not projects.exists() and 'uid' in config and os.getuid() not in (0, int(config['uid'])):
+        raise InstallError('A new projects directory requires --uid to match the installer user, or root. '
+                           'Otherwise prepare a directory writable by that UID first.')
     app = [config.get(k) for k in ('github_app_id', 'github_installation_id', 'github_private_key')]
     if any(app):
         if not all(app):
@@ -58,6 +65,10 @@ def validate_config(config):
         key = safe_path(app[2])
         if not key.is_file() or not os.access(key, os.R_OK) or key.stat().st_mode & 0o077:
             raise InstallError('The GitHub private key must be a readable regular file with private permissions (0600).')
+        if 'uid' in config and key.stat().st_uid != int(config['uid']):
+            raise InstallError('The GitHub private key owner must match --uid so the non-root agent can read it.')
+        if 'uid' in config and os.getuid() not in (0, int(config['uid'])):
+            raise InstallError('Run the installer as --uid (or root) to create readable private GitHub configuration.')
     if config['version'] != 'latest':
         updater.normalize_version(config['version'])
 
@@ -81,7 +92,7 @@ def render(config, stack):
                        '        bind:\n          create_host_path: false\n')
         text = text.replace('    networks:\n', mounts + '    networks:\n', 1)
     values = (config['domain'], config['projects_directory'], config['network'],
-              config['entrypoint'], config['certresolver'])
+              config['entrypoint'], config['certresolver'], str(config.get('uid', 1000)), str(config.get('gid', 1000)))
     env = ''.join(f"{key}='{value}'\n" for key, value in zip(ENV_KEYS, values))
     return text, env
 
@@ -180,7 +191,13 @@ class Installer(updater.Updater):
             path = self.stack / name
             path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
             updater.atomic_write(path, data, 0o755 if name.startswith('bin/') else 0o600)
-        Path(config['projects_directory']).mkdir(parents=True, exist_ok=True)
+            if name == 'auth/github-app.json' and os.getuid() == 0:
+                os.chown(path, int(config.get('uid', 1000)), int(config.get('gid', 1000)))
+        projects = Path(config['projects_directory'])
+        projects_existed = projects.exists()
+        projects.mkdir(parents=True, exist_ok=True)
+        if not projects_existed and os.getuid() == 0:
+            os.chown(projects, int(config.get('uid', 1000)), int(config.get('gid', 1000)))
         self.save(phase='configured')
 
     def verify_files(self):
@@ -198,16 +215,19 @@ class Installer(updater.Updater):
         # No files or directories are needed for --check. All substitutions are supplied explicitly.
         text, _ = render(config, self.stack)
         for key, value in zip(ENV_KEYS, (config['domain'], config['projects_directory'], config['network'],
-                                       config['entrypoint'], config['certresolver'])):
+                                       config['entrypoint'], config['certresolver'],
+                                       str(config.get('uid', 1000)), str(config.get('gid', 1000)))):
             text = re.sub(r'\$\{' + key + r'(?::[^}]*)?\}', lambda _: value, text)
         self.run(['docker', 'compose', '--env-file', '/dev/null', '-p', 'kobo', '-f', '-', 'config', '--quiet'],
                  data=text.encode())
 
     def configure_github(self):
-        self.run(self.compose('exec', '-T', 'kobo', '/usr/local/bin/kobo-github-app-token', '--check'))
+        # Legacy prepared installations retain their original root execution.
+        runtime = ['kobo-vps-entrypoint', '--exec'] if 'uid' in self.state.get('config', {}) else []
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, '/usr/local/bin/kobo-github-app-token', '--check'))
         helper = 'credential.https://github.com.helper'
-        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--replace-all', helper, ''))
-        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--add', helper,
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, 'git', 'config', '--global', '--replace-all', helper, ''))
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, 'git', 'config', '--global', '--add', helper,
                              '!/usr/local/bin/gh auth git-credential'))
 
     def assert_started(self):
@@ -297,6 +317,8 @@ class Installer(updater.Updater):
 def arguments(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--directory', type=Path, required=True)
+    parser.add_argument('--uid', help='Non-root runtime UID (defaults to the invoking user).')
+    parser.add_argument('--gid', help='Runtime GID (defaults to the invoking user).')
     for name in ('domain', 'projects-directory', 'network', 'entrypoint', 'certresolver', 'version',
                  'github-app-id', 'github-installation-id', 'github-private-key'):
         parser.add_argument('--' + name)
@@ -311,7 +333,7 @@ def arguments(argv=None):
 
 def configure(args, installer):
     names = ('domain', 'projects_directory', 'network', 'entrypoint', 'certresolver', 'version',
-             'github_app_id', 'github_installation_id', 'github_private_key', 'docker_socket')
+             'github_app_id', 'github_installation_id', 'github_private_key', 'docker_socket', 'uid', 'gid')
     config = installer.state.get('config', {}).copy()
     config.update({name: getattr(args, name) for name in names if getattr(args, name) is not None})
     interactive = sys.stdin.isatty() and not args.yes
@@ -339,6 +361,10 @@ def configure(args, installer):
     ask('entrypoint', 'Traefik HTTPS entrypoint')
     ask('certresolver', 'Traefik certificate resolver (empty for preloaded certificate)', '')
     ask('version', 'Stable release version', 'latest')
+    # Do not silently change an already managed deployment's recorded config.
+    if not installer.state:
+        ask('uid', 'Host user ID for Kōbō and agents', str(os.getuid() or 1000))
+        ask('gid', 'Host group ID for Kōbō and agents', str(os.getgid() or 1000))
     if config.get('docker_socket') is None:
         config['docker_socket'] = interactive and input('Give agents Docker access (root-equivalent host control)? [y/N]: ').lower() == 'y'
     if not any(config.get(name) for name in ('github_app_id', 'github_installation_id', 'github_private_key')):
@@ -365,6 +391,7 @@ def main(argv=None):
             return 0
         print(f'Install directory: {installer.stack}\nURL: https://{config["domain"]}\n'
               f'Projects: {config["projects_directory"]}\nDocker socket: {config["docker_socket"]}\n'
+              f'Runtime UID:GID: {config.get("uid", "legacy")}:{config.get("gid", "legacy")}\n'
               f'GitHub App: {bool(config["github_app_id"])}')
         if not args.yes and not installer.state:
             if not sys.stdin.isatty() or input('Create this installation? [y/N]: ').lower() != 'y':

package/scripts/kobo-update

@@ -21,7 +21,7 @@ from datetime import datetime, timezone
 REPO = 'https://github.com/loicngr/kobo.git'
 VERSION = re.compile(r'\d+\.\d+\.\d+')
 COMPOSE_ENV_KEYS = ('KOBO_DOMAIN', 'KOBO_PROJECTS_DIR', 'TRAEFIK_NETWORK',
-                    'TRAEFIK_ENTRYPOINT', 'TRAEFIK_CERTRESOLVER')
+                    'TRAEFIK_ENTRYPOINT', 'TRAEFIK_CERTRESOLVER', 'KOBO_UID', 'KOBO_GID')
 BUSY_JS = r"""
 const db = new (require('better-sqlite3'))('/root/.config/kobo/kobo.db', {readonly:true});
 const sessions = db.prepare("SELECT count(*) n FROM agent_sessions WHERE status = 'running'").get().n;
@@ -262,15 +262,29 @@ class Updater:
         self.logged(['docker', 'build', '--progress=plain', '-t', base, str(source)])
         overlay = self.job / 'overlay'
         overlay.mkdir()
+        launcher = Path(__file__).resolve().with_name('kobo-vps-entrypoint')
+        if not launcher.is_file():
+            raise UpdateError('Install kobo-vps-entrypoint beside kobo-update before building an image.')
+        shutil.copyfile(launcher, overlay / 'kobo-vps-entrypoint')
         (overlay / 'Dockerfile').write_text(
-            f'FROM {base}\nRUN docker compose version >/dev/null 2>&1 || '
-            '(apt-get update && apt-get install -y --no-install-recommends docker-compose-plugin '
-            '&& rm -rf /var/lib/apt/lists/*)\n')
+            f'FROM {base}\nUSER root\n'
+            'RUN apt-get update && apt-get install -y --no-install-recommends '
+            'docker-compose-plugin docker-buildx-plugin netcat-openbsd util-linux '
+            '&& rm -rf /var/lib/apt/lists/*\n'
+            'COPY --chmod=755 kobo-vps-entrypoint /usr/local/bin/kobo-vps-entrypoint\n'
+            'RUN chmod a+r /app/package.json /app/package-lock.json /app/CHANGELOG.md '
+            '&& chmod -R a+rX /app/dist /app/src/client/dist\n')
         self.logged(['docker', 'build', '--progress=plain', '-t', image, str(overlay)])
         self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'docker',
                   image, 'compose', 'version'])
         self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'node', image,
                   '-e', "require('better-sqlite3')(':memory:').close();require('node-pty')"])
+        self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'kobo-vps-entrypoint',
+                  image, 'node', '-e', "if(process.getuid()===0)process.exit(1);"
+                  "const fs=require('fs');const dir='/app/src/client/dist/';"
+                  "const mode=['pwa','spa'].find(m=>fs.existsSync(dir+m+'/index.html'));"
+                  "if(!mode)throw Error('Missing built UI');fs.accessSync(dir+mode+'/index.html',fs.constants.R_OK);"
+                  "require('better-sqlite3')(':memory:').close();require('node-pty')"])
         return image
 
     def backup(self):

package/src/mcp-server/README.md

@@ -578,7 +578,9 @@ IDs. Workspace-bound callers omit those fields: the backend derives their scope
 from a per-launch capability. They cannot forge another workspace, session or
 launch. The managed server exposes the same tools to capable subagents; custom
 subagent tool restrictions still apply. If a child lacks access, the parent
-reports its activity rather than creating a duplicate indicator.
+reports its observed milestones and outcome rather than creating a duplicate
+indicator. Pass the full create → update → finish lifecycle to delegates; they
+must finish their own activity before returning when its outcome is known.
 
 For example, an external client can create an activity with:
 
@@ -593,7 +595,9 @@ For example, an external client can create an activity with:
 }
 ```
 
-Keep the returned `id`. Report absolute progress with `update_progress_bar`:
+Keep the returned `id` and `sequence`. Update **the same bar** at actual phase
+changes and meaningful completed milestones, including during a long phase.
+Report absolute progress with `update_progress_bar`:
 
 ```json
 {
@@ -607,8 +611,28 @@ Keep the returned `id`. Report absolute progress with `update_progress_bar`:
 }
 ```
 
-Then call `finish_progress_bar` with the same scope/id, a higher `sequence`,
-`outcome: "succeeded"` or `"failed"`, and an optional summary in `step`.
+An audit with no measurable denominator still needs step updates. After creating
+an indeterminate activity, send this when its phase changes:
+
+```json
+{
+  "workspace_id": "<workspace ID>",
+  "session_id": "<session ID>",
+  "progress_id": "<returned id>",
+  "sequence": 1,
+  "step": "Code inspection complete; verifying findings"
+}
+```
+
+Omitting **both** `current` and `total` is valid on updates. It keeps an
+indeterminate activity indeterminate, or preserves existing numeric values.
+Do not invent a percentage, send unchanged updates or create periodic LLM turns
+just to refresh a bar.
+
+Before your final report (or return to the parent), call `finish_progress_bar`
+with the same scope/id, a higher `sequence`, `outcome: "succeeded"` or `"failed"`,
+and an optional summary in `step`, once the outcome is known. Do not finish an
+activity merely because you yield while its background work continues.
 Supply numeric progress only when known: both values must be finite, with
 `total > 0` and `0 <= current <= total`. Omit both at creation, or send both as
 `null`, for an indeterminate indicator. Updates with no numeric pair keep the