Installation

Install Bun, clone the repo, run the CLIs, configure data/agent.json: everything runs in dry-run until you explicitly provide binaries and keys and turn dryRun off.

One line install


curl -fsSL https://effective-intelligence-app.netlify.app/install.sh | bash

The script is install.sh at the repo root. Read it before you pipe it into a shell, it is short and does exactly this:

Checks the OS and architecture. macOS and Linux, x86_64 or arm64. Windows is refused with a pointer to WSL2.
Checks for git and bun. If Bun is missing, it prints the official command from bun.com/docs/installation and runs it only after you answer yes at the prompt. With no terminal available (CI, non-interactive pipe) it prints the command and exits with a non-zero status instead of installing anything silently.
Clones the repo into the install directory, or git pull --ff-only when it is already a clone. A non-git directory in the way is moved to <dir>.bak.<timestamp> instead of being deleted.
Runs bun install, then bun run src/agent-cli.ts detect so you immediately see your hardware and the matched profile.
Prints the next commands and the docs URL.

Nothing is armed by the installer: the agent stays in dry-run.

Variable	Default	Purpose
`EI_HOME`	`$HOME/.effective-intelligence`	Install directory.
`EI_REPO`	`https://github.com/X-Ventures/effective-intelligence.git`	Git remote. Override it for SSH or a fork.
`EI_NO_RUN`	unset	Set to `1` to skip the hardware detection step.
`NO_COLOR`	unset	Set to disable colored output.

install.sh --help prints the same summary.

Repository access. The GitHub repository is currently private, so an anonymous clone fails by design. The script says so explicitly and exits non-zero. Authenticate first (gh auth login, or an SSH key plus EI_REPO=git@github.com:X-Ventures/effective-intelligence.git), then re-run:


EI_REPO=git@github.com:X-Ventures/effective-intelligence.git \
  sh -c "$(curl -fsSL https://effective-intelligence-app.netlify.app/install.sh)"

Requirements

Bun. The entire project (CLIs, agent, MCP server) runs directly on Bun, no build step.
macOS or Linux. Hardware detection uses sysctl on macOS and /proc plus nvidia-smi on Linux.
Network access to public APIs: WhatToMine, NiceHash, Vast.ai, CoinGecko, DexScreener. No API key is required for read-only planning.

Clone and install


git clone <repo-url> effective-intelligence
cd effective-intelligence
bun install

Run the commands


# Yield Oracle: net USD/day ranking of a hardware profile across mature markets
bun run src/cli.ts --profile rtx-4090 --kwh 0.10

# Network Scorer: in-house risk-adjusted EV of the internal registry
bun run src/score-cli.ts --gpu-baseline 2.9

# Unified planner: THE allocation plan for a machine (primary + stack + total)
bun run src/plan-cli.ts --profile rtx-4090 --kwh 0.10 --ip-slots 1

# Emission window detector (run on a cron, ~15 min interval)
bun run src/watch-cli.ts

# Local agent: hardware detection, plan for THIS machine, run loop
bun run src/agent-cli.ts detect
bun run src/agent-cli.ts plan
bun run src/agent-cli.ts run 15

# MCP server (agent-first funnel) and its smoke test
bun run src/mcp-server.ts
bun run src/mcp-smoke.ts

Supported profiles are defined in src/profiles.ts and include rtx-5090, rtx-4090, rtx-4080, rtx-4070-ti, rtx-4070, rtx-4060-ti, rtx-3090, rtx-3080-ti, rtx-3080, rtx-3070, rtx-3060-ti, rtx-3060, rtx-2080-ti, rtx-2070, gtx-1660-super, r9-7950x, apple-silicon, plus conservative generic fallbacks (generic-gpu, generic-cpu).

Configure data/agent.json

The file is materialized with defaults the first time you run agent-cli:


{
  "kwhUsd": 0.1,
  "ipSlots": 1,
  "dryRun": true
}

Full schema (src/agent/config.ts):

Field	Type	Purpose
`kwhUsd`	number	Electricity price in $/kWh. Used by every net revenue calculation. Default `0.1`.
`ipSlots`	number	Residential IP slots available for the stack (bandwidth and points networks). Default `1`.
`dryRun`	boolean	When `true` (default), drivers log the exact action they would take and touch nothing.
`walletAddress`	string, optional	Settlement target (Base), set at enrollment.
`walletBtc`	string, optional	NiceHash payout address. Required for a real NiceHash miner command.
`walletXmr`	string, optional	Monero pool payout address (RandomX mining).
`minerBinaries`	object, optional	Absolute paths: `{ "xmrig": "/path/to/xmrig", "trex": "/path/to/t-rex" }`.
`vastApiKey`	string, optional	Enables the rental driver to list, reprice and unlist your machines on Vast.ai.
`telegram`	object, optional	`{ "botToken": "...", "chatId": "..." }` for watcher alert push.

Dry-run philosophy

Nothing executes for real until you opt in, twice:

dryRun must be set to false in data/agent.json, and
the relevant binary or key must be present: a miner only spawns if the configured binary path exists on disk; the rental driver only calls the Vast.ai API if vastApiKey is set.

Until both conditions hold, every driver prints the exact command line or API action it would perform, with unconfigured values shown as explicit placeholders such as <WALLET_BTC_NON_CONFIGURE> or <TREX_NON_INSTALLE>. This makes the plan fully auditable before any watt is spent. Missing keys never cause failures: they degrade to logs.