Back to Browse

Venira MCP Server

Developer ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Workspace-scoped MCP server for coding agents: files, search, shell, checkpoints, PR/CI, audit.

About

Workspace-scoped MCP server for coding agents: files, search, shell, checkpoints, PR/CI, audit.

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (3 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.

6 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

Shell Command Execution

Runs commands on your machine. Be cautious — only use if you trust this plugin.

database

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Absolute path of the project folder the server works in. Defaults to the current directory.Optional

Environment variable: VENIRA_WORKSPACE

Folder for the audit database and encrypted secrets. Defaults to <workspace>/data.Optional

Environment variable: VENIRA_DATA_DIR

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "venira-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "venira-mcp@1.19.0"
      ],
      "env": {
        "VENIRA_DATA_DIR": "your-venira-data-dir-here",
        "VENIRA_WORKSPACE": "your-venira-workspace-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

venira-mcp

Fast, workspace-scoped MCP server for coding agents (OpenCode, Claude Desktop, any MCP client). Three tool modes — Core (32 tools: coding set minus code intelligence, for small models) · Default (39 coding tools + shell, no CI/CD) · Expert (52 tools: default + CI/CD). VENIRA_JS_EXEC_MODE=off hides execute_js in every mode (52 → 51, 39 → 38, 32 → 31); otherwise it is registered and approval-gated. VENIRA_SETUP_TOOLS=1 adds the two setup tools detect_harnesses and install_self (+2); npx venira-mcp --install and --print-config do the same from a terminal. Pure Node, 1 native dependency (better-sqlite3), no GUI, no external binary.

Security scope. Venira is a guard rail with an audit trail, not a sandbox. It runs with the privileges of the OS user that started it. The workspace lock limits the paths the file tools can touch (unless VENIRA_UNRESTRICTED=1), not what a shell command does: commands are classified by rules (allow / ask / deny) and every call is audited, but a malicious prompt can still steer the agent into running a harmful command that the active profile lets through (with off, every command runs). Anything running as the same OS user can read the keys in VENIRA_DATA_DIR. For untrusted workspaces, or whenever you need a real isolation boundary, run Venira in a container or VM. Details: SECURITY.md.

1. Setup

One-line install (run in your project, then restart the client):

npx --yes venira-mcp@latest --install auto --workspace .

Prefer your agent? Paste this prompt into OpenCode/Claude/Cursor:

Set up Venira MCP for this workspace.
1. Detect my MCP client config path.
2. Run: npx --yes venira-mcp@latest --install auto --workspace .
3. Restart the client. Then call health to verify.

Manual config (pick your client):

ClientConfig pathFormat
VS Code<workspace>/.vscode/mcp.jsonJSONC
OpenCode~/.config/opencode/opencode.jsoncJSONC
Claude Desktopclaude_desktop_config.jsonJSON
Cursor~/.cursor/mcp.jsonJSON
Codex~/.codex/config.tomlTOML

All use the same npx command. See §2 for ready-to-copy JSON/TOML.

In this repo .vscode/mcp.json is git-ignored because it holds machine-specific settings (and may relax security flags). Copy .vscode/mcp.example.json to .vscode/mcp.json and adjust it locally.

2. Client configs (copy-paste)

The examples use two environment variables: the workspace and the tool set. Everything else has a safe default, so you only add a VENIRA_* variable when you want to change that default (see Config recipes).

OpenCode / VS Code / Cursor / Claude / Kimi / DeepSeek / Antigravity — use the wrapper format supported by your client:

// OpenCode: "mcp" > "venira" > "environment"
{
  "mcp": {
    "venira": {
      "type": "local",
      "command": ["npx", "--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "enabled": true,
      "environment": {
        "VENIRA_WORKSPACE": "/absolute/path/to/project",
        "VENIRA_TOOL_MODE": "expert",
        // Small model / restricted context? Uncomment to slim tools/list:
        // "VENIRA_TOOL_MODE": "core"
      }
    }
  }
}

// VS Code: "servers" > "venira" > "env"; ${workspaceFolder} expands automatically.
{
  "servers": {
    "venira": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "${workspaceFolder}",
        "VENIRA_TOOL_MODE": "expert"
      }
    }
  }
}

// Claude / Cursor and compatible clients: "mcpServers" > "venira" > "env"
{
  "mcpServers": {
    "venira": {
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "/absolute/path/to/project",
        "VENIRA_TOOL_MODE": "expert"
      }
    }
  }
}

Generic MCP JSON example

For clients that accept the common mcpServers JSON shape, use the example for the user's operating system as a realistic starting point. Replace the example paths with paths on the user's machine; VENIRA_DATA_DIR is optional and can point to any writable directory. Keep this file private if it contains local paths or credentials.

Windows:

{
  "mcpServers": {
    "venira": {
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "C:\\Users\\YourName\\Projects\\my-app",
        "VENIRA_DATA_DIR": "C:\\Users\\YourName\\AppData\\Local\\venira",
        "VENIRA_TOOL_MODE": "expert"
      }
    }
  }
}

Linux:

{
  "mcpServers": {
    "venira": {
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "/home/yourname/projects/my-app",
        "VENIRA_DATA_DIR": "/home/yourname/.local/share/venira-mcp",
        "VENIRA_TOOL_MODE": "expert"
      }
    }
  }
}

mcpServers is a common client configuration shape, but some clients use a different outer key or file format. Preserve the Venira command, args, and environment values when adapting the example. The approval command returned at runtime uses the effective data directory from this configuration, so users and agents should copy data.approval.approve_command instead of constructing a path themselves.

Codex (~/.codex/config.toml):

[mcp_servers.venira]
command = "npx"
args = ["--yes", "--package=venira-mcp@latest", "venira-mcp"]

[mcp_servers.venira.env]
VENIRA_WORKSPACE = "C:\\path\\to\\project"
VENIRA_TOOL_MODE = "expert"

Config recipes

Pick one block and put its variables in the env section of your client config. Every other variable keeps its default.

RecipeVariables
Minimal (recommended)VENIRA_WORKSPACE, VENIRA_TOOL_MODE=expert
Fewer prompts on a personal machineMinimal, plus VENIRA_SECURITY_PROFILE=trusted
Full trust (isolated or personal machine only)Minimal, plus VENIRA_SECURITY_PROFILE=off

off keeps full trust: shell checks off (hard-deny included), no workspace lock (VENIRA_UNRESTRICTED=1), VENIRA_JS_EXEC_MODE=auto as the default JS mode, no elicitation, full env passed to shell, reveal=1 prints secrets and nothing prompts. A variable you set yourself always wins over the profile (e.g. VENIRA_JS_EXEC_MODE=off stays off). Deliberate opt-ins are never implied: VENIRA_SHELL_OVERRIDES, VENIRA_ALLOW_SELF_INSTALL and VENIRA_SECRET_KEYCHAIN.

Do not write a variable just to restate its default (for example VENIRA_OUTPUT_MODE=full, VENIRA_USE_RIPGREP=1 or VENIRA_SECURITY_PROFILE=balanced).

Security profiles

VENIRA_SECURITY_PROFILEShell policyUse
strictstrictRead-only and workspace-local allowlist runs without approval
balanced (default)balancedRecommended general-purpose setting
trustedpermissiveAsk-rule and unclassified commands run; hard-deny commands require approval
offoffFull trust: shell checks off, no workspace lock, JS exec auto, no elicitation, full env passed to shell. Prints a warning and audits shell commands. Replaces setting those variables one by one; any of them you set explicitly still wins

VENIRA_SHELL_MODE is an advanced override and takes precedence over the profile. VENIRA_JS_EXEC_MODE separately gates the JavaScript tool: off (default) hides it, ask registers it with per-call human approval (skipped when VENIRA_PERMISSION_MODE=allow_all), semi-auto registers it without approval but keeps the containment (workspace-only fs, scrubbed env, no child processes; network is always open), auto registers it without approval and without any containment (full fs access, inherited env; personal machines only). switch_workspace follows the profile the same way: trusted/off (and an explicit VENIRA_UNRESTRICTED=1) switch to any existing directory; strict/balanced switch only inside VENIRA_WORKSPACE_ROOTS, which unset locks switching to the spawn workspace.

Choose trusted when you want fewer prompts on a personal machine. Choose off only when you intentionally accept that shell checks are disabled; JS exec is still gated by VENIRA_JS_EXEC_MODE (a human gate for execute_js only counts when that mode is ask and VENIRA_PERMISSION_MODE is not allow_all). The secret_env gate remains active in every profile. Elicitation hangs off the shell mode: strict never prompts (CLI grant only), balanced prompts for every unclassified ask-rule command, permissive never prompts at all (only the command_substitution always-ask rule, hard-deny commands downgraded to ask.deny.*, and secret_env still prompt), off never prompts.

Advanced configuration

VariableDefaultChange when
VENIRA_SHELL_MODEProfile mappingYou need to override only the shell policy (strict, balanced, permissive, or off)
VENIRA_JS_EXEC_MODEoffask registers execute_js with per-call approval (skipped when VENIRA_PERMISSION_MODE=allow_all); semi-auto registers it without approval but contained; auto registers it without approval and without containment
VENIRA_UNRESTRICTED0Keep workspace path restrictions enabled; do not set to 1 in production

See the full environment reference in §6 for caching, shell, provider, and diagnostic options.

3. Benchmark (per-op, p50)

Measured: Windows + Node 24, standalone build, 2026-11-01.

Opp50Notes
Cached read_file8.0 mswarm cache
read_batch (8 files)12.8 msone call, 8 items
get_file_info6.2 mscached
search (literal, *.ts)11.5 msp95 ≈ 1.3 s (file count dependent)
health (no DB)28.5 ms
shell_run + status~930 ms2 s wait budget dominates
First call113.7 mspost warm-up

Batch: 8 reads as one batch call (16.6 ms) vs 8× individual (~76 ms) — the round-trip saving that makes the agent loop fast.

Agent tool-path benchmark: Venira MCP vs Codex exec_command

Measured on 2026-11-07 on one Windows 11 build 26200 machine (Intel Core i5-1035G1, 8 logical processors, 11.8 GiB RAM, Node v24.20.0). Each workload used 20 paired samples per phase, alternating call order. Venira used the persistent MCP connection; each native exec_command call launched a fresh PowerShell process. Cache-miss samples cleared Venira's in-process cache; warm samples reused it. The OS filesystem cache stayed warm.

WorkloadPhaseVenira p50 / p95exec_command p50 / p95Ratio of p50s
Read first lines of 8 files in one batchCache miss53.5 / 72 ms962 / 1,121 ms17.98×
Read first lines of 8 files in one batchWarm39 / 60 ms1,103.5 / 1,549 ms28.29×
Search VENIRA_WORKSPACE across the workspace (49 hits)Cache miss118.5 / 188 ms1,034.5 / 1,507 ms8.73×
Search VENIRA_WORKSPACE across the workspace (49 hits)Warm34.5 / 152 ms1,018 / 1,383 ms29.51×

Both workloads matched exactly in all 20 pairs: normalized text for the 8-file batch and sorted file/line locations for search. These are practical agent tool-path timings, not raw filesystem timings. A separate 100-sample component benchmark shows native PowerShell can be faster for simple uncached reads; the largest Venira gains are on warm list/search and avoiding a fresh shell process. The p95 estimates are rough with 20 samples, and results from this one machine are not a general performance guarantee.

See the full methodology and results and raw samples. Reproduce the component benchmark from the repository root with npm run bench:tools -- --runs=100.

4. Three tool modes

Three tool modes set which tools the client sees. Set via VENIRA_TOOL_MODE env var or "toolMode" in venira.config.json (env wins). VENIRA_DISABLE_TOOLS hides additional tools on top. core is the small-model / restricted-context preset (the old VENIRA_PROFILE=core, now folded into this one variable).

ModeToolsIncludes
core32default minus the code-intelligence tools: dependency_graph, change_impact, outline_symbol, diff_files, symbol_references, recent_files, execute_js
default39Read/write/edit/search, code intel, snapshots, shell, delete_path, execute_js — no CI/CD; explain_error and plan_read_batch are expert-only
expert52Everything in default + pr_*, ci_*, explain_error, plan_read_batch

delete_path is always available. In balanced / strict mode, shell rm -rf / / ~ and Windows drive-wide deletes are hard-denied, and recursive/force deletes (Remove-Item -Recurse -Force, rd /s /q, del /f /q) need approval. permissive mode lets ordinary ask-rule and unclassified commands run without a prompt, but hard-denies require approval and uninspectable command substitutions require approval in every policy-enabled mode.

5. Tools quick reference

All tools return the standard envelope (ok, kind, data, hint, elapsed_ms).

Read (batch-safe, cached)

ToolPurpose
list_filesList files/dirs, depth 1–3, limit ≤ 200
read_fileRead a file by line range; optional ranges[] (up to 16)
get_file_infoFile/dir metadata (kind, size, mtime); missing_ok=1 answers ok with exists:false for missing paths (works in read_batch)
searchSearch by file/dir name, content, regex, or symbol; hybrid: 1 tags hits with source+confidence; queries[] ranks files by AND/OR/NOT patterns
recent_filesRecently modified files (index-first, scan-fallback)
read_batchUp to 8 read-only ops in one call; each item takes the same arguments as its standalone tool (search items support regex, case_sensitive, hybrid, ...)
healthDiagnostics: capability, queue, cache hit-rates, p50/p95, security limits notice, and server.workspace_switching (enabled, profile, allowed_roots)
switch_workspaceRe-root the workspace to another directory mid-session — for clients that spawn the server once (e.g. Claude Desktop). Follows VENIRA_SECURITY_PROFILE: trusted/off switch to any existing directory; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = locked to the spawn workspace)
read_auditRead recent audit log rows
memoryOne handoff note per workspace that outlives the chat: action=read at the start of a task, action=write (full overwrite, max 6000 bytes) before finishing or running out of context. Plain markdown at <workspace>/.venira/memory.md (follows switch_workspace; legacy data-dir note is still read as a fallback). Not encrypted, so keep secrets out

Whole-file hashes. read_file returns sha256 = the hash of the whole file (sha256_scope: "file"), even when the call returned only a slice, and text_sha256 = the hash of the text that was returned. sha256 is therefore safe to send back as expected_sha256; text_sha256 is not. The hash covers the raw bytes, so a file with a BOM round-trips. When a write or edit refuses a stale hash (stale_content), the file is left untouched and the response asks for a fresh read: re-read the file, rebuild the patch against the current content and send the new hash - never replay the same edit unchanged. In compact mode the text arrives as preview (preview_truncated marks a cut); the hash fields are always there.

Recovery that fits the tool. A failure names the call that can recover from it: a missing secret points at secret action=list, a missing device flow at github_connect action=start, a missing checkpoint at snapshot action=list, a missing file at the file tree. A read batch that lost one item is marked partial: true and reports failed_count and succeeded_count, so the successful reads stay visible. health in compact mode keeps whole sections and names the ones it dropped, and sections asks for exactly the parts you need.

A failed edit answers with a diagnosis, not a dump. When old_text is not in the file, the error says where it went wrong and how small the gap is: mismatch carries the file, the line, the first differing character, how many characters the line is off, and the two lines it compared. context carries three lines before and three after the wrong spot - without line numbers, so it can be copied straight into old_text (numbered has the numbers for orientation). The payload stays under a kilobyte even for a long edit, and the file is never changed by a refused edit. indentation and line_endings say whether the file uses tabs or spaces and CRLF or LF - the two things plain text cannot show.

Snippets that run. execute_js gives a snippet with a top-level await the same require it has in CommonJS mode, so the two are not mutually exclusive. A static import of a network module is refused before the snippet runs (in the contained modes) with the way out; a require of one is blocked at runtime, so a snippet that proves the block still runs. A top-level return, a timeout and a failed snippet all come back with a reason you can act on, and the envelope carries command_status: "failed".

Write (mutating, pass reason)

ToolPurpose
write_fileCreate/overwrite/append; expected_sha256 guards blind overwrites
edit_fileReplace old_text→new_text; edits[] (up to 64); fuzzy edit opt-in
edit_batchMultiple edits; stops at first failure and attempts checkpoint rollback. Check data.atomic and data.rollback_succeeded; snapshot failure/incompleteness or a partial restore means changes may remain. A batch that rolled back cleanly removes its own checkpoint (data.checkpoint_deleted: true), so a failed attempt does not eat a VENIRA_SNAPSHOT_KEEP slot; a failed rollback keeps the checkpoint - it is the recovery path.
createCreate a directory (missing parents are created; use write_file for file content)
move_pathMove or rename a file/dir; overwrite=1 replaces a file (never a directory); not undoable
copy_pathCopy a file, or a directory with recursive=1; skips symbolic links and protected files inside a directory
apply_patchApply a unified diff (create/modify/delete/rename), all-or-nothing; dry_run=1 to validate first; rolls back every file on failure
delete_pathDelete file/dir; not undoable

Checkpoints (git-free rollback)

snapshot — create/list/restore/delete. Content-addressed, deduplicated, atomic per-file restore. The id carries the local timestamp (snap-20261113-001500-3f9ac2); the exact instant is created_at_ms (epoch milliseconds).

Code intelligence

ToolPurpose
outline_symbolParse a file's symbols (functions, classes, types) with line numbers
diff_filesUnified diff between two files
symbol_referencesFind all occurrences of a named symbol
dependency_graphTS/JS/Python/Rust/Go/Java/Kotlin import/symbol graph (JSON/DOT/Mermaid)
change_impact"What breaks if I edit this?" — bounded reverse/forward closure

Two caps, two names. symbol_references has max_references (how many references come back - the token bill, default 100) and limit (how many workspace hits are scanned - the work, default: max_references). The result says which one bit: count (found), returned, omitted, scan_limit and limited.

change_impact says what it could not resolve. unresolved[] holds the seeds that did not resolve (the symbol is not declared, or the name is ambiguous in N files) with a next_step; the graph-wide unresolved imports are only counted (stats.unresolved_imports), because they say nothing about the seeds and cost tokens on every call.

The graph's side lists are short and counted. dependency_graph returns the 50 most used external[] entries and the 10 first unresolved[] ones; stats.externals and stats.unresolved_imports hold the full counts, and limited: true says that a list was cut.

Shell (async, policy-gated)

ToolPurpose
shell_runRun a command; background: 0 blocks for final output; 1 returns run_id. shell: powershell (Windows PowerShell 5.1), pwsh (PowerShell 7+), cmd or bash; omitted → VENIRA_DEFAULT_SHELL, else cmd on Windows and $SHELL/bash elsewhere
shell_statusPoll a running command (not queued, not audit-logged)
shell_cancelKill a running command by run_id
shell_cancel_sessionKill all shell runs in this session

Repeated-failure guard. A shell invocation is fingerprinted (normalized command, shell, resolved cwd and the non-secret inputs; secret_env contributes its names only) and the fingerprint is remembered per session when the run fails or times out. The identical invocation is then not run again: the call fails with repeated_failure and carries data.previous (exit code, timed-out flag, bounded stderr tail, failure count). Nothing is stored but the hash - never the command text, never a secret value - so a repeat with secrets is reported as "same command and inputs", never as an exact match of the secret values. Change the command, the shell, the cwd or the inputs and it runs normally; a deliberate rerun of the identical command is retry_failed: 1. A successful run clears the memory.

What the shell really did. The response names the binary that ran the command (shell_path, shell_kind: native, wsl, git-bash or unknown) - on Windows bash is often the WSL launcher, which runs the command inside a Linux distro and reports its own messages in UTF-16 (those are decoded for you, and a WSL without a distribution comes back with a shell_hint). cmd.exe receives the command verbatim, so double quotes survive; PowerShell reports the native exit code of the last command (git status outside a repository reports 128, not 1), while a failing cmdlet still reports 1.

Choosing a shell on Windows. powershell starts powershell.exe (5.1), which has no && / || pipeline-chain operators; pwsh starts PowerShell 7+ (winget install --id Microsoft.PowerShell), which has them. pwsh must be on the PATH of the server process, so restart the MCP client after installing it. Policy treats both as the same PowerShell dialect: every segment of an && / || chain is classified on its own, so a denied command after && is still denied (policy_adv_dialect_pwsh_chain_operators). pwsh starts slower than cmd; set VENIRA_DEFAULT_SHELL=pwsh only if you want it for every call. A shell binary that is not installed fails with [shell_unavailable] and an install hint instead of returning exit code -1. In PowerShell an unquoted (...), @(...) or {...} counts as a substitution the policy cannot inspect, so a command that carries one always asks for approval in policy-enabled modes, including permissive: PowerShell evaluates the group before the command runs, so git status (Remove-Item -Recurse -Force $HOME) would otherwise delete while looking like read-only git (policy_adv_dialect_powershell_grouping_expressions).

Local git (this repo)

ToolPurpose
git_statusParsed worktree status: branch/detached, upstream (+ upstream_gone), ahead/behind, per-file {path, old_path?, staged, unstaged, untracked, unmerged, kind, status, index_status, worktree_status} + counts; clean flag; paths[] limits
git_diffParsed diff (staged=1 for the index): per-file action (`added
git_logCommit list (ref, limit, paths[], author, grep) — or blame=1 with path for per-line blame (line, commit, author, authored_at, summary, prev_*); max_lines caps blame
git_branchaction=list (local; include_remote=1 for remotes), current, create (from= optional), switch, delete (force=1)
git_commitCommit staged changes, or stage paths[] first; amend=1 / allow_empty=1 opt-in; reports sha, files_changed, files
git_stash`action=push

Read-only git (status, diff, log/blame, branch list/current, stash list/show) needs no reason; mutating calls do. Mutations invalidate the whole cache (worktree-wide change). Local only against the workspace repository root (git rev-parse --show-toplevel; paths stay workspace-relative); push is never performed by these tools — routine git pushes need no approval, force/delete/URL pushes ask one, and ALLOW_ENV_READ is the only remaining named override.

Git provider: PR/CI (GitHub, GitLab, Bitbucket)

pr_create/comment/merge/list/close/reopen, ci_status/trigger/logs/wait, ci_control (cancel / retry-failed; Bitbucket supports cancel only) — same tool args across providers; token from secret or env vars.

CI reads are bounded and never hide a cap:

  • Pagination — status/job/check-run/step lists follow the provider's next-page link (Link header on GitHub/GitLab, body next on Bitbucket) for at most 5 pages / 200 items, stay on the configured API origin, and never fetch the same page twice. When a cap or the provider total stops the walk, the result says so (truncated / partial) instead of reporting a partial list as complete.
  • Verdicts — a finished Bitbucket pipeline/step is read from state.result (not just COMPLETED), so a failed run is never shown green.
  • Logs — failing steps/jobs are read first; archives and entries are byte-capped (see VENIRA_GIT_LOG_*), and a log whose declared size is over the cap is refused before it is downloaded.
  • ci_wait — one bounded long-poll (no polling loop). Returns summary (one line), next_step (wait_again · merge_or_continue · fix_failing_step_then_push · read_logs · inspect_status), failing_jobs (max 5) and, on failure, a failure_tail of the first failing job (numeric ids on GitHub/GitLab, UUID step ids on Bitbucket).

Secrets (encrypted at rest)

secret — store/inspect/remove credentials by name; AES-256-GCM; rotation metadata; expired secrets refused. github_connect — GitHub Device Flow, tokens in vault.

Diagnostics & planning

explain_error — turn an error into a cause + next tool calls (rule table, no model). plan_read_batch — plan which files to read for a task, returns ready read_batch call. cache_clear — clear the in-process caches (all / read / info / list / search / recent / negative / graph / shell) when reads look stale because a tool changed files outside Venira. trace_status — show recent traced tool calls and the trace configuration; tracing is always on (VENIRA_TRACE was removed), and VENIRA_TRACE_FILE additionally appends to a rotating file.

JS execution

execute_js — run synchronous JS (opt-in via VENIRA_JS_EXEC_MODE). The mode decides both the approval step and how much the snippet is contained:

ModeApproval per callNetworkFilesystemEnvironment
off (default)tool not registeredn/an/an/a
askyes (skipped when VENIRA_PERMISSION_MODE=allow_all)open (every mode)workspace onlyscrubbed
semi-autonoopen (every mode)workspace onlyscrubbed
autonoopenunrestrictedinherited
  • Contained (ask, semi-auto): Node's permission model limits reads and writes to the workspace and denies child processes and workers; only PATH, TERM and NODE_PATH are passed (HOME and USERPROFILE are empty). Network access is open in every mode. This is best-effort containment, not a sandbox.
  • auto drops all of the above: the snippet has the full network, the full filesystem, child processes and the server's environment (including any tokens in it). Use it only on a personal machine you trust. health reports js.exec_without_approval (a warning) for both semi-auto and auto; it does not distinguish the two.
  • semi-auto is the old behaviour of auto. If your config says VENIRA_JS_EXEC_MODE=auto and you want the snippet to stay contained, change it to semi-auto.
  • Output is still redacted for obvious secret assignments, and the timeout (default 30 s, max 10 min) applies in every mode.

6. Environment variables (key ones)

Full reference: the source reads 80+ distinct supported VENIRA_* names; this table lists the documented ones. See the source or npx venira-mcp --help for the rest.

VariableDefaultWhat it does
VENIRA_WORKSPACEprocess.cwd()Workspace root; all paths resolve against it
VENIRA_TOOL_MODEdefaultcore (32 tools) / default (39 tools) / expert (52 tools); +2 with VENIRA_SETUP_TOOLS=1
VENIRA_OUTPUT_MODEfullfull or compact (summarize/trim payloads > 8 KiB; generic payloads use preview_text)
VENIRA_AUDIT_DETAILsummaryWhat read_audit can show per job: off stores nothing extra, summary keeps one args line and one result line, full also keeps redacted JSON args/result (up to 16 KiB per job). Long or sensitive values (file content, old_text/new_text, secret values) are stored as a length only
VENIRA_UNRESTRICTED"0""1" disables workspace lock (never in production)
VENIRA_SECURITY_PROFILEbalancedSelects the shell policy: strict, balanced, trusted, or off
VENIRA_SHELL_MODEProfile mappingAdvanced override for shell policy: strict, balanced, permissive, or off
VENIRA_DEFAULT_SHELLcmd on Windows, $SHELL / bash elsewhereShell used when a call does not name one: powershell (5.1), pwsh (7+), cmd, bash
VENIRA_SHELL_TAIL_MAX2000Characters kept in a shell run's stdout/stderr tail (minimum 256); the head of huge output is dropped so the exit code and last lines survive
VENIRA_SHELL_MAX_OUTPUT_BYTES262144Per-stream cap (stdout and stderr each) that a shell run records
VENIRA_SHELL_MAX_TIMEOUT_MS1800000Upper bound for a caller-supplied shell timeout (timeout_s); larger values are clamped to this
VENIRA_JS_EXEC_MODE"off""off" hides execute_js · "ask" registers it with per-call approval (skipped when VENIRA_PERMISSION_MODE=allow_all) · "semi-auto" registers it without approval, contained (workspace-only fs, scrubbed env, no child processes; network always open) · "auto" registers it without approval and without containment
VENIRA_USE_RIPGREP"1""1" uses ripgrep if installed (faster on big repos)
VENIRA_SEARCH_MAX_FILES"50000"Max files collected by the JS fallback walker before it stops and reports complete: false. Bounds searches rooted at huge trees (e.g. with VENIRA_UNRESTRICTED=1 and an absolute path outside the workspace)
VENIRA_CACHE"all"all every TTL cache on · list only directory listings · search only searches · off always fresh (slower)
VENIRA_EDIT_FUZZY"0""1" enables fuzzy-match fallback for old_text, and adds fuzzy_distance, ignore_indentation and case_insensitive to the edit_file / edit_batch schemas. tools/list changes with this flag, so reconnect the client after changing it. With "0" those options are not advertised and a call that still sends them is refused with [unsupported]
VENIRA_DATA_DIRper-user OS pathWhere audit DB + encrypted secrets live
VENIRA_SNAPSHOT_ROOT<per-user data dir>/snapshotsShared checkpoint root for every project and client; each workspace gets its own sub-folder (absolute path)
VENIRA_SNAPSHOT_DIRunsetExact checkpoint store for a single project, no sub-folders; wins over VENIRA_SNAPSHOT_ROOT (absolute path)
VENIRA_SNAPSHOT_KEEP20Checkpoints kept per project (oldest pruned on create)
VENIRA_SNAPSHOT_MIRROR_DIRunsetOptional append-only copy of the checkpoint store in this existing folder (OneDrive/Dropbox, NAS share, USB drive, rclone mount); absolute path, must be outside the store and the workspace
VENIRA_SNAPSHOT_MIRROR_TIMEOUT_MS20000 after create, 100000 for action=mirrorTime budget of one mirror run; it stops between files (partial) and the next run resumes
VENIRA_DISABLE_TOOLSunsetComma-separated tool names to hide from tools/list
VENIRA_GIT_PROVIDERinferredgithub / gitlab / bitbucket
VENIRA_GIT_TOKENunsetFallback token when no provider-specific secret found
VENIRA_GIT_TIMEOUT_MS60000Per-request timeout for provider JSON calls (1 000–600 000)
VENIRA_GIT_RETRIES1Retries for safe GET reads only (0–3); POSTs are never replayed
VENIRA_GIT_LOG_TIMEOUT_MS90000Timeout for CI log downloads (1 000–900 000)
VENIRA_GIT_LOG_ZIP_BYTES33554432Max bytes of a CI log archive; larger declared sizes are refused before download
VENIRA_GIT_LOG_ENTRY_BYTES / VENIRA_GIT_LOG_TEXT_BYTES4194304 / 8388608Per-entry and total decoded log text caps
VENIRA_SHELL_OVERRIDESunsetOperator allowlist: ALLOW_ENV_READ (the ALLOW_GIT_PUSH override was removed)
VENIRA_PERMISSION_MODEallow_allPermission mode passed when the session scope opens (manual / best_effort / allow_all); allow_all also skips the VENIRA_JS_EXEC_MODE=ask approval prompt; shown in health
VENIRA_SESSION_IDautoSet for test/verify runs to separate audit rows
VENIRA_SESSION_GRANT_RULESbuilt-in: cd_outside_workspaceExtra ask-rule ids (comma-separated) that may be approved with --approve --session
VENIRA_SHELL_APPROVAL_TTL_MS600000 (10 min)Lifetime of an in-memory --session grant; pending approvals always expire after a fixed 5 minutes
VENIRA_SETUP_TOOLS"0""1" advertises detect_harnesses and install_self in tools/list (changes the tool list after a restart)
VENIRA_ALLOW_SELF_INSTALL"0""1" lets install_self write other clients' config files
VENIRA_SHELL_POLICY_FILEunsetPath to a JSON shell policy file (allow/ask/deny rules); never read from the workspace automatically
VENIRA_TOOL_POLICY_JSON / VENIRA_TOOL_POLICY_FILEunsetPer-tool policy rules, inline JSON or a file (see lib/tool-policy.ts)

Advanced tuning knobs (all optional)

Sensible defaults; leave any of these unset unless you know why you set them.

VariableDefaultWhat it does
VENIRA_PRETTY"0"Pretty-print JSON envelopes
VENIRA_BATCH_ITEM_BYTES524288Per-item response budget inside read_batch; larger items are trimmed
VENIRA_SHELL_ENV_ALLOWunsetExtra environment variable names passed through to shell runs, beyond the scrubbed baseline
VENIRA_SHELL_CACHE"1"Cache read-only shell results
VENIRA_SHELL_CACHE_READ_ONLY"1"Compatibility flag (shell output caching is always read-only — nothing mutating is ever cached)
VENIRA_CONFIG_FILEunsetExplicit path of the JSON config file (git provider settings); never auto-read from a workspace
VENIRA_WORKSPACE_ROOTSunsetAllowlist of roots switch_workspace may reach under strict/balanced (absolute paths, both , and ; separators). Unset = locked to the spawn workspace. Ignored under trusted/off/VENIRA_UNRESTRICTED=1 (those switch to any existing directory)
VENIRA_CACHE_LIST_ONLYunsetEnable only the directory-listing cache
VENIRA_CACHE_SEARCH_ONLYunsetEnable only the search cache
VENIRA_LIST_CACHE_MS1500Directory-listing cache lifetime
VENIRA_NEGATIVE_CACHE_MS500Lifetime of cached not-found results
VENIRA_RECENT_CACHE_MS2000recent_files cache lifetime
VENIRA_SEARCH_CACHE_MS3000Search cache lifetime
VENIRA_TTL_CACHE_BYTES8388608Size cap of each list / search / recent / references cache
VENIRA_CACHE_RACY_MS30Files modified this recently are re-read instead of served from the read cache (0 disables)
VENIRA_READ_CACHE_BYTES67108864Total size cap of the file-read cache
VENIRA_AUDIT_STRICT"0""1" fails a tool call when its audit row cannot be written (default: audit failure is a warning)
VENIRA_AUDIT_KEEP_DAYS90Audit rows older than this many days are pruned
VENIRA_SNAPSHOT_MAX_BYTES536870912Total size cap of a project checkpoint
VENIRA_SNAPSHOT_MAX_FILE_BYTES33554432Largest single file a checkpoint captures
VENIRA_SNAPSHOT_MAX_FILES0File-count cap of a checkpoint (0 keeps the built-in limit)
VENIRA_GIT_MAX_BYTESbuilt-inLargest provider API response accepted
VENIRA_GIT_LOG_MAX_BYTESbuilt-inTotal CI log bytes returned per call
VENIRA_GIT_MAX_REDIRECTSbuilt-inRedirects followed (same-origin only)
VENIRA_GIT_ALLOW_HTTP"0"Allow plain-HTTP provider URLs (tokens may travel in clear text)
VENIRA_GITHUB_ALLOW_HTTP"0"Deprecated alias of VENIRA_GIT_ALLOW_HTTP; the GIT_* name wins, prints a one-time note
VENIRA_GIT_ALLOWED_HOSTSunsetExtra API hosts the provider client may call
VENIRA_GIT_API_URLunsetProvider API base URL (self-hosted instances)
VENIRA_GITHUB_API_URLunsetDeprecated alias of VENIRA_GIT_API_URL; the GIT_* name wins, prints a one-time note
VENIRA_GIT_PROXYunsetHTTP(S) proxy for provider calls
VENIRA_GIT_REPOunsetRepository slug override (owner/name)
VENIRA_GITHUB_REPOunsetGitHub repository slug override
VENIRA_GITLAB_REPOunsetGitLab project path override
VENIRA_BITBUCKET_REPOunsetBitbucket repository slug override
VENIRA_GIT_SECRET_NAMEunsetName of the stored secret holding the provider token (default GITHUB_TOKEN)
VENIRA_GIT_TOKEN_ENVunsetName of another environment variable holding the provider token (e.g. GITHUB_TOKEN)
VENIRA_GIT_USERNAMEunsetUsername for providers that need one (Bitbucket app passwords)
VENIRA_GITHUB_TOKENunsetGitHub token (falls back to GITHUB_TOKEN / GH_TOKEN)
VENIRA_GITLAB_TOKENunsetGitLab token (falls back to GITLAB_TOKEN / GL_TOKEN)
VENIRA_BITBUCKET_TOKENunsetBitbucket token (falls back to BITBUCKET_TOKEN / BB_TOKEN)
VENIRA_SECRET_KEYCHAIN"auto"Windows keychain for the secret store key (auto / off / required)
VENIRA_TRACE_FILEunsetAlso append the trace to this file (rotates at 10 MB)

7. Security model

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!