Skip to content

installation.md

Latest commit

 

History

History
66 lines (40 loc) · 5.58 KB

installation.md

File metadata and controls

66 lines (40 loc) · 5.58 KB
Raw

Installation and provider onboarding

Choose your host:

npx --yes github:thehan-co/jevriel install codex
npx --yes github:thehan-co/jevriel install claude

Requirements: Node.js 20+, npm, Git and the host CLI. Python 3.10+ is needed only for the public benchmark. This installs the npm executable from GitHub; it is not an npm-registry publication.

The Codex installer copies the plugin to ~/plugins/jevriel, preserves personal marketplace entries and installs it. Claude adds the repository's marketplace and plugin. Start a new host session after installation.

Choose where JEV runs

Onboarding asks for your API source: Cloudflare, TypeSafe direct, OpenRouter, a compatible HTTPS endpoint, a custom adapter, or your existing MCP. Credentials belong to that provider. There is no mandatory TypeSafe account and no automatic paid fallback. Provider options and adapter contract.

npx --yes github:thehan-co/jevriel setup
# Or select a route directly:
npx --yes github:thehan-co/jevriel setup --provider cloudflare
npx --yes github:thehan-co/jevriel doctor

Interactive setup requests credentials in a hidden terminal prompt, never in chat. Optional local credentials are stored as plaintext with owner-only permissions in ~/.config/jevriel/provider.json. Use environment injection from your secret manager if preferred. JEVRIEL_CONFIG_DIR changes the directory. For older TypeSafe-only setups, the legacy credentials file remains readable when selecting TypeSafe.

Setup makes one small verification request under your selected provider's quota/billing. Unattended installs with incomplete configuration finish as setup-required. Selecting an existing MCP skips credential migration and verification calls; the skill uses that connector, while bundled inference remains disabled.

A compatible endpoint receives only its explicitly configured credential. HTTPS redirects are rejected. Custom adapters run trusted local commands without a shell. They are the extension point for APIs with different authentication or payload formats; arbitrary APIs are not assumed to share a contract.

Pricing and runtime controls

Actual provider charges and free allowance are distinct from the TypeSafe published reference estimate. The plugin cannot infer that an account has remaining free quota. Choose auto/enabled/disabled with jevriel_session_mode; enabled never overrides user permissions or chooses another provider.

Metadata receipts go to ~/.local/state/jevriel/usage.jsonl; configure JEVRIEL_LEDGER_DIR to change that home. No source text, answers or credentials are stored in the ledger. No automatic community upload exists.

Interactive installation also offers Light or Deep adoption. Deep writes a persistent pointer only after you choose the host instruction file. Noninteractive installs preserve the existing preference and never silently opt into Deep.

The default benchmark uses your selected JEV provider, plus a separate hosted OpenRouter LLM key for the baseline. An existing chat subscription is not inferred to cover either API.

Updates, existing connectors and qualification

Rerun the installer to update. Existing Jev/JEV MCP installations are retained. The skill can use them after inspecting their contracts; installing this plugin does not prove replacement parity.

Use the host's removal command to disable the plugin. Local configuration and receipts remain yours. Codex installation and offline tests are recorded in the release QA file. Cloudflare/OpenRouter contract fixtures and Claude manifest validation do not imply completed live provider tests or frontier-model certification.

Already connected? Skip new credentials

If your agent already has a working JEV MCP, run npx --yes github:thehan-co/jevriel setup --provider existing. JEVRIEL supplies the skill while that MCP makes the requests. This does not migrate credentials or change the existing provider. Bundled inference and its default benchmark adapter remain disabled; use the existing connector or a configured custom benchmark adapter.

Interactive setup lists this route first. For a failed direct connection, HTTP 401 means authentication failed; HTTP 403 means access denied; HTTP 429 means rate/quota limit. Replace a saved token with npx --yes github:thehan-co/jevriel setup --replace-key. Keys stay out of command arguments and chat.

Any file/terminal-capable AI

npx --yes github:thehan-co/jevriel install portable --skip-setup
npx --yes github:thehan-co/jevriel setup --provider openrouter
node "$HOME/.local/share/jevriel/bin/jevriel.mjs" doctor
node "$HOME/.local/share/jevriel/bin/jevriel.mjs" judge --input packet.json

Portable installation places the skill at ~/.agents/skills/jevriel and the runtime at ~/.local/share/jevriel. Hosts that use another skill directory can read/copy the skill there. A generic MCP host can register command node with the absolute ~/.local/share/jevriel/server/index.mjs path (expand ~ yourself). The bundled stdio server uses Node built-ins; the optional MCP SDK is for benchmark clients, not server startup.

The JSON packet contains state and questions. Use --input - for stdin. The CLI and MCP share the same selected provider, validation and metadata ledger. CLI stdout contains results for your own storage; stderr reports failures without printing malformed input. See the runnable daily triage example.

Choose Light or Deep adoption. Light is manual invocation. Deep explicitly installs a persistent instruction hook so the agent considers JEV throughout its workflows. Installation alone never enables Deep.