InnoClaw: a self-hosted research workspace with shell access

Folders on the server become the chat surface

The organising idea is that you do not import documents into a tool, you point the tool at directories you already have. One environment variable holds a comma-separated list of absolute paths, and those directories become workspaces you can open, browse, edit, and sync. Chatting inside one retrieves over its files and returns answers with citations back to the documents, which is the specific behaviour that separates this from a general chatbot with a document upload screen. The whole local setup is a short fixed sequence:

git clone https://github.com/SpectrAI-Initiative/InnoClaw.git
cd InnoClaw
npm install
cp .env.example .env.local          # then edit: set WORKSPACE_ROOTS and at least one API key
mkdir -p ./data
npx drizzle-kit migrate
npm run dev                          # open http://localhost:3000

After that the interface opens, and the documented path through it is to configure a model provider in settings, open a workspace, click sync, and start asking. The directory list has one constraint that catches people out: the paths must already exist before startup, so a typo produces an empty workspace rather than an error worth reading. There is also a separate folder holding the database and related state, created explicitly before the migration step runs. The framing in the documentation is that this replaces juggling separate tools for literature, notes, code, and automation with one folder you open and sync.

Three workflows, and only one needs a cluster

The documentation offers three starting paths rather than one, and the difference between them is mostly about what infrastructure you have. Paper study is entirely local: it searches several literature sources including a preprint server and a general academic index, summarises what it finds, and runs a structured discussion with several assigned roles, named as a moderator, a skeptic, a librarian, a reproducer, and a scribe. Working in a workspace is the folder model above, extended with an agent panel for multi-step tasks and tool calling, plus importable scientific skills grouped by domain. Remote experiments are the one that needs setup: you inspect repositories, submit jobs through a shell, a scheduler queue, or a site-specific submission tool, and watch execution across clusters, with approval checkpoints before the high-risk steps. Each path names a single first action, which is a good sign that the authors expect people to arrive mid-project rather than starting fresh.

Disabled auth means admin access for whoever connects

This is the part to read before anything else, and the project is commendably direct about it. An authentication mode can be set to disabled, and the environment reference states plainly what that means: anyone who can reach the service gets administrative access, and it should be used only for trusted local or single-user deployments. There is a dedicated script for running the app that way, which is convenient for a laptop and dangerous on a shared network, and the documentation calls out that the app includes shell execution and remote job submission, pointing at a security document for hardening and trust boundaries. Other auth settings are worth knowing about: a secret that signs session cookies, with a suggested way to generate it, a switch that enforces a single bootstrapped administrator while leaving public registration to create ordinary users, and a cookie flag you are told to lower only for temporary plain-HTTP deployments.

A network filesystem breaks the dev server, so it is handled

There is a specific accommodation in the configuration for people whose code lives on a network mount. Without it, running the development server on a filesystem that does not support local file locking fails at startup, because the framework's build directory takes a lock it cannot take. The fix is automatic: the app detects a lockless network filesystem and disables that lock itself, so the dev server starts. Two caveats come with it, and both are the kind that only bite later. You are still told to point the database at local disk, because the database is exactly the kind of file that needs locking even when the build directory does not. And if you override the build directory at all, it has to stay inside the project, which is called out with an example name. So the accommodation is real, but it shifts the problem rather than removing it, and the shift lands on the database.

Nine model providers, and per-vendor URL overrides

The provider configuration is broader than a single vendor would suggest, and the structure of it explains why. There are keys for nine distinct providers, and the interesting part is the second layer: a set of vendor-level base URL overrides whose purpose is to point every model from a given vendor at one endpoint. That is a different model from a global base URL, and it exists because several of these providers are consumed through self-hosted or relay gateways where the models share a common host. So a deployment can mix a hosted key for one vendor with a self-hosted gateway for another without rewriting anything. On the code side, the application targets a current Node release as a hard engine requirement, builds the production bundle with the webpack pipeline rather than the newer bundler, and then runs a verification step against the produced standalone artifact before the build is considered successful.

The container builds a native module it will not ship tools for

The container file is a three-stage build and the staging is deliberate. The first stage installs a compiler toolchain, which exists for one reason: a dependency needs a native compilation step and will not install without a build environment. A schema migration tool is then installed separately and without being recorded, because the runtime stage needs it later for the automatic migration on startup but it does not belong in the shipped dependency set. The build stage runs both the application build and a separate compile of an administrative command tool. The runtime stage is the interesting part. It installs only an init process, which means the application is not running as the first process in the container. It creates an unprivileged user and switches to it. It copies the traced standalone output rather than a node_modules tree, and it brings across the migration files and configuration so the entrypoint can bring the schema up to date on boot without a separate step.

The release tags and the manifest disagree

A small inconsistency worth knowing about if you pin versions. The published releases reach a version four, and the release notes for that entry describe model selection, skill import, and agent refinements. The package manifest inside the repository declares an earlier version, so the version in the file you would inspect is not the version that was shipped. Anyone automating an upgrade from the manifest rather than the tags will therefore target the wrong release. This is the kind of thing that happens when a project publishes from a branch rather than from the manifest, and the documentation's own upgrade instructions sidestep it by telling you to fetch tags and check out an explicit version, which is the correct approach regardless. The upgrade path is otherwise straightforward: fetch tags, check out the version, reinstall, run the migration, build. The instruction to read the changelog and diff your local environment file against the example before every upgrade is the part that will save you an afternoon.

The CLI is the same runtime, not a second one

A terminal client is published from a package inside the plugins tree and is installed by linking the project globally, after which it accepts an interactive invocation or a one-shot prompt. The important detail is that it is not a separate implementation. It runs the same local application runtime the web interface uses, which means there is one set of workspaces, one database, and one configuration rather than two worlds that drift. How it authenticates is the part that trips people up. With authentication enabled, invoking it starts the application for you, opens the browser login page locally, and stores a dedicated session for the terminal once you sign in. That browser round trip is deliberate rather than a gap, since it reuses the web login instead of inventing a second credential flow. For unattended automation the documentation points at the other route instead, starting the application with authentication turned off, which is the same trade-off described earlier taken one step further.

Editorial conclusion

InnoClaw suits a lab or engineer who wants cited answers over private files, agent-assisted review of repositories, and cluster job submission in one self-hosted surface, rather than assembling three separate tools and a tunnel between them. It is a poor fit if the machine is shared or the files are sensitive and nobody has read the deployment hardening notes, because disabling authentication hands anyone who can reach the service administrative access. Before running it, read the security document rather than the quick start, decide whether authentication stays on, and point the SQLite database at local disk even if the rest of the checkout lives on a network mount.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. SpectrAI-Initiative/InnoClaw on GitHub