From 615958469d61686253bb40b023d4d0bbc8740118 Mon Sep 17 00:00:00 2001 From: Nicolas Cantu Date: Mon, 23 Mar 2026 22:28:03 +0100 Subject: [PATCH] docs(extension): expand AnythingLLM Workspaces README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Motivations:** - Clear usage: palette, Dev tools panel, install, troubleshooting **Root causes:** - N/A **Correctifs:** - N/A **Evolutions:** - README sections: requirements, configuration, commands, SSH note, API refs **Pages affectées:** - extensions/anythingllm-workspaces/README.md --- extensions/anythingllm-workspaces/README.md | 116 ++++++++++++++------ 1 file changed, 85 insertions(+), 31 deletions(-) diff --git a/extensions/anythingllm-workspaces/README.md b/extensions/anythingllm-workspaces/README.md index c21d835..d89121e 100644 --- a/extensions/anythingllm-workspaces/README.md +++ b/extensions/anythingllm-workspaces/README.md @@ -1,52 +1,102 @@ -# AnythingLLM Workspaces (VS Code / Cursor extension) +# AnythingLLM Workspaces (VS Code / Cursor) -Extension for the **AnythingLLM developer API**, optional **local repos API** (`repos-devtools-server`), and a **dev tools panel** for slash-style commands. +Extension that talks to the **AnythingLLM developer HTTP API** (list/create workspaces, open the UI in a browser). Optionally uses a **local repos HTTP service** (`repos-devtools-server`) to clone or open Git folders under a configured root, from a **Dev tools** webview panel. -## Prerequisites +## Features -- AnythingLLM reachable at your public base URL (e.g. `https://ia.enso.4nkweb.com/anythingllm`). -- An **API key** created in AnythingLLM: **Settings → API Keys**. +| Area | What it does | +|------|----------------| +| AnythingLLM | List workspaces, open one in the browser, open the web UI. | +| Workspace ensure | If no workspace matches a repo folder name, create it via `POST /api/v1/workspace/new`. | +| Local repos API | Clone (`branch` **test** by default), list git folders, resolve paths — requires `repos-devtools-server`. | -**Do not** use the **nginx Bearer secret** for `/ollama/` (see `deploy/nginx/README-ia-enso.md`). That value is only for the Ollama reverse proxy. AnythingLLM validates API keys against its **own** database; a wrong secret yields `403` with `{"error":"No valid api key found."}`. +## Requirements -For **clone / repos-list / repos-load**, run **`services/repos-devtools-server`** on the host that owns the clone root (e.g. `192.168.1.164` with `REPOS_DEVTOOLS_ROOT=/home/ncantu/code`). The extension calls this API over HTTP (default `http://127.0.0.1:37140` when your editor runs on that same host or via port-forward). +1. **AnythingLLM** reachable at a public base URL (example: `https://ia.enso.4nkweb.com/anythingllm`). +2. An **API key** from AnythingLLM: **Settings → API Keys**. + +**Important:** Do **not** put the **nginx Bearer secret** used for `/ollama/` here (see `deploy/nginx/README-ia-enso.md`). AnythingLLM only accepts keys stored in its own app; a wrong value returns `403` and `{"error":"No valid api key found."}`. + +3. For **clone / repos-list / repos-load** commands: run **`repos-devtools-server`** on the machine that owns the clone directory (see `../../services/repos-devtools-server/README.md`). Default URL from the editor: `http://127.0.0.1:37140`. If Cursor connects over **SSH** to that host, `127.0.0.1` is the remote machine — no port forward needed. If the editor runs on another PC, set `anythingllm.reposApiBaseUrl` to a tunnel or the server’s reachable address. + +## Installation + +- **From source:** open `extensions/anythingllm-workspaces` in VS Code / Cursor, **Run → Start Debugging** (Extension Development Host). +- **From VSIX:** + `npm install && npm run compile && npx @vscode/vsce package` + then **Extensions → … → Install from VSIX…** and pick `anythingllm-workspaces-*.vsix`. + +After install or upgrade, run **Developer: Reload Window** if commands are missing. ## Configuration -| Setting | Description | -|--------|-------------| -| `anythingllm.baseUrl` | Base URL without trailing slash (default matches `deploy/nginx/README-ia-enso.md`). | -| `anythingllm.apiKey` | Secret from AnythingLLM **Settings → API Keys** (optional leading `Bearer ` is stripped). Use **User** settings. | -| `anythingllm.reposApiBaseUrl` | `repos-devtools-server` base URL (no trailing slash), default `http://127.0.0.1:37140`. | -| `anythingllm.reposApiToken` | Same value as `REPOS_DEVTOOLS_TOKEN` on the server. **User** settings. | +Open **Settings**, search for **AnythingLLM**, or edit **User** `settings.json`: -## Commands (palette) +| Key | Description | +|-----|-------------| +| `anythingllm.baseUrl` | AnythingLLM public base URL, **no** trailing slash. | +| `anythingllm.apiKey` | API key from AnythingLLM (a leading `Bearer ` prefix is stripped if present). | +| `anythingllm.reposApiBaseUrl` | `repos-devtools-server` base URL, no trailing slash (default `http://127.0.0.1:37140`). | +| `anythingllm.reposApiToken` | Same secret as `REPOS_DEVTOOLS_TOKEN` on the server. | -- **AnythingLLM: List workspaces** — `GET /api/v1/workspaces`, then open the chosen workspace in the browser. -- **AnythingLLM: Open web UI** — Opens the AnythingLLM base URL. -- **AnythingLLM: Dev tools panel** — Webview: enter commands, **Run**, read JSON/text **Response**. +Use **User** settings so secrets are not committed with a workspace. -## Dev tools panel — command lines +## Commands (Command Palette) -One command per line: +Open the palette: **Ctrl+Shift+P** (Windows / Linux) or **Cmd+Shift+P** (macOS). + +| Title in palette | Command ID | Action | +|------------------|------------|--------| +| **AnythingLLM: List workspaces** | `anythingllm.listWorkspaces` | Calls `GET /api/v1/workspaces`, pick a workspace, open it in the browser. | +| **AnythingLLM: Open web UI** | `anythingllm.openWebUi` | Opens `anythingllm.baseUrl` in the browser. | +| **AnythingLLM: Dev tools panel** | `anythingllm.openDevToolsPanel` | Opens the Dev tools webview (see below). | + +## Dev tools panel + +### How to open it + +1. **Ctrl+Shift+P** / **Cmd+Shift+P** +2. Type **AnythingLLM: Dev tools panel** (or `dev tools`, `anythingllm`). +3. **Enter** + +A side editor tab opens with: + +- A **Commands** text area (one command per line) +- **Run** — execute all non-empty lines in order +- **Clear output** +- **Response** — JSON or text from the server / API, or `ERROR: …` + +Settings are read **when you click Run**, so you can change `baseUrl` or tokens without reopening the panel. + +### Command lines | Line | Behaviour | |------|-----------| -| `/repos-clone ` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`** (override with JSON only via API, not this line). | -| `/repos-clone-sync ` | Clone + ensure AnythingLLM workspace named like the repo folder + **Open folder** + open workspace in browser. | -| `repos-list` or `/repos-list` | `GET /repos-list` — cloned git directories under the root. | -| `/repos-load ` | Verify repo folder + **Open folder** in the editor. | -| `/repos-load-sync ` | Open folder + ensure workspace + browser. | -| `/workspace-load ` | Ensure workspace exists (`GET /workspaces` then `POST /workspace/new` if missing) + browser. | -| `help` | Short built-in help text. | +| `/repos-clone ` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`**. | +| `/repos-clone-sync ` | Same as clone, then ensure an AnythingLLM workspace with the **same name as the repo folder**, **Open folder** in the editor, open that workspace in the browser. | +| `repos-list` or `/repos-list` | `GET /repos-list` — git repositories under the server root. | +| `/repos-load ` | `POST /repos-load` — verify folder + **Open folder**. | +| `/repos-load-sync ` | Same as load + ensure workspace + browser. | +| `/workspace-load ` | List workspaces; if none matches by **name** or **slug**, create via API; then open browser. | +| `help` or `/help` | Print built-in help in **Response**. | -**Workspace matching:** name or slug must equal the folder/repo name you use (exact string match on `name` or `slug` from AnythingLLM). New workspaces are created with `POST /api/v1/workspace/new` and `{ "name": "" }`. +**Workspace name:** Matching uses **exact** equality on AnythingLLM `name` or `slug` and the repo folder name you pass. Creation body: `{ "name": "" }`. -**AnythingLLM “user”:** the developer API uses the **API key**; per-user workspace ownership follows AnythingLLM’s own multi-user rules — this extension does not impersonate a browser session. +**API key vs browser user:** The extension only uses the **developer API key**. Multi-user behaviour is defined by AnythingLLM for that key. ## Ollama -This extension does not call Ollama. For `https://ia.enso.4nkweb.com/ollama/v1`, use Cursor model settings and the nginx Bearer (see `deploy/nginx/README-ia-enso.md`). +This extension does **not** call Ollama. For OpenAI-compatible URLs such as `https://ia.enso.4nkweb.com/ollama/v1`, configure the editor’s model provider and use the nginx Bearer as documented in `deploy/nginx/README-ia-enso.md`. + +## Troubleshooting + +| Symptom | Check | +|---------|--------| +| `403` / `No valid api key found` | Use an AnythingLLM **Settings → API Keys** value, not the Ollama nginx Bearer. | +| `401` on clone/list/load | `anythingllm.reposApiToken` must equal `REPOS_DEVTOOLS_TOKEN` on `repos-devtools-server`. | +| `ECONNREFUSED` / fetch failed | Server running? Correct `anythingllm.reposApiBaseUrl`? | +| Command palette has no AnythingLLM entries | Extension enabled? **Developer: Reload Window**. | +| Clone fails | Remote must expose branch **`test`** (or change branch via the HTTP API body, not the one-line panel command). | ## Build @@ -56,9 +106,13 @@ npm install npm run compile ``` -Load the folder in VS Code / Cursor with **Run Extension** or install the packaged `.vsix` after `vsce package`. +Package: `npx @vscode/vsce package --allow-missing-repository` (Node 20+ recommended for current `vsce`). ## API reference -- AnythingLLM: `server/endpoints/api/workspace/index.js` (e.g. `GET /v1/workspaces`, `POST /v1/workspace/new` under `/api`). +- AnythingLLM (upstream): Mintplex-Labs **anything-llm** — `server/endpoints/api/workspace/index.js` (routes under `/api`, e.g. `GET /v1/workspaces`, `POST /v1/workspace/new`). - Local repos: `services/repos-devtools-server/README.md`. + +## License + +MIT