Reported issues for vnsh

Pod holds 16 of 18 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to vnsh.

Most discussed

Add search, filtering and knowledge discovery across accessible documents

Parent: #49

Problem

A knowledge system that requires users and agents to already know every URL is not discoverable.

V1 scope

Search non-sensitive metadata: title, tags, type, status, author and timestamps.
Filter by space, collection, type, tag, status and recency.
Provide recent/changed-since queries for agent synchronization.
Add browser search plus CLI and MCP search/list operations.
Define pagination, stable ordering and result snippets.
For encrypted body search, begi

Read the thread · 2026-08-13 · open · 2 comments

Decision gate: does more than one agent actually touch a workspace?

The gate for the whole v2 bet:

SELECT blob3 AS workspace, count(DISTINCT blob4) AS agents
FROM vnsh_events
WHERE blob1 LIKE 'workspace%'
GROUP BY workspace

blob4 is the agent identity, taken from the MCP initialize handshake. It has to be counted rather than blob2 (client type): every MCP client reaches vnsh through the same server and reports mcp, so counting client types would show 1 for three collaborating agents and 2 for a single agent using two surfaces — wrong in both

Read the thread · 2026-07-28 · open · 2 comments

Artifact V1: add cross-surface create, update, review-request and handoff operations

Parent: #59

Goal

Give browser, CLI and MCP one coherent collaboration contract instead of implementing Artifact semantics independently.

Operations

create Artifact;
get/list/search;
read current or selected version;
update with expected version;
attach change summary and evidence;
request human review;
hand off with principal, instruction and per-Artifact scope;
inspect capabilities and status.

Design constraints

Use one canonical validation/URL/version package w

Read the thread · 2026-08-13 · open · 1 comment

Migrate existing permanent workspaces and artifacts into Knowledge Spaces safely

Parent: #49

Goal

Introduce Knowledge Spaces without breaking existing permanent URLs, ownership, encryption, history or automation.

Scope

assign existing permanent documents to a default personal space;
backfill safe metadata defaults;
preserve all /w/, /artifact/, /p/, #w= and #r= URLs;
define opt-in conversion from URL-key encryption to managed-space encryption;
preserve version history, quota accounting and public/private visibility;
update account UI, API, CLI

Read the thread · 2026-08-13 · open · 1 comment

Expose vnsh knowledge as MCP Resources and add project bootstrap

Parent: #49

Goal

Make vnsh knowledge discoverable through standard MCP primitives, not only callable tools that require a preexisting URL.

Scope

Advertise MCP Resources and Resource Templates for spaces, documents and artifacts.
Support list/read discovery with stable vnsh resource URIs.
Keep mutating behavior in tools.
Add a bounded project-bootstrap operation/resource that returns:
- project overview;
- current-state and handoff documents;
- active decisions and runbook

Read the thread · 2026-08-13 · open · 1 comment

Self-describing responses: Link rel=describedby, and workspaces in /llms.txt

An agent that meets a vnsh.dev/w/ link with no vnsh tooling installed has no way to learn what to do with it. /llms.txt documents this, but nothing points there from the resource itself.

Adding a Link header to workspace and blob responses lets an agent bootstrap from the response alone, with no prior knowledge and nothing installed:

Link: <https://vnsh.dev/llms.txt>; rel="describedby"

This is the widest tier of the distribution ladder: it reaches every agent that can make an HT

Read the thread · 2026-07-28 · closed · 1 comment

No per-directory agent guidance (AGENTS.md)

There is a root CLAUDE.md and nothing else. worker/, mcp/, cli/, extension/ and tests/ have no local guidance about conventions, test commands, security constraints or the traps specific to each.

Several traps in this repo are non-obvious and have each cost real time:

worker/ — client JS lives inside TypeScript template literals, so backslashes must be doubled or regexes silently break at runtime. Neither the type checker nor unit tests catch it.
worker/test/ —

Read the thread · 2026-07-28 · closed · 1 comment

Version metadata disagrees across package.json, server.json, runtime and client headers

Version strings disagree across the MCP package:

Where	Value
`mcp/package.json`	1.3.0
`mcp/server.json`	was 1.0.1 for two releases, now synced
MCP server runtime `new Server({version})`	1.0.0
`cli/npm` client header	`cli-npm/2.0.0` while the package is 2.1.x

server.json drove the registry entry, so the public listing advertised 1.0.1 while npm shipped 1.2.0. The runtime version appears in the MCP handshake, so clients see 1.0.0 regardless of what is in

Read the thread · 2026-07-28 · closed · 1 comment

Most recent

Artifact V1: make first Library Artifact creatable from official MCP

Found by zero-background onboarding dogfood. The empty Account Library says 'connect an Agent', but vnsh-mcp 1.7 only creates encrypted legacy /artifact/# links; it cannot create, discover or version the service-readable Account Artifacts shown in the Library.\n\nAcceptance:\n- MCP exposes account Artifact create/list/read/update tools.\n- Missing/expired VNSH_TOKEN errors explain the Human action.\n- list removes the pasted-URL requirement.\n- updates require explicit base version and surface c

Read the thread · 2026-08-13 · closed · 0 comments

Artifact V1: make Agent onboarding, discovery and handoff work without pasted URLs

Parent: #59 Related MCP Resources: #54

Problem

If every interaction requires a human to paste an Artifact URL plus instructions, vnsh has not become an Agent collaboration layer.

Journey

One-time setup:

vn login
vn mcp setup

Afterward an authenticated Agent can:

list/search accessible Artifacts;
inspect needs-review and changes-requested queues;
read current or historical versions;
create/update drafts;
request human review;
receive a scoped handoff to one Arti

Read the thread · 2026-08-13 · open · 0 comments

Artifact V1: publish latest or pin an approved version

Parent: #59

Goal

Let humans share a stable result while agents continue iterating privately.

V1 behavior

A human can enable an unguessable public share URL and choose:

Latest — follows future current versions; or
Pinned — permanently resolves to a selected approved version until the owner changes it.

The public URL lives on the isolated content domain and never grants edit access.

Acceptance criteria

Only authorized humans can enable, change or revoke publicati

Read the thread · 2026-08-13 · open · 0 comments

Artifact V1: add Human review and approval gates

Parent: #59

Goal

Keep humans meaningfully in the loop without blocking routine agent iteration.

Workflow

Agent/editor updates a draft and calls request review.
Human reviewer sees a Needs review inbox.
Human compares the proposed version and provenance.
Human approves that exact version or requests changes with a note.
Agents can continue creating later versions; approval remains attached to the reviewed version.

Authority

Agent tokens may request review but cannot appro

Read the thread · 2026-08-13 · open · 0 comments

CLI cannot create or read workspaces

The vn shell function and the vnsh npm CLI can only create one-shot /v/ blobs. Neither can create, read or update a workspace, so the terminal — the surface most of the existing audience arrives through — cannot reach the feature the site now leads with.

The npm CLI is the easy half: it already uses Node's crypto, so HKDF and AES-256-GCM cost nothing extra. The logic can be lifted from mcp/src/crypto.ts.

vnsh workspace new [file]      create, print both links
vnsh workspace read 

[Read the thread](https://github.com/raullenchai/vnsh/issues/17) · 2026-07-28 · closed · 1 comment

### Claude Code plugin, and a human-side trigger for creating workspaces

**Agents will not spontaneously create a workspace.** They are single-session:
Claude Code has no way to know another agent is open in a different window, and
nothing in its context suggests a cross-platform handoff is needed. Betting on
tool-description wording alone means waiting for an intent the model has no basis
to form.

The triggers split by reliability:

| Action | Reliability | Trigger |
|---|---|---|
| Create | **unreliable** | Must come from a human — a command, hook or keybinding |

[Read the thread](https://github.com/raullenchai/vnsh/issues/15) · 2026-07-28 · closed · 1 comment

### OpenHands microagent — one markdown file bootstraps the integration

OpenHands has the shortest integration path of any agent: repo microagents live in
`.openhands/microagents/`, are markdown with YAML frontmatter, support `triggers:`
keywords, and carry an `mcp_location` field pointing at an MCP server. **A single
markdown file can bootstrap the whole integration.** (V1 renames microagents to
*skills*.)

**Done when**
- [ ] `.openhands/microagents/vnsh.md` exists with triggers and `mcp_location`
- [ ] OpenHands picks up the workspace tools without manual MCP con

[Read the thread](https://github.com/raullenchai/vnsh/issues/14) · 2026-07-28 · open · 0 comments

### Append channel: conflict-free concurrent writes without CRDT

`PUT` replaces the whole document, so two agents working at once means one gets a
412 and has to merge. Merging is exactly what language models are unreliable at,
and a bad merge silently destroys the other agent's work.

Appending is conflict-free *by construction* and needs no CRDT:

POST /api/workspace/:id/append no If-Match; the server serialises


Each chunk carries its own nonce and is encrypted with the same content key; the
client concatenates on read. With no "based on which v

[Read the thread](https://github.com/raullenchai/vnsh/issues/11) · 2026-07-28 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/raullenchai/vnsh/issues).