Skip to content

quickstart.md

Latest commit

 

History

History
166 lines (106 loc) · 14.6 KB

quickstart.md

File metadata and controls

166 lines (106 loc) · 14.6 KB
Raw

Quickstart

Get Exxperts running, connect your AI, and save your first memory, all in about five minutes.

Exxperts is a local-first platform for persistent AI colleagues. Each room houses an exxpert - an agent with durable, governed memory: everything it remembers lives in plain files on your machine, every memory write goes through an approval workflow you control, and the memory belongs to the room, not to any model vendor.

Ways to use exxperts

Three doors into the same product, all sharing the same local data under ~/.exxperts (rooms, memory, provider logins), one local server at a time:

  • Desktop app (macOS Apple Silicon, Windows x64): signed builds, download links in the README. The app is self-contained and always runs its own version, and it uses the same data as a terminal install.
  • Terminal install: the one-line command below; gives you the exxperts commands.
  • Repo clone: for contributors; the by-hand steps are below, the full guide is CONTRIBUTING.md.

If you take the app door, skip to step 2 once it opens.

What you need

  • macOS, Windows, or Linux with a terminal, and about 1 GB of free disk space (updates briefly peak at about 1.4 GB while the new version is unpacked next to the old one). On macOS with Apple Silicon, Windows x64, and Linux x64, the one-line install below needs nothing else preinstalled; other platforms automatically build from source, which needs the git and Node.js from the next bullet.
  • Only for shell access in rooms and for the build-from-source fallback: git (on Windows, Git for Windows; rooms' optional shell tool runs through Git Bash) and Node.js 20.6+ with npm (check with node --version; if missing, install the LTS from nodejs.org). Building from source takes about 3 GB of disk.
  • An AI subscription: Claude (Pro/Max) or ChatGPT Plus/Pro, or an OpenAI-compatible gateway if you or your org run one.

1. Install and run

One command installs everything: it downloads a prebuilt archive for your platform (no Node.js, npm, or Git needed) and installs the exxperts command. Prebuilt archives exist for macOS on Apple Silicon, Windows x64, and Linux x64; on any other platform, or when the download fails, the same command automatically falls back to building from source (that path needs git and Node.js 20.6+ and clones the repo into ~/exxperts). Re-run it anytime to update. The archives and their checksums are published on GitHub Releases; release-pipeline.md describes how they are built.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/EXXETA/exxperts/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/EXXETA/exxperts/main/install.ps1 | iex

Then start the web app:

exxperts web

Windows note: if PowerShell refuses to run exxperts afterwards ("running scripts is disabled on this system"), that is PowerShell's default script policy, not a broken install. Either run it from cmd.exe or Git Bash, or allow npm-installed commands for your user once and open a new terminal:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Prefer to do it by hand? The same commands work on every platform (on Windows, apply the two Git settings from Windows notes below before cloning; the one-line installer does that for you):

git clone https://github.com/EXXETA/exxperts.git
cd exxperts
npm install
npm run install:global   # builds, packs, and installs the exxperts commands
exxperts web

The web app starts on http://127.0.0.1:8787 and opens in your browser (if it doesn't, open the URL the command prints). Everything runs locally: the server only listens on your machine (unless you later opt in to remote mode, which serves your own paired devices over your private tunnel; see SECURITY.md).

If install:global fails with ENOTEMPTY, an older exxperts install is in the way: run npm uninstall -g @exxeta/exxperts-app, delete the leftover directory the error names if it survives, and retry. (The tarball it mentions is named after the npm package @exxeta/exxperts-app; Exxeta is the company behind exxperts.)

If it fails with EACCES on macOS/Linux, use a user-level npm prefix instead of sudo:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Prefer running straight from the clone without installing commands? npm run build, then ./scripts/exxperts-web (macOS/Linux/Git Bash) or node bin\exxperts-web.cjs (Windows).

Updating later: re-run the one-line install command. On the platforms with prebuilt archives it performs an archive install even when you previously built from source: it migrates you to the archive install, carries app/.env over, and uninstalls the old npm-based global command (the clone stays in place); set EXXPERTS_INSTALL_METHOD=source to stay on a source install instead. Archive installs update in place and keep the install's app/.env; your rooms, memory, and provider logins in ~/.exxperts are never touched by installs or updates. Updating a source install by hand: from the repo folder, git pull, npm install, npm run install:global. Confirm with exxperts --version. If anything misbehaves, exxperts doctor checks your install and the optional layers on any install type and prints the fix (contributors working from a clone can also use npm run doctor).

Windows notes

Windows is supported for the desktop app, the web app, and the CLI/TUI; the desktop app and the one-line installer need nothing preinstalled on Windows x64. The requirements below matter for two things only, shell access in rooms and installing from source (by hand or via the installer's fallback):

  1. Git for Windows ≥ 2.40 (https://gitforwindows.org), needed for the source install path and for rooms' optional shell tool: that tool runs commands through Git Bash's bash.exe, which is discovered automatically from your Git installation, whether machine-wide (C:\Program Files\Git) or per-user (%LOCALAPPDATA%\Programs\Git, the no-admin install), or on PATH. A WSL bash on PATH also works for rooms' shell tool; in that case commands run inside the WSL Linux environment (Windows drives under /mnt/c, the distro's own tools).
  2. Node.js 20.6+ (LTS recommended) and npm (https://nodejs.org), needed for the source install path only; the prebuilt archive bundles its own Node runtime.
  3. Windows Terminal recommended for the CLI/TUI (legacy conhost is untested).

One-time Git settings before cloning (long paths matter because node_modules trees exceed the 260-character MAX_PATH); clone into a folder your user owns (for example under %USERPROFILE%), never into C:\ or C:\Program Files:

git config --global core.longpaths true
git config --global core.autocrlf false   # the repo's .gitattributes manages line endings

Developing from a clone without a global install? Use the shell-independent forms: node bin\exxperts-web.cjs, node bin\exxperts-cli.cjs, and node scripts\exxeta-web.mjs (dev web app with server + Vite UI). The bash launchers in scripts/ also work from Git Bash.

2. Connect your AI

Open AI setup in the web app.

  • Claude or ChatGPT Plus/Pro: click Sign in on the provider's row. The provider's login opens in a new browser tab; complete it there and the page updates by itself. Credentials stay on your machine, in the local credential store.
  • OpenAI-compatible gateway (or any other provider): on the same page, choose Add provider. For a gateway, choose Add gateway, give it a name, enter its base URL and API key, load its models and approve the ones your rooms may use; the terminal wizard (exxperts setup openai-compatible) still works too. Details: Provider setup.

Signing in is enough: the provider's models join the model pickers, and the Default models on the same page start on the first provider you sign in to. Each room can pick its own Conversation and Memory models later in Room settings, Model. A room never switches models on its own: if its model's provider is signed out later, the room waits until you sign in again or choose another model.

3. Create your first room

From Home, create a room. A room is a persistent colleague: it keeps its own memory, workspace, and conversation threads, and it picks a working style at creation.

Try this:

  1. Chat normally: ask it to help with something real.
  2. Tell it something worth keeping: "Remember that I prefer concise summaries."
  3. Paste a screenshot straight into the message box with Cmd+V (Ctrl+V on Windows): it stages as an attachment, exactly as if you had added it through Files.
  4. When you finish the session, press Remember next to the message box. The room keeps a short summary of the conversation, and anything you explicitly asked it to remember becomes a pinned note when the conversation is memorized.

Nothing enters memory silently. Remember shows you the proposal before it saves, and a room can be set to save clean proposals without that preview; anything questionable always comes back to you. Later, as remembered conversations accumulate, the room offers Memorize (turning them into lasting notes, grouped by topic) and Review (tidying the notes it has), both approval-gated the same way, and both undoable. Each room also has a memory budget for its notes: Room settings and the Memory page show how full the memory is, and notes that would not fit move to an archive the room can still read, only when you save. Remember warns when one more save would fill the room's waiting list; Memorize then clears it. The full story: Memory.

The app's Settings open with Cmd+, (Ctrl+, on Windows), and a room's settings with Cmd+Shift+, or the gear in the room.

Order your rooms

With two or more rooms, Home shows a Sort control at the top right. Choose Last used (the room where a message was last sent comes first, through whichever door, scheduled runs included; until a room is used after this update, its most recent conversation stands in; rooms never used follow, by name), Name A→Z, Name Z→A, or Custom. Custom opens arrange mode the first time, on the order you see; once an arrangement is saved, the Arrange link beside the control reopens it. In arrange mode, drag each room into place (on a touch screen, a long press picks it up; with the keyboard, the arrow keys move the focused room, Home and End to the ends), then Save. Cancel or Escape leaves the order as it was. The order is saved with your rooms, not in the browser, so the desktop app, the web app and your phone all show the same one; a phone paired read-only sees it and cannot change it. "New room" is always last, and the archived section is not sorted.

4. Give the room a workspace (optional)

In the room's settings, set a workspace folder and pick an access mode. Full access works with files like you do, in the folder and beyond. Bounded workspace carries the same Read, List, Find, Search, Write and Edit tools fenced to that folder; with write tools on it can edit files there, not only add new ones. Each tool is a toggle, and whether the room can change files follows from what you enabled: with no write tools and no Bash the room says it is read-only. Bash is off by default and Full access only; when on, it asks before each command with a card that shows the command. Details: Workspace and Bash.

macOS note: if the workspace is in a protected folder (Documents, Desktop, Downloads, iCloud Drive), macOS may block directory listing for the terminal that launched Exxperts. Check from that same terminal:

ls ~/Documents | head

If that fails with Operation not permitted, grant your terminal access in System Settings → Privacy & Security → Files and Folders, or choose a non-protected folder.

Where your data lives

Path Purpose
~/.exxperts/app/ Product state: rooms (memory, events, threads), schedules, usage, artifacts, feature config.
~/.exxperts/agent/ Runtime state: provider credentials, model config, CLI sessions.

Each room is a self-contained folder under ~/.exxperts/app/personalized-agents/<room-id>/: its constitution, durable memory and archive, full event history with content fingerprints, and saved threads, all in plain files you can read.

Back up and move your rooms

Because a room is just a folder, backing it up or moving it to another machine is a copy:

  1. Finish the session in the room (use Remember if you want the latest conversation kept) and close it.
  2. Copy the room's folder, ~/.exxperts/app/personalized-agents/<room-id>/, to the same path on the other machine (or archive it: tar -czf my-room.tgz -C ~/.exxperts/app/personalized-agents <room-id>).
  3. On the other machine, install Exxperts and sign in to the same provider: the room's models and its open conversation's model come from it. Without it, pick other models in Room settings, Model and switch the open conversation too.
  4. If the room had a workspace, set it again in room settings; workspace grants reference absolute paths on the original machine and don't carry over. The workspace section warns when the saved folder isn't found on this machine.

The room appears on Home automatically; no import step. Copying all of ~/.exxperts/ backs up everything, credentials included, so treat that copy as sensitive.

Uninstall

Desktop app: quit it from the tray, then delete the app (macOS: drag it out of Applications; Windows: uninstall from Settings, or just delete the portable folder). Terminal install: stop the server with Ctrl-C; if you installed the package globally, npm uninstall -g @exxeta/exxperts-app. Your rooms and credentials stay in ~/.exxperts/; delete that folder only if you want to erase all local product state.

Going further

  • How Exxperts works: the architecture of rooms, prompt layers, and the approval-gated memory lifecycle.
  • Memory: the full memory model and who approves what.
  • Provider setup: all provider paths in detail, and which model a room uses.
  • MCP client support: connect MCP tool servers.
  • Web search: built in via DuckDuckGo, no setup; SearXNG is the reliable path for heavy use or networks where DuckDuckGo blocks automated queries.
  • CLI/TUI: exxperts cli (or ./scripts/exxperts-cli) opens the terminal experience, sharing the same rooms and credentials.