Why does pnpm not work on Windows when installing Nestor?

Nestor pins a specific pnpm version via Corepack. Run 'corepack enable' once, then use 'corepack pnpm install' (or just 'pnpm install' once Corepack is active). Standalone pnpm installs may shadow the pinned binary and cause Windows path issues.

How do I fix port 3100 already in use?

Either stop the conflicting process (Studio default port) or override with NESTOR_STUDIO_PORT=3200 npx nestor-sh start. The same applies to NESTOR_API_PORT for the underlying server.

How do I migrate a v3.4.x database to v3.5?

No manual step needed. v3.5 ships a numbered migration system (CRIT-7) that detects v3.4.x schemas via the _schema_meta table and inserts a synthetic baseline row marked 'inferred'. The DB is upgraded transparently on the first 'npx nestor-sh start'.

Troubleshooting

Q: Why is the native Rust security core not loading?

Nestor ships native prebuilds for win32-x64, linux-x64, linux-arm64, darwin-arm64. If your platform isn't covered (e.g. darwin-x64 Intel Mac, deprecated since v3.5), Nestor automatically falls back to a JS implementation — about 5-15% slower on hot paths but functionally identical.

Quick fixes for the most common Nestor install, runtime, and integration issues. If you don't find your problem here, please open an issue with full reproduction steps.

Install issues

Windows: `pnpm: command not found` or version mismatch

Nestor pins a specific pnpm version via packageManager in package.json. The recommended way is to enable Node's built-in package manager dispatcher:

# One-time setup
corepack enable

# Then use the pinned pnpm transparently
corepack pnpm install
corepack pnpm -r build

If you have a global pnpm installed via npm install -g pnpm, it may shadow Corepack's binary and cause confusing version errors. Either remove the global install or always prefix with corepack.

`npx nestor-sh install` hangs or never finishes

The interactive wizard expects a TTY. If you're running inside a non-interactive shell (CI, IDE terminal pane, nohup), pass an explicit config file instead:

# Non-interactive install with a pre-filled config
npx nestor-sh install --config ./nestor.config.json --yes

If the wizard hangs at "Detecting platform...", check that your network can reach registry.npmjs.org (the optional native package fetch). With no network, the install still completes — Nestor falls back to the JS implementation.

"`EACCES: permission denied`" when writing to `~/.nestor`

Nestor stores its database, logs, and skill cache under $NESTOR_HOME (defaults to ~/.nestor). On systems where the home directory is read-only or symlinked oddly, override the location:

export NESTOR_HOME=/var/lib/nestor
npx nestor-sh install

NESTOR_HOME is honored by all CLI commands (install, start, shell, daemon, watch, telemetry, evolve, schedule, skill) since v3.5.

Runtime issues

"Port 3100 already in use"

The Studio dashboard binds to port 3100 by default. If another process holds the port, override it:

NESTOR_STUDIO_PORT=3200 npx nestor-sh start
NESTOR_API_PORT=3201 npx nestor-sh start # underlying server

API key validation fails for a working key

Nestor validates keys at install time by issuing a small probe call to each provider. Causes of false-negative validation:

Anthropic: keys created without "Claude API" scope. Re-issue from the console with full access.
OpenAI: project-scoped keys without an active project — set OPENAI_PROJECT_ID in the env.
Gemini: keys must come from Google AI Studio, not Vertex AI. Vertex requires a different adapter (not yet shipped).
OpenRouter: keys with rate_limited tier hit the probe quota immediately. Skip validation with --skip-validate on install.

Agent fails with "`Tool execution timeout`"

Default tool timeout is 60s. Long-running tools (web_fetch against slow upstreams, large shell_exec) need a higher timeout — set per-agent:

npx nestor-sh agent config <agent-name> --tool-timeout-ms 180000

"`Approval required`" loops in shell

If you set --approve manual and every tool invocation prompts, switch to smart mode (the default) which only prompts for high-risk operations:

/approve smart

Or extend the allow-list:

npx nestor-sh agent config <agent-name> --add-allow file_read,file_list,web_fetch

Native build / Rust core

"`Native module not found, falling back to JS implementation`"

This is informational, not an error. Nestor publishes prebuilt native packages for win32-x64, linux-x64, linux-arm64, and darwin-arm64. If your platform isn't in that matrix (e.g. darwin-x64 Intel Mac, deprecated since v3.5), Nestor automatically routes to a pure-JS implementation. Performance impact: ~5–15% slower on the security-core hot paths (SSRF check, secret redaction). Functionality is identical.

Linux ARM64 (Raspberry Pi, AWS Graviton): native fails to load

Make sure you're on glibc 2.31+ (Debian Bookworm, Ubuntu 22.04+). Older distros need to fall back to JS:

NESTOR_NATIVE=disabled npx nestor-sh shell

I want to build the Rust core from source

Clone the repo, install Rust 1.75+, then:

git clone https://github.com/lrochetta/nestor.git
cd nestor
corepack pnpm install
corepack pnpm --filter @nestor/native build:rust

The build produces packages/native/index.<platform>-<arch>.node, which is loaded by the JS wrapper at packages/native/src/index.ts.

Database / migrations

Upgrading from v3.4.x — do I need to migrate manually?

No. v3.5 ships a numbered migration system (CRIT-7) that handles v3.4.x DBs transparently. On first npx nestor-sh start after upgrade:

The runner detects the legacy _schema_meta table from v3.4.x.
It creates a new _schema_migrations table.
It inserts a synthetic baseline row marked inferred=1 for migration 001-initial.
Subsequent migrations apply incrementally.

Your data is never touched. If something goes wrong, restore $NESTOR_HOME/nestor.db from before the upgrade.

"`SQLITE_BUSY: database is locked`"

Two Nestor processes are competing for the same DB file. The most common cause is npx nestor-sh start already running while you launch npx nestor-sh shell against the same NESTOR_HOME. Either stop the daemon first, or run the second process in a different home:

NESTOR_HOME=~/.nestor-sandbox npx nestor-sh shell

Database file grows large (>1 GB)

Mostly OTel telemetry events and run history. Two safe operations:

# Compact (VACUUM) to reclaim space
npx nestor-sh telemetry compact

# Trim run history older than 30 days
npx nestor-sh telemetry prune --older-than 30d

Integrations

Claude Code / Claude Desktop don't see the MCP tools

Restart Claude Code after editing mcp.json. Verify the JSON is well-formed:

{
  "mcpServers": {
    "nestor": {
      "command": "npx",
      "args": ["nestor-sh", "mcp"]
    }
  }
}

If tools still don't appear, run npx nestor-sh mcp --debug standalone to confirm the server starts without errors.

Obsidian sync writes nothing

Check ~/.nestor/config.json contains a valid obsidian.vaultPath. The path must be absolute. The agent process needs write permission to that directory.

Performance

macOS Intel (darwin-x64) feels slow

Confirmed and expected. v3.5 deprecated darwin-x64 prebuilds — Intel Macs run the JS fallback for the Rust security core, which is ~5–15% slower on hot paths. Apple Silicon Macs are unaffected. There is no meaningful workaround beyond upgrading to Apple Silicon hardware.

First Studio page load is slow

The first request rebuilds the WAL index in SQLite. Subsequent loads are sub-100ms. To pre-warm:

npx nestor-sh start --prewarm

Getting help

If you've tried the above and it's still broken:

Run npx nestor-sh doctor — this prints a full diagnostic (versions, paths, native status, DB integrity).
Search existing issues.
If nothing matches, open a new issue with the doctor output, your platform, and exact reproduction steps.
Quick questions: GitHub Discussions.

✎ Edit this page on GitHub · Last updated 2026-04-26