GitHubGet StoixGitHub
DocumentationOverview

Documentation · Public preview

From install
to first project.

A practical guide to installing Stoix, connecting Hermes Agent, verifying the local runtime, and understanding the boundaries of the current public preview.

Install Stoix GitHub
01 Check requirements02 Run installer03 Complete Hermes setup04 Run doctor

Documentation checked against Stoix repository commit 9650f07 · 16 August 2026

01

Before you begin

Requirements

The bootstrap installer runs in your user account. It needs network access, a modern browser, and the standard shell tools listed for your platform.

PlatformProcessorsInstaller requirementsPrivilege
macOSStoix: Apple silicon or Intel; official Hermes: Apple siliconcurl, tar, SHA-256 tool, bash for automatic Hermes setupCurrent user
WindowsARM64, x64PowerShell and standard Windows archive/hash toolsCurrent user
LinuxARM64, x64curl, tar, SHA-256 tool, bash for automatic Hermes setupCurrent user
Public-preview status

No GitHub Release is published yet, so the installer currently uses its slower source-build fallback. Clean-machine validation across every platform and final signing/notarization decisions remain release-owner work.

02

Recommended setup

Install Stoix

Choose the path that matches your machine. Keep the direct Stoix route when Hermes already works; use the verified two-stage route when you are starting without Hermes.

Hermes already installed

Copy the Stoix command for your operating system. The installer preserves your Hermes installation and configures Stoix to use its local API.

Terminal
$ curl -fsSL https://raw.githubusercontent.com/finxray/hermes-ui/master/install.sh | sh

macOS 12 or later · Apple silicon or Intel · installs in your user account. No preinstalled Node.js required.

Starting without Hermes

Install Hermes Agent from its official channel first, complete the provider wizard, and confirm hermes doctor is clean. Then install Stoix. Native Windows is supported; WSL2 is optional, not required.

01Install Hermes Agent
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
02Reload your shell
source ~/.zshrc
03Verify Hermes
hermes doctor
04Install Stoix
curl -fsSL https://raw.githubusercontent.com/finxray/hermes-ui/master/install.sh | sh

Officially supported on Apple silicon. Finish the Hermes provider setup, then verify it before installing Stoix. Stoix configures its local Hermes connection; provider credentials stay in Hermes.

Official Hermes installation guide
Official Hermes installation Hermes platform support

What happens after you press Enter

1
Detects your platform

Selects macOS, Windows, or Linux and the matching ARM64 or x64 target.

2
Tries the latest compatible release

A published archive is downloaded with its adjacent SHA-256 file and verified before extraction.

3
Uses the source fallback when needed

When no compatible release exists, Stoix downloads the current public source branch and builds it with a temporary Node.js runtime verified against Node’s published checksum list.

4
Installs without replacing your data

The package is staged in a versioned per-user directory before the stable launcher is switched.

5
Connects Hermes

The installer can find or install official Hermes, enable its loopback API, create or reuse a private key, and start the local services.

6
Opens Stoix

The browser opens when the local runtime is ready. Provider authentication remains your action.

Install locations

macOS
Application directoryApplication entryCommand
Windows
Application directory

A Start menu entry is created for the current user. Open a new terminal before using stoix.

Linux
Application directoryCommand

The desktop entry uses the user applications directory.

Inspect before running

If you prefer not to pipe a remote script directly into a shell, download it, inspect it, then execute the local file.

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/finxray/hermes-ui/master/install.sh -o install-stoix.sh
less install-stoix.sh
sh install-stoix.sh
Windows PowerShell
irm https://raw.githubusercontent.com/finxray/hermes-ui/master/install.ps1 -OutFile install-stoix.ps1
Get-Content .\install-stoix.ps1
& .\install-stoix.ps1

Advanced installer options

Advanced options must be passed to a local installer file. These examples skip automatic Hermes setup and finish without launching Stoix.

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/finxray/hermes-ui/master/install.sh -o install-stoix.sh
sh install-stoix.sh --skip-hermes --no-launch
Windows PowerShell
irm https://raw.githubusercontent.com/finxray/hermes-ui/master/install.ps1 -OutFile install-stoix.ps1
.\install-stoix.ps1 -SkipHermes -NoLaunch

macOS / Linux flags

Install a local release archive and verify an adjacent checksum when present.

Install a specific published version.

Override the per-user application directory.

Override the user command directory.

Override the private configuration directory.

Do not install or configure Hermes Agent.

Finish without starting Stoix.

Do not change PATH or create an application entry.

Force the source-build path.

Show installer usage without making changes.

Windows parameters

Install a local release archive and verify an adjacent checksum when present.

Install a specific published version.

Override the per-user application directory.

Override the user command directory.

Override the private configuration directory.

Do not install or configure Hermes Agent.

Finish without starting Stoix.

Do not change PATH or create a Start menu entry.

Force the source-build path.

Read install.sh Read install.ps1
03

Get oriented

First launch

1
Keep the terminal open

The source-build fallback can take several minutes while it prepares a temporary runtime and production package.

2
Complete provider setup

Hermes may ask you to sign in or provide your own model-provider credential. Stoix cannot accept credentials for you.

3
Create your first project

Projects organize related sessions, attachments, and visual workspace state.

4
Launch later with stoix

Use a new terminal, Start menu, or application launcher. Packaged Stoix opens on 127.0.0.1:3210.

04

Verify

Run a health check

Doctor reports package readiness, the active configuration path, and Hermes reachability without printing secrets.

Terminal or PowerShell
stoix --doctor
Packaged Stoix
Hermes API
Hermes Dashboard
Source development

If Hermes is unavailable, run hermes doctor and then hermes gateway start.

05

Configure

Local settings

Private runtime settings live outside immutable application versions. Keep the configuration file private.

SettingPurposeClass
Hermes endpoint. Defaults to http://127.0.0.1:8642.Defaulted
Hermes credential read only by the Stoix server boundary.Private
Optional local Hermes Dashboard endpoint.Optional
Optional private Dashboard session credential.Private
Optional default model identifier for the workspace.Optional
Enables the real Hermes adapter. Defaults to true.Defaulted
Optional approved HTTPS update-manifest override in production.Optional
Packaged Stoix port. Defaults to 3210; a conflict fails clearly.Defaulted
Configuration paths
Windows
macOS
Linux
XDG path
Fallback
06

Work effectively

Workspace model

Stoix is presentation and orchestration software. Hermes remains the agent runtime and owns canonical agent sessions.

ProjectsKeep related work together

Group project-scoped chats, files, and presentation state.

ConversationsSee progress clearly

Stream responses, tool activity, approvals, and errors in separate states.

RuntimeControl Hermes capabilities

Work with models, skills, plugins, keys, logs, and configuration.

AttachmentsKeep durable bytes local

Selected files live in Stoix’s per-user data directory.

07

Continue anywhere

Channel continuity

When Hermes reports source metadata, Stoix groups external conversations by platform and opens the same canonical session on desktop.

01Hermes reports metadata

The session retains its platform identity.

02Stoix groups the channel

Each supported platform receives a dedicated folder.

03You continue the session

No duplicate local thread is created.

Current boundary

Stoix can continue sessions exposed by the Hermes HTTP API. Hermes does not currently expose a CLI-style handoff back to the originating platform.

08

Stay current

Update policy

Settings checks for a newer published stable version. Installing an update remains an explicit terminal action.

Update Stoix
stoix update
  • 01
    Settings discovers

    The Settings check validates release metadata and reports availability; it does not install anything.

  • 02
    The command updates

    On Stoix 0.1.1 or later, stoix update stops the running app, invokes the bundled installer, preserves configuration and data locations, then relaunches Stoix.

  • 03
    No silent replacement

    Stoix updates only when you request it. When no compatible published release is available, the updater can use the current public source version.

Open GitHub Releases
09

Develop

Run from source

Source development requires Node.js 24, npm 11, and a separately installed Hermes runtime.

macOS / Linux
git clone https://github.com/finxray/hermes-ui.git
cd hermes-ui
npm ci
cp .env.example apps/web/.env.local
npm run dev
Windows PowerShell
git clone https://github.com/finxray/hermes-ui.git
cd hermes-ui
npm ci
Copy-Item .env.example apps/web/.env.local
npm run dev

Open http://127.0.0.1:3000. Put any required HERMES_API_KEY only in the ignored apps/web/.env.local file.

10

Understand

Data & storage

Browser profileWorkspace presentation

Project and chat presentation state is stored in browser IndexedDB.

Per-user data storeDurable attachments

Metadata uses stoix.sqlite3; attachment bytes use a local content-addressed objects directory.

Hermes runtimeAgent sessions

Canonical Hermes conversations and runtime state continue to belong to Hermes.

Version directoriesApplication code

Configuration and user data remain outside immutable application versions.

Default durable-data locations
Windows
macOS
Linux
XDG path
Fallback
11

Trust boundary

Security model

  • 01
    Credentials stay server-side

    Browser JavaScript does not receive the Hermes API key.

  • 02
    Local networking

    Packaged Stoix and Hermes recovery surfaces bind to 127.0.0.1.

  • 03
    Cross-origin mutations are rejected

    State-changing requests are checked at the Stoix server boundary.

  • 04
    Release integrity, not code signing

    Published archives are designed for adjacent SHA-256 verification. Platform signing and macOS notarization are not currently claimed.

  • 05
    No Stoix telemetry endpoint

    The current preview contains no Stoix cloud account, analytics, advertising, or telemetry endpoint.

12

Recover

Troubleshooting

stoix is not found

Open a new terminal so the updated user PATH is loaded. On macOS/Linux, confirm ~/.local/bin is on PATH. You can also use the Start menu or application launcher.

The first installation is taking several minutes

No release is published yet, so the installer downloads source and builds a production package with a temporary, checksum-verified Node.js runtime. Keep the terminal open.

Stoix opens but cannot reach Hermes

Run stoix --doctor, then hermes doctor. Confirm the gateway uses 127.0.0.1:8642 and run hermes gateway start.

Hermes asks for provider authentication

Complete the Hermes setup with your own account or API key. Stoix cannot create or accept provider credentials on your behalf.

Port 3210 is already in use

The packaged launcher fails instead of changing ports silently because browser data is origin-bound. Stop the conflicting service or choose a stable STOIX_PORT in private configuration.

The browser does not open

Run stoix --doctor, then open http://127.0.0.1:3210 manually. Use stoix --no-open when you intentionally do not want automatic browser launch.

The installer failed or an installation is incomplete

Read the terminal error, correct the reported network or tool issue, and rerun the same installer. The installer repairs an incomplete same-version installation without deleting existing configuration or data.

Report an issue
13

Current limitation

Uninstall status

Stoix does not currently provide a tested uninstall command. This documentation does not invent one.

Why this matters

Application files, launcher integration, private configuration, durable attachments, browser IndexedDB, and the separate Hermes runtime have different ownership and deletion consequences. A future uninstaller must offer these as explicit choices.

Until an official removal workflow is implemented and tested on all supported platforms, request platform-specific help through the project issue tracker rather than deleting broad directories manually.

Ready to begin?

Check your platform, run the installer, and verify the local connection.

Install Stoix