Nicolas Cantu
615958469d
**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
119 lines
6.0 KiB
Markdown
119 lines
6.0 KiB
Markdown
# AnythingLLM Workspaces (VS Code / Cursor)
|
||
|
||
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.
|
||
|
||
## Features
|
||
|
||
| 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`. |
|
||
|
||
## Requirements
|
||
|
||
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
|
||
|
||
Open **Settings**, search for **AnythingLLM**, or edit **User** `settings.json`:
|
||
|
||
| 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. |
|
||
|
||
Use **User** settings so secrets are not committed with a workspace.
|
||
|
||
## Commands (Command Palette)
|
||
|
||
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 <git-url>` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`**. |
|
||
| `/repos-clone-sync <url>` | 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 <folder-name>` | `POST /repos-load` — verify folder + **Open folder**. |
|
||
| `/repos-load-sync <name>` | Same as load + ensure workspace + browser. |
|
||
| `/workspace-load <name>` | 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 name:** Matching uses **exact** equality on AnythingLLM `name` or `slug` and the repo folder name you pass. Creation body: `{ "name": "<name>" }`.
|
||
|
||
**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 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
|
||
|
||
```bash
|
||
cd extensions/anythingllm-workspaces
|
||
npm install
|
||
npm run compile
|
||
```
|
||
|
||
Package: `npx @vscode/vsce package --allow-missing-repository` (Node 20+ recommended for current `vsce`).
|
||
|
||
## API reference
|
||
|
||
- 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
|