A web workspace over a folder of documents. It indexes the folder, including the text inside PDFs, office files, and images, and puts a chat assistant over it that answers from those files and links its sources, alongside search, browsing, and structured queries. It runs anywhere Node and GUFI run, with any OpenAI-compatible model. On the Parallel Works ACTIVATE platform it can also run workflows and agents on connected HPC and cloud systems.
On a Mac (Apple silicon, macOS 14 or later): curl -fsSL https://github.com/parallelworks/activate-studio/releases/download/macos/install.sh | bash installs the ACTIVATE Studio app in ~/Applications, which runs the Studio on your own folder with nothing else to install and no administrator rights, including on a managed Mac that does not allow LaunchAgents. The disk image on the macOS release page does the same: double-click the app in it and choose Install. To remove it, choose Uninstall ACTIVATE Studio… in the app menu: it lists what it removes (the app, and by default its indexes, settings and logs) and never your documents. See docs/MACOS.md.
On Linux (x86_64, glibc 2.28 or newer, so RHEL 8 and 9 and their rebuilds, Ubuntu 20.04 and later, Debian 11 and later): a per-user install with no administrator rights (activate-studio/install.sh from the unpacked archive) or an administrator's .deb (Ubuntu, Debian) or .rpm (RHEL, Rocky, Alma) puts the same Studio in its own window, where WebKitGTK is installed, and in your browser where it is not. See docs/LINUX-APP.md.
The macOS and Linux apps are built as the Go version: the Go server (server-go) with GUFI, tesseract and the embedding model, and no Node or Python. Installed copies of v1.188 and earlier move to it through their normal update (docs/UPDATES.md, "The Go version"). So is the container image on ghcr.io, built from the release's Linux app with deploy/app-go.def.
On Windows: the Linux app runs inside WSL2 (Windows Subsystem for Linux), in its own window through WSLg or in a Windows browser, and indexes Windows folders through /mnt/c. There is no native Windows build, and this setup has been tested only in containers so far. A browser can also open a Studio that runs on a Linux machine. See docs/WINDOWS.md.
On ACTIVATE: run the workflow in deploy/workflow.yaml on a connected resource and set its "Knowledge Base Directory" to your folder. It builds the index and opens the Studio as a session. The platform's models work with no setup.
On your own machine (Linux or macOS, with git, Node 26 and pnpm; on Ubuntu or Debian indexer/setup_gufi.sh installs the build tools and libraries it needs with apt, so it asks for sudo unless run as root; on macOS it uses Homebrew):
git clone https://github.com/parallelworks/activate-studio && cd activate-studio
pnpm install && pnpm build
indexer/setup_gufi.sh # once: builds the GUFI index engine (release 0.8.1)
export KB_ROOT=/path/to/your/folder
export OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY=<your key>
indexer/reindex.sh # indexes the folder (or later: Settings, Indexing, Libraries, Build index)
pnpm start # then open http://localhost:4080
Without KB_ROOT, it opens a small sample folder. Any OpenAI-compatible endpoint works in place of OpenAI's, including a site's AI portal; Settings, Model access takes the headers, model names and query string a portal may need, and its Test says whether the model calls tools, which chat needs to search your files. A clone on a Mac is covered in docs/MACOS.md too.
- Chat answers from your files and links each source. Type @ to hand it a file from the library, set how long the model reasons with Effort, ask it to save a report or table as a PDF, Word or Excel file (with images from the library in a PDF or Word report; justified black text with no divider lines, and a paragraph's leading label in italic with a colon; a centered, unnumbered cover page, left-aligned text, landscape pages, a font, size, margins, line spacing, page breaks or a header and footer line when you ask for them; a check of the writing that the assistant weighs before it hands the report over; a report asked for in several formats is written once as Markdown and the others are made from it, and a later change is an edit to that file, with the PDF and Word documents made again), and have it move, rename, copy or delete library files (a delete waits for your approval). A chat goes into the library only when you save it, with Save or by asking the assistant.
- Search finds file names, the words inside files, and, where it is on, meaning: passages that say the same thing in other words. It also reads the text and vectors GUFI's own extraction writes, in GUFI's common external database schema, in an index Studio did not build. Each library's search stops at a time limit, 20 seconds unless set longer in Settings for very large indexes, and a running search can be stopped; either way its query ends on the library's host too.
- Library browses and views documents, CSV tables, images, PDFs, office files, and 3D models, takes files and whole folders with their structure, uploads into a folder and downloads a file or a whole folder as a zip from its right-click menu, and describes the folder you select: its size, contents, and labels. A library can name a second host over ssh that has its files, for an index whose own host does not. A folder on an SFTP or ssh host, a cluster or an rclone remote can be added as a copy that Studio keeps in step on this computer and indexes, which makes a host that allows SFTP only, such as an upload drop, searchable. A bucket of any S3 compatible store, on AWS or on premises, can be indexed through rclone from its listing alone, each object read only when opened (Preview). Libraries can be exported as a library list file that others import into their own Studio, from the Library's Add menu, in setup, or in Settings, so an administrator shares one setup, including an index built as root, and each person connects as themselves and sees what their own permissions allow. Where people sign in to a Studio beside a cluster, each person can have a space of their own there, written and indexed as their own account, and share folders in it with other accounts or groups through POSIX ACLs (Preview).
- Transfers copies, moves and syncs files between libraries, folders on this computer, your ACTIVATE clusters, saved ssh locations (including accounts that allow SFTP only), the remotes of your installed rclone (used with its existing configuration, which Studio never changes; sign-in off only) and CONDUIT, with a plan to confirm before each one starts and a list of every transfer and its progress.
- Query answers structured questions about the files, such as the largest or newest, or runs read-only SQL. Query and search results export to CSV.
- Stats maps each library, here or on another system: its folders by size, and its files by what they say.
- Workflows, on ACTIVATE, runs chosen platform workflows from their own forms, and opens the sessions they start.
- pw code answers the chat under ACTIVATE by default: the ACTIVATE agent harness, in a pw code session of the person chatting, which uses the Studio's own tools through its MCP server (search and statistics from the index, reading and writing library files, labels, platform workflows; the Studio checks the session has them before each message, and the Studio assistant answers when it cannot), works in files, and runs the commands they approve, in the chat or in PW Code on the web, where the same session opens. The Studio assistant answers elsewhere, and either can be chosen for each chat.
- pw code from the chat: ask the assistant to have pw code do a piece of work, such as a report built with code. The agent works in a library folder when it runs where the library is, and the assistant waits for it, then indexes and links what it wrote. It also finds your existing sessions by name or topic, follows them, and gives them direction.
- Code, on ACTIVATE, lists your pw code sessions across the platform's machines, shows each one's conversation, and opens it in ACTIVATE.
- Agents take the parts of a larger request in parallel; you can watch them, approve what they ask to do, and steer them.
- Sign-in, on a Studio several people share: through the ACTIVATE session proxy, or through ACTIVATE or any other OpenID Connect provider (
docs/DEPLOY.md). Each person can also sign in with ACTIVATE under Settings, Model access, which the Studio renews and uses as their own credential for models, the platform, and My library, a folder of theirs on the Studio's cluster (docs/MULTI-USER.md). - Other tools, such as pw code, can search and read the same knowledge base over MCP (search, the text the index holds, and the original files) or an OpenAI-compatible endpoint.
Each library the Studio builds has an index depth, set on a scale in Settings, Indexing, Libraries, in setup, and when the library is added. Each stop adds to the one before and takes longer to index:
| Depth | What the index holds |
|---|---|
| Names | Names, sizes, dates and owners of every file and folder. |
| Text | The words inside files: text, code, PDFs and Office documents. |
| Text + OCR | Text in images and scanned PDF pages, read by tesseract. |
| Meaning on documents | Search by meaning over the first four passages of each PDF, Office, text, Markdown and image file. The default for the main folder and the libraries the Studio builds, here or on a remote system, computed last, after names and text are searchable. |
| Meaning on all files | Search by meaning over up to twelve passages of every file with text. |
Many folders (code, data, simulation output) need no more than Text. Settings, Indexing, Building also sets the speed of search by meaning: Standard embeds the first 256 tokens of each passage, and Faster the first 128, in well under half the time with slightly lower ranking. Embeddings come from all-MiniLM-L6-v2 through ONNX Runtime (int8), which the macOS app and the container carry; a clone gets it from indexer/setup_gufi.sh, or python3 indexer/fetch_embed.py --deps indexer/.deps --model index/models/minilm-l6. A build on a remote system embeds with the same model, which the first build there sends with its packages for the Python there. An index connected as it is stays as it was built.
The in-app Help is the user guide: docs/HELP.md, with the details in docs/REFERENCE.md. Its What's new page shows CHANGELOG.md.
The same documents, grouped by what you want to do, are listed in docs/README.md.
| Document | Covers |
|---|---|
docs/HELP.md |
the user guide, shown in the app and read by the assistant |
docs/REFERENCE.md |
the details behind the user guide, part by part |
docs/DEPLOY.md |
running it on ACTIVATE, in a container, or as a plain server, and connecting models |
docs/CUSTOMIZATION.md |
settings, branding, identity, and the assistant's tools |
docs/LIBRARIES.md |
several indexes at once, building an index of a folder here or on a remote system over ssh or pw ssh, library lists to export and import, the Library's Details card, and which parts of the app appear |
docs/WORKFLOWS.md |
the Workflows tab |
docs/AGENTS.md |
delegated agents |
docs/ACCESS-CONTROL.md |
who can find what: GUFI and the file system's permissions, deploying for user and group access, and an administrator's index |
docs/MULTI-USER.md |
several people on one deployment |
docs/MACOS.md |
the macOS app, and running from a clone on macOS |
docs/UPDATES.md |
update channels (Stable and Preview), installing another version, the state snapshot and format, and what the Go version must keep |
docs/LINUX-APP.md |
the Linux app: per-user install, .deb and .rpm, requirements, update and uninstall, the install layout |
docs/GUFI-MACOS.md |
GUFI built for macOS 14 and later: the published archive, building and checking it |
docs/WINDOWS.md |
the Linux app on Windows through WSL2: install, window or browser, Windows folders under /mnt/c, labels and sync there |
docs/ARCHITECTURE.md |
how the index, retrieval, and server work |
- GUFI (Los Alamos National Laboratory): the metadata, full-text, and vector index.
- sqlite-vec and sqlite-lembed: vector storage, and embedding with a local model where ONNX Runtime is not installed.
- ONNX Runtime, tokenizers and all-MiniLM-L6-v2: embeddings for search by meaning.
- @parallelworks/ui: the chat interface, the platform's workflow forms and run graph, the log viewer and code editor, and the controls throughout (buttons, fields, menus, dialogs, tabs, tables).
- Streamdown, three.js, occt-import-js, Tesseract, Fastify, React, and Vite.
Contributions are welcome. CONTRIBUTING.md covers setup, the repository layout, tests, pull requests, and releases. Report security issues through SECURITY.md.