User guide

The 0.1.29 desktop workspace

Version 0.1.29 updates the composer, device identity controls and result display. The homepage uses synthetic demo content to show this version’s interface; see the download page for packages and verification details.

• Choose the folder, model, approval mode, and reasoning level from the composer. The compact reasoning menu shows options supported by the selected model. Auto uses its default; an unavailable previous choice prompts you to confirm.
• A separate edit control sits beside the device name. Arrows and values beside Model connections show local rates, with full explanations in the activity panel. These figures do not aggregate model usage on other devices.
• Request a stop from the composer during execution and wait for confirmation. Once confirmed, send new instructions to continue the conversation. A new round cannot start while the stop is unconfirmed.
• After success, the result is expanded first, with planning and execution details available on demand. Icon controls let you copy or quote a reply and add follow-up instructions. Conversation history retains search, drafts, pinning, and project groups.

1 Install and open Rivloom

Visit the Download app page for the Windows x64 installer. Check the version, file size, and SHA-256 against the details on that page. Run the installer, follow the installation wizard, then open Rivloom.

The current installer is unsigned, so Windows may display a source or reputation warning. Check the file source and verification details before deciding whether to proceed. Runtime components are bundled; you still need any tools required by your project and network access to your model service.

Closing the window and quitting

From 0.1.18, closing the window keeps Rivloom in the system tray while tasks continue in the background. Choose “Got it” in the first notice to remember your choice. Click the tray icon to return to the workspace. To quit completely, right-click the tray icon and choose “Quit Rivloom”; the app stops execution and exits directly.

Update an installed version

In 0.1.22, the current version appears beside the Rivloom logo at the bottom left. A separate information icon on the right opens About Rivloom. Common sidebar actions use icons with names shown on hover and keyboard access. More contains the recycle bin, connection diagnostics, keyboard and input options, and interface language.

In About Rivloom, choose Check for updates, then Download and install. Starting with 0.1.7, the update dialog closes automatically after download verification. Progress then shows task checks, service shutdown, file backup, and installation startup. Rivloom reopens when installation finishes.

0.1.26 reduces the scope of Windows in-app update backups. It skips cache and temporary files at the roots of the shared engine and each account's engine. Plugin dependencies are omitted only after verification confirms they can be rebuilt offline from the installer. Custom, modified or unverifiable dependencies and their generated markers are retained together. Conversations, accounts, settings, attachments and identically named folders elsewhere are still backed up.

An upgrade from an older version to 0.1.26 still uses that older version's backup logic. This optimization applies to later in-app updates initiated after 0.1.26 is installed. It does not delete current application data or provide automatic restoration or rollback between versions.

Starting with 0.1.9, a successful launch into the updated workspace automatically removes all obsolete upgrade backups, including copies left by earlier versions and interrupted backups. Backups are retained if the upgrade or workspace startup fails. Cleanup retries automatically when a file is temporarily in use. Current conversations, model settings, device identity and project files are preserved.

Upgrading from 0.1.5 or 0.1.6 to 0.1.7 still uses the older updater, so you may need to close its update dialog once. The new flow applies to subsequent updates after 0.1.7 is installed. Version 0.1.4 still requires a manual installation.

2 Configure a model

In 0.1.23, Model connections at the bottom left and Manage connections in the model menu open the same settings at any time. Setup also appears when no model is available on first use. Save multiple named connections with an endpoint, credentials and model ID, and adjust the API protocol, context size and maximum output in advanced settings.

Save separate connections for your company network, home or other workplaces, then choose one for your current environment. Saving settings does not call a model. Connection tests need separate confirmation and send one minimal request to the selected saved model, which may use service quota.

Use this connection and Save and use change the default model for new tasks. Existing tasks and unsent drafts keep their own selections. An unavailable default prompts you to check it; after switching networks, review the model selected for your current conversation. You can defer first-time setup and reopen it from the sidebar later.

0.1.25 fixes connection settings staying locked after a task ends: the page refreshes its status and restores editing. A temporarily unavailable model remains selected. Confirm the connection test again when the model or its availability changes. Saving settings, changing the default and refreshing afterward each show their own result.

Manage existing provider accounts and OAuth connections through Provider accounts and more settings. Use Execution and folders to configure the work this device can accept. Tasks use the executing device’s account quota, and model calls may be billed.

From 0.1.17, Model access offers Account sign-in, API Key and Custom service. Add multiple accounts for one provider, name each account, and save its API key or use an OAuth method supported by the provider. Existing accounts can be renamed. OpenCode Go uses API keys; connect and choose each plan account separately, without pooled quota or automatic rotation.

In Custom service, enter a name, endpoint and model IDs, choose Chat Completions or Responses, and supply an API key or select keyless access. After saving, add another service or switch between connected services to edit or remove them. Defaults affect future selections; connection tests require separate confirmation and may use service quota.

From 0.1.17, the model picker groups models by provider and account name, shows model counts, and supports expanding, collapsing and search. Tasks and resumed sessions keep their original account. Context sizes and image badges reflect the engine catalog; actual capabilities depend on the account and model response.

New installations of 0.1.19 no longer select an OpenCode Zen free model automatically. Connect your own account and choose an available model. Accounts you explicitly connected remain available.

View Node activity from the sidebar

Local model rates appear on the same row to the right of Model connections. Version 0.1.29 uses compact arrows, values and units. The left control opens connection settings; the right control opens activity details with running, generating, tool, waiting and recent failure states by connection. Narrow sidebars prioritize output; input rates and full status remain available in the panel.

Rates cover conversations executed on this Node, including received delegations. Tasks running on other devices do not contribute to local rates. The activity control stays visible when idle, waiting for samples or temporarily unavailable, and explains its current state.

• In avg is the average rate of newly confirmed input-token usage over the last 60 seconds, not the model's prefill speed.
• Out estimates the rate from text and reasoning increments actually received over the last 3 seconds, retaining the ≈ marker. Tool output is excluded. After a short reply ends, its samples expire within the original 3-second window; they do not mean the model is still generating.
• Input and output are shown independently. Missing, stale or incomplete totals display — rather than zero. Valid details for individual connections remain available in the panel. Monitoring makes no extra model calls and is not a billing or quota view.

Library shows actual operations such as refreshing the catalog, reading knowledge, saving memories and organizing categories, even after you leave the Library page. Expand partial failures or failures to see the reason and dismiss the notice; dismissing does not retry the operation. Sharing only changes who may read the content. Other devices fetch it on demand, so it does not mean every device is synchronized.

0.1.25 fixes two activity edge cases: dismissing an old failure notice no longer dismisses a newer failure of the same operation, and valid usage received after a task ends can complete its input statistics within the retention window. Late events do not bring expired executions back into view.

Project files shows reads and saves across page changes, with brief success feedback and reasons for failures. Inbox bounces once only when new items increase its count. Devices indicates changes from current, valid connection and execution states. Activity stays quiet when idle, pauses animation while the window is hidden and respects the system's reduced-motion setting.

3 Choose a working folder

Select New conversation, choose or add an ordinary folder below the input area, then select a model. Start with a test project that contains no sensitive information. Git is not required.

In 0.1.21, attachments sit on the upper-left edge of the composer and @ device selection on the upper-right. Both stay outside the text area and show an attachment count or device name when used. You can clear the device selection or drag in files. Choose the folder, model, approval mode and completion requirements below the input.

Preview office files

From 0.1.23, click the name of a ready attachment, task input or result to preview PDF, Word (DOCX) and Excel (XLSX) files in the app. Project files lets you browse registered local projects and search file names. Fetch remote files to this device first.

• PDF supports page navigation, zoom, text selection and search within the current page. Scanned pages can be viewed; this version does not provide OCR.
• DOCX displays text, headings, lists, tables and some embedded images. Its reading layout may differ from Word.
• XLSX supports switching sheets, paginated viewing and search within the current batch. It displays saved formula results without recalculating formulas, running macros or reading external links. CSV and TSV can also be viewed as tables.

Select text or cells and choose Quote in chat to keep the file name and page or sheet information in a quote card. Previews indicate truncated content and format limits. DOC, XLS and PPT do not yet have built-in previews; open them with a system app.

Fully loaded UTF-8 TXT and Markdown files up to 256 KiB support simple editing. Saving a project file checks for external changes and keeps your draft if there is a conflict. Historical attachments and results are saved as new copies. Office files are primarily for preview; use their native apps for complex formatting and editing.

0.1.25 fixes search highlighting for special characters and duplicate match counts in Markdown code blocks, and removes ineffective text-pagination buttons from PDF pages and full Word layout previews. Quoting is disabled while editing. Entering or leaving edit mode clears the previous selection, and unsaved changes still need to be handled. Other file actions no longer clear a preview read error or its retry control.

Preview components come with the package and do not depend on a public Office viewing service. A computer without public internet access can connect to a reachable internal model service. Tasks still depend on the model’s tool-calling abilities and required project tools. Public update checks continue as before; an internal update source is not yet available.

4 Choose an approval mode

Open Conversation settings, choose an AI approval mode, and add acceptance criteria if needed. For your first task, choose Request approval to review edits, commands, and network requests before continuing. See the security guide.

5 Describe your task and send it

Describe the goal, what may be changed, and how to check the result. The task enters the execution queue and starts when ready. Here is a request to try in a test project:

Starting with 0.1.11, your messages show their body directly, without a separate You / Copy row. A small copy icon appears when you hover over a message or task result and hides when you move away. It also appears on keyboard focus and remains available on touch devices. Drag to select text and press Ctrl+C; the selection has a clear highlight. Click the icon to copy the full content with its line breaks and indentation.

Workflow conversations retain each round’s request, response, results and files. From 0.1.29, a new planning or execution failure keeps its history and allows the next queued message to proceed in order. Manual pauses and context preparation failures still need explicit handling. Once the previous round has safely ended, a new request continues a stopped or failed conversation. An unconfirmed stop remains pending and cannot force a new round; answer model questions in the current round’s question card.

Unsent text, the target device, folder and model options, and completed uploads are saved automatically and restored when you switch conversations, refresh or restart. A draft clears only after sending succeeds. Files whose uploads were incomplete when you closed the app must be selected again; the app will show a clear message.

Responses and results support Markdown headings, lists, tables and syntax highlighting. Code blocks have separate copy buttons, and copying a whole message preserves its Markdown source. Paste screenshots with Ctrl+V, drag in files or select attachments. Once uploaded, supported office documents, images, text, audio and video can be previewed in the app.

Text previews show the first 256 KiB; download the file to read its full content. Some audio or video codecs may require a system app, and unsupported formats show a notice. HTML and SVG content is displayed as plain text.

6 Review and confirm the result

Handle approvals and questions in the conversation. Successful execution is marked complete automatically. Then open the actual files, check the contents and relevant tests, and add follow-up requests if needed. The engine’s diff may not include every change; you still need to verify the files yourself.

Right-click a delivered file or select More to open its folder, open it with the default app, save a copy or copy its local path. The preview toolbar in 0.1.23 also offers installed Chrome, Edge or another system app for compatible formats. Incomplete transfers show their status; file actions become available once transfer completes.

Starting with 0.1.13, responses, deliverable files and execution details appear separately. Expand the details when needed; completed portions remain visible after failure or a stop. Messages, rounds and panels use less space.

When the current round fails, click Retry this step on the failed step. Once the previous execution is confirmed to have ended, Rivloom retries that step and continues the necessary following steps, preserving completed steps, earlier attempts and files. If execution status cannot be confirmed, it explains why. The message queue keeps its existing pause state.

In 0.1.13, remote results initially show their source device, path and file details; files stay on the device that created them. Click Fetch to this device for a local copy, then preview, open or save it after transfer completes. Materials needed by later steps are prepared automatically. A follow-up conversation that only refers to earlier results does not automatically download all previous files. On-demand retrieval and remote step retries require both devices to update; older nodes keep their existing file return behavior.

Move between pending items and conversations

Open Inbox at the bottom left to see conversations that need attention. From 0.1.23, selecting an item opens its conversation, expands its folder in the sidebar, scrolls to it and highlights it. Transitions respect your system’s reduced-motion preference.

Back to inbox in the conversation returns to the list with its category and scroll position preserved. Loading failures show an error and a retry action; unavailable counts are not shown as zero.

How history supports follow-ups and handoffs

A conversation retains goals, constraints, decisions and progress with source versions. For a follow-up or node handoff, the worker uses that state and searches or reads original history in pages as needed. Nodes supporting this feature no longer attach the accumulated conversation file by default; older nodes keep their compatibility path.

Each history read returns up to 32 KiB, including the text and associated information. This is a page transfer budget, not the model's context window, total history capacity or input limit. Longer history can be read in further pages. State new goals and constraints clearly; model inferences do not automatically become your authorization.

Execution shows reasoning and tool activity supplied by the model. After context compaction, Rivloom restores the current workflow and permission rules. In 0.1.21, quotes appear as separate cards that you can expand or remove, leaving the text input clear. Review the quote and your new request before sending.

Remote history reads are limited to the currently trusted target node that accepted this execution. New reads are rejected when execution ends or access is revoked. The participating nodes must support this capability.

Review and confirm conversation context

Open Conversation context at the top of the conversation. Goals and memory shows the current goal and sourced constraints and decisions, separating user confirmations from model inferences. Read the original source, confirm or revise an entry, withdraw it and inspect its history. Current requirements take precedence over historical references.

Read records shows successfully processed history pages and local Wiki reads, not proof that the model understood them. Execution and compaction shows rule sources, version checks and restoration records for local execution, rather than full model input or token counts. View knowledge and rule records for remote execution on the executing device.

For an ordinary local conversation awaiting an answer or interrupted, add requirements in the same conversation. The app confirms that the old execution has stopped before continuing the original session. After a normal exit and reopening, you still need to continue explicitly. Workflow conversations retain their message queue; restarting does not automatically replay operations that already occurred.

Hand work to another device

“This device” in a task means the device that submitted it. The model selects a target from the task’s meaning, and scheduling respects explicit device constraints. Planning and execution devices are shown separately. Upgrading does not force-unlock or rerun existing records whose remote stop remains unconfirmed.

In 0.1.22, the queue and devices panel starts collapsed when idle and opens automatically while execution items remain unfinished. You can also open or close it manually; that choice takes priority for the current interface session. The collapsed panel shows the unfinished item count. Opening or closing it does not pause or stop tasks.

From 0.1.18, check LAN connectivity in “Devices and models” or “Connection diagnostics”. If communication rules are missing, choose “Allow LAN connections and retest” and complete Windows administrator authorization. Public networks require explicit consent to trust the current LAN. Rules are limited to the local subnet; repair rediscovers devices without automatically confirming pairing.

Step status distinguishes queued work, input preparation, unmet dependencies and execution awaiting confirmation, with details about device connectivity, configuration and tool reports. Queue receipts identify held, admitted and rejected work. Copy a diagnostic summary that omits task text, device names and paths. Refreshing reads status without dispatching the task again.

In 0.1.19, use Remove from queue for waiting or deferred items in the local execution queue. For a failed task, choose End and remove from queue. The app completes this only after confirming the engine has stopped, and keeps the history. This does not undo file changes already made.

On both devices, open Devices & models → Nodes & Brain, check pairing details, and confirm trust. Configure projects, models, and execution on the receiving device. Then use @ in a new conversation to choose a preferred device, or @@ to lock one. Follow steps, queues, handoffs, and results in the original conversation.

Tasks from paired devices are received automatically and may consume the receiving device's model quota. Pair only with trusted devices. Device pairing and AI operation approval are separate confirmations.

Set up a Linux worker over SSH

The Linux command-line app targets headless workers on a local network. Check the Linux download section for released architectures and packages. The steps below apply to a verified, extracted archive.

The Linux x64 package in 0.1.19 requires kernel 4.18 or newer, glibc 2.30 or newer, and libstdc++.so.6 providing GLIBCXX_3.4.25 or newer symbol versions. Run uname -r and getconf GNU_LIBC_VERSION to check the kernel and glibc. Alpine/musl and 32-bit systems are unsupported; ARM64 is not released yet. Meeting these requirements does not mean every older distribution has been tested.

1 Check your architecture, initialize and start

Connect over SSH as a regular Linux user and check the architecture with uname -m. Choose x64 for x86_64. aarch64 needs an ARM64 package; installation is unavailable until one appears on the download page. Follow the download commands in an empty directory to verify SHA-256 and extract. Runtime components are included; install project tools such as Git and compilers separately.

uname -m
./rivloom/bin/rivloom init --name linux-worker
./rivloom/bin/rivloom serve

serve runs in the foreground. Keep it open and use a second SSH terminal for the management commands below, from the extraction directory. Do not run tasks as root. Data defaults to $XDG_DATA_HOME/rivloom, or ~/.local/share/rivloom when unset. Always use the same user and data directory for this node.

2 Pair with a trusted desktop

./rivloom/bin/rivloom status
./rivloom/bin/rivloom nodes
./rivloom/bin/rivloom pair request NODE_ID
./rivloom/bin/rivloom pair list
./rivloom/bin/rivloom pair confirm PAIRING_ID --code CODE

Replace NODE_ID, PAIRING_ID and CODE with the current values. Compare the pairing code in Windows under Devices & Models → Nodes & Brains and in the Linux list, then confirm on both sides. Starting the service does not automatically trust other devices. If discovery fails, check that both devices are on the same trusted network and that their firewalls allow the required traffic.

3 Configure a project, model and execution policy

./rivloom/bin/rivloom projects add /absolute/project/path --name work --confirm
./rivloom/bin/rivloom models list
./rivloom/bin/rivloom execution enable --project PROJECT_ID --model PROVIDER/MODEL --approval ask --confirm

Replace the absolute project path, project ID and model ID. Configure model accounts separately on the Linux device. The providers key PROVIDER --stdin --confirm command reads a key from standard input; keep real keys out of arguments, scripts and chats. Model requests use the worker account and may incur charges.

Enabling execution requires explicit confirmation. Start with ask approval mode, use @@ in a Windows conversation to lock execution to this Linux node, and select its project. Send a small test task first. Tasks access files with the current Linux user permissions; this is not an operating-system sandbox.

./rivloom/bin/rivloom queue list
./rivloom/bin/rivloom pending
./rivloom/bin/rivloom approve TASK_ID REQUEST_ID once
./rivloom/bin/rivloom approve TASK_ID REQUEST_ID reject

pending lists approvals and questions waiting for a response. Review the actual request, then choose either once or reject; do not run both decisions shown in the example. To answer a question, use respond TASK_ID REQUEST_ID --stdin and provide the request-specific JSON answer. Use --help for command details.

4 Run persistently with systemd

Stop the foreground serve process first and keep the program in a permanent location. service only prints a user systemd unit; it does not install or start it. Review the executable and data paths before saving the unit and starting it:

mkdir -p "$HOME/.config/systemd/user"
./rivloom/bin/rivloom service --executable "$(pwd)/rivloom/bin/rivloom" > "$HOME/.config/systemd/user/rivloom.service"
systemctl --user daemon-reload
systemctl --user enable --now rivloom
systemctl --user status rivloom
journalctl --user -u rivloom

For operation after SSH logout or at boot, ask the device administrator to enable lingering for this user according to local policy. Before updating, pause incoming work, handle running tasks and stop the service. Preserve the data directory, then verify and replace the program. Automatic updates are not available for Linux.

Shared Skills and progressive Wiki memory

Starting with 0.1.15, Skills & Memory in the sidebar brings reusable skills and memory together. Only the local workspace creator can manage registrations, instructions and sharing.

Skills: register once, read as needed

1. Under My Node, add a folder containing SKILL.md directly, with name and description in its frontmatter. Keep scripts and references in that folder.
2. Skills are local-only by default. In Manage sharing, choose the Brains allowed to read them; the list shows the current sharing scope.
3. Switch to a Brain catalog to find shared content. The agent searches names and descriptions, then reads SKILL.md, the file list and any supporting files it needs. Registering, sharing and reading do not run scripts.

A Brain coordinates paired devices and relays shared knowledge. If A and B connect to the same Brain, B can discover and read skills that A shares with it, without pairing directly with A. Sharing is not forwarded automatically across Brains. Any later script execution follows the task approval mode; dependencies are not installed automatically.

Wiki: start with summaries, then read relevant entries

Each memory entry has a name, summary, category path, body and scope. Organize entries in a hierarchy such as Project / Website / Conventions, scope them to one working folder or all local folders, edit them and view their history.

Progressive means searching categories and summaries first, then reading the relevant entries, instead of loading the entire Wiki into the task context. Regular tasks can save facts with sources; read-only planning cannot write memory. When approval is required, a denied request saves nothing.

Wiki memory stays local by default. Choose a Brain manually when you want to share. Share entries in this category applies only to existing entries shown under the current category and filters; new entries remain private.

Save confirmed knowledge as project memory

From 0.1.20, the local owner can use Save to project memory in Conversation context for an active, user-confirmed entry in a workflow conversation linked to a project. This keeps the original source and version, and can create a memory or replace one already saved by this conversation. Model inferences do not automatically become long-term memory.

Project memory applies to its project, with sharing controlled by knowledge-library settings. Conversation entries and project memories are managed separately. Withdrawing a project memory blocks future knowledge reads while preserving old versions and records of earlier reads. Wiki and Skill content is read in version-pinned pages of up to 32 KiB, with the source online and authorization maintained. History-read authorization does not open another node's private Wiki.

Versions and instructions have explicit scopes

Each task pins an entry to the version it first reads. If the source changes, that task will not mix versions; a new task reads the current source version without silently falling back to an old cache. The source device must be online and access must still be authorized; the Nodes and Brain involved must support this capability.

Local main instructions apply only to tasks started by the local workspace creator. Working folder instructions use AGENTS.md, falling back to agent.md if absent. Remote tasks can use knowledge tools only to read content shared with their Brain and the instructions for their execution folder.

Revoking sharing blocks future reads, but cannot remotely recall content already delivered. Shared content may also enter model context. Review its source before use and keep credentials and private information out.

What organization does today

Organization runs after startup and memory changes, with changes batched together; you can also select Organize memory manually. It generates category indexes and marks entries with identical bodies in the same scope, preserving the originals and history. It makes no extra model calls and does not perform independent background AI rewriting or merge similar memories.

Search conversation content

Starting with 0.1.14, Search conversations finds historical requests, answers, earlier step attempts and pending messages. Results show matching excerpts; click to open the content and use previous/next to move between matches. Clear the query to leave search navigation. Search respects your visible scope and recycle-bin state, does not scan project files, and does not send drafts or start tasks.

Organize conversation history and the recycle bin

In 0.1.27, conversation history uses a compact graphite list. Desktop rows default to 30px with 14px titles, fitting more conversations into the same height. Important states such as running, awaiting confirmation and incomplete remain on the right; other conversations show their update time. Full-title tooltips appear only when a title is truncated.

More actions appear on hover or keyboard focus without moving the title. Touch rows are at least 44px tall and keep their action button visible. Esc returns focus from a menu to its trigger; the history drawer on narrow screens supports Tab cycling and Esc to close. The sidebar starts at 340px, respects a previously saved width and can still be resized by dragging.

Starting with 0.1.10, right-click a conversation to rename it, pin or unpin it, or move it to the recycle bin. Names and pins are saved for the current user. Pinned conversations appear first within their directory, and renaming leaves the original task instructions unchanged. A More button appears on hover and stays visible on touch devices. Use Shift+F10 to open the menu, arrow keys to navigate, Enter to act and Esc to close.

Directory aliases have been supported since 0.1.8. Since 0.1.10, right-click a directory or open More to set its alias, copy its full path or open the local folder. Clear an alias to restore the folder name. Aliases are saved per local user and persist after restarting. The real path remains available to view and search; aliases do not rename the folder or change its name on other devices.

Conversation history is grouped by working directory. Click a directory to collapse it, or search directories and conversation content. Choose Move to recycle bin from More or the context menu and confirm. Work that is running, queued or has an unconfirmed state must first stop and be confirmed. Search navigation, unsent drafts, pinning and returning to attention items remain available.

In the recycle bin, restore the original conversation, permanently delete an individual entry, or confirm emptying the bin. Entries are kept for three calendar months from when they were moved there. Expired entries are removed at startup and every hour while the app runs. Deleting a conversation does not delete actual project files.

From 0.1.20, permanent deletion also cleans up local engine sessions with a verified association. If a session is active, shared by another retained conversation, or its engine is unavailable, the cleanup record remains with an option to retry. Project originals, remote copies and separately saved project memories are preserved. Database files are not automatically compacted.