# How to Install and Configure Oh-My-Pi (OMP): A Terminal AI Agent Setup Guide > AI Release · @ai_release1 · https://ai-release.org/guides/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen_en.html ## TL;DR - **Time to complete:** 20–30 minutes - **Difficulty:** Intermediate - **You need:** - A terminal: macOS, Linux, or Windows (PowerShell 7 or WSL) - Node.js + npm installed (required version = whatever the package's `engines` field says — check the documentation) - An API key from an LLM provider that OMP supports (check the documentation for the supported provider list) - About 200 MB of free disk space for a global npm package and its dependencies - One empty scratch project folder that the agent is allowed to touch **Important about values in this guide.** The source material does not pin a package name, a version, a config path, or a model ID for OMP. Everything that cannot be verified is written as a placeholder — ``, ``, ``, `` — and flagged **"check the documentation"**. Replace each placeholder before running a command. Never guess a package name from memory: the registry check in Step 1 tells you the real one. ## Requirements and setup ![Illustration: Requirements and setup](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen-en-1.jpg?v=1792918387) **What to do:** confirm your runtime, then read the package metadata straight from the npm registry so you know the exact package name, the required Node version, and the name of the binary you will type. **Why:** CLI agents (command-line tools that run inside your terminal and act on your files) are distributed as npm packages. Installing the wrong Node version or typing a binary name that does not exist produces errors that look like tool bugs but are just environment mistakes. - Operating system: macOS 13+, a current Linux distribution, or Windows 10/11 with PowerShell 7 or WSL2 - Node.js LTS and npm — `node --version` must return a version that satisfies the `engines` constraint of the package - Write access to your user home directory (`~/.config`, `~/.local`) — no `sudo` needed if npm is configured for a user prefix - An API key stored as an environment variable (a named value your shell passes to every program it launches), **not** inside a file you commit - A project folder you are happy to have the agent read, e.g. `~/projects/omp-demo` - Network access to the npm registry and to your provider's API endpoint **How to check:** ```bash node --version npm --version ``` Expected: two lines, e.g. `v20.11.1` and `10.2.4`. Any numbers are fine at this stage; what matters is that neither command prints `command not found`. ```bash npm view version engines bin ``` Expected output shape (your values will differ — treat the actual numbers as authoritative): ``` version = 'x.y.z' engines = { node: '>=x' } bin = { omp: 'bin/omp.js' } ``` The `bin` line is what you type afterwards. If it says `bin = { 'omp-cli': ... }`, then the command is `omp-cli`, not `omp`. **Check the documentation** for the canonical command name. Now export the key for the current shell: ```bash export OMP_API_KEY="" printenv OMP_API_KEY | wc -c ``` Expected: a number greater than 1 (the character count of your key). Use `wc -c` instead of plain `printenv` when screen-sharing, because the raw command prints the secret to your terminal. To persist it across sessions: ```bash echo 'export OMP_API_KEY=""' >> ~/.bashrc && source ~/.bashrc ``` On Windows PowerShell, `setx OMP_API_KEY ""` works but only affects **new** shells — close and reopen the window before testing. ## Step 1. Install the CLI and confirm the binary **What to do:** create the workspace folder, install the package globally, and confirm the binary resolves. ```bash mkdir -p ~/projects/omp-demo && cd ~/projects/omp-demo npm install -g ``` **Why:** a global install (`-g`) puts the launcher on your `PATH`, so you can start the agent from any project folder rather than only from one directory. **How to check:** ```bash omp --version ``` Expected: a single version string such as `x.y.z`, matching the `version` value from the registry query. If you instead see `zsh: command not found: omp`, jump to Troubleshooting case 1 — this is a `PATH` problem, not a failed install. Then confirm the binary can see its own options: ```bash omp --help ``` Expected: a usage block listing subcommands. Look for a `config` or `doctor` entry — that is the supported way to validate your configuration in the next step. If neither exists, **check the documentation** for the correct validation command. ## Step 2. Write and validate the configuration file ![Illustration: Step 2. Write and validate the configuration file](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen-en-2.jpg?v=1792918391) **What to do:** create the config directory, drop in a JSON config that names your provider, model, key variable, and sandboxed workspace, then validate the JSON before you ever start the agent. ```bash mkdir -p ~/.config/omp $EDITOR ~/.config/omp/config.json ``` ```json { "provider": "", "model": "", "apiKeyEnv": "OMP_API_KEY", "workspace": "/home//projects/omp-demo", "approvalPolicy": "ask", "maxTokens": 4096 } ``` **Why each key matters:** | Key | What it controls | How to confirm the correct value | |---|---|---| | `provider` | Which API endpoint OMP calls | Provider list — check the documentation | | `model` | Which model answers | Provider's model list; copy the ID exactly | | `apiKeyEnv` | Name of the env var holding the key | Must equal the variable you exported: `OMP_API_KEY` | | `workspace` | Directory the agent may read and write | Absolute path, no `~` | | `approvalPolicy` | Whether commands run silently or need your OK | `ask` is the safe default for a first run | | `maxTokens` | Cap on response length | Provider plan limits | Two rules that prevent most incidents. First, the key never goes into this file — `apiKeyEnv` stores only the *name* of the variable, so the file is safe to back up. Second, `workspace` is your blast radius: everything outside that path should be off-limits, which is the same safety model used when you [set up subagents and shared permissions for a team of Claude Code agents](https://ai-release.org/guides/claude-code-dlya-komandy-kak-nastroit-subagentov-i-obsc.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). Keep `approvalPolicy` at `ask` until you trust the setup. **How to check:** validate the JSON syntax on its own, without involving OMP: ```bash python3 -m json.tool ~/.config/omp/config.json > /dev/null && echo "JSON OK" ``` Expected: `JSON OK`. A trailing comma produces `json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes` and no output — fix the comma and re-run. Then, if `omp --help` showed a validation subcommand, run it (e.g. `omp config check`) and expect a line confirming the config path and the resolved model. ## Step 3. Run a first task and verify the result ![Illustration: Step 3. Run a first task and verify the result](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen-en-3.jpg?v=1792918401) **What to do:** give the agent a small, safe, verifiable task inside the workspace. ```bash cd ~/projects/omp-demo printf 'hello world\n' > notes.txt omp "summarise the files in this directory" ``` **Why:** a one-shot prompt proves three things at once — that the API key is read, that the provider and model resolve, and that the workspace path is correct. If any of those is wrong, the run fails immediately instead of failing later on a real task. **How to check:** on screen you should see the agent state a plan, pause for your approval if `approvalPolicy` is `ask`, then print an answer that mentions `notes.txt`. Then confirm a clean exit: ```bash echo $? ``` Expected: `0`. Anything non-zero means the run errored — read the last lines of output before changing the config. Final acceptance checklist: - [ ] `omp --version` prints a version string - [ ] `python3 -m json.tool ~/.config/omp/config.json` exits 0 - [ ] The one-shot prompt returns an answer referencing `notes.txt` - [ ] `echo $?` after the run prints `0` - [ ] No new files appeared outside `~/projects/omp-demo` ## Troubleshooting **Problem. The shell cannot find the command after a successful install** - Error: `zsh: command not found: omp` - Cause: npm's global bin directory is not on `PATH` — common when npm uses a user-level prefix, or when you installed Node via a version manager that has not been sourced. - Solution: find the actual directory and append it. ```bash npm prefix -g echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc omp --version ``` Expected: the version string appears after the re-source. **Problem. The global install is refused with a permissions error** - Error: `npm ERR! code EACCES` / `npm ERR! syscall mkdir` / `npm ERR! path /usr/local/lib/node_modules` - Cause: the system Node install is owned by root, and npm will not write there without elevation. - Solution: do **not** use `sudo npm install -g` — it leaves root-owned files behind. Point npm at a directory you own: ```bash mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc npm install -g ``` **Problem. The agent starts but every request is rejected** - Error: `401 Unauthorized` or `Incorrect API key provided` - Cause: the variable is set in one shell but not the one running OMP, the key has a stray space or newline, or the key belongs to a different provider than the one in `provider`. - Solution: verify in the *current* shell, then re-export. ```bash printenv OMP_API_KEY | wc -c printf '%s' "$OMP_API_KEY" | wc -c ``` If the two counts differ, your key has a trailing newline — re-export it without one. If the count matches and the error persists, confirm that `provider` and `model` belong to the same vendor whose key you issued. ## Summary and next steps You now have OMP installed globally, a JSON config that pins the provider, model, and workspace, and a verified one-shot run returning exit code `0`. Next, give the agent a scratch README to rewrite and compare the diff against `git status`, then explore approval policies — and if you want an agent that also drives a browser, read [how to set up the open-source browser agent Scout by Outcrawl](https://ai-release.org/guides/kak-nastroit-otkrytyy-brauzernyy-ii-agent-scout-outcraw.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## FAQ **Do I need Node.js installed to run OMP?** Yes. OMP is distributed as an npm package, so Node.js and npm must be on your machine. Confirm the exact minimum version with `npm view engines` rather than assuming an LTS number. **Where should I store the API key?** In an environment variable such as `OMP_API_KEY`, referenced from the config by name (`apiKeyEnv`). Storing the raw key in `config.json` means it ends up in backups, screen shares, and possibly git. **Can I restrict which folders the agent can touch?** Set `workspace` to a single absolute path and keep `approvalPolicy` at `ask`, so every command is confirmed first. The config schema for additional allow/deny rules is version-specific — check the documentation. **I'd rather not work in a terminal at all — what are the alternatives?** Terminal is not the only option: [DeepSeek Harness Desktop covers installing a desktop agent and adding plugins on Windows and Mac](https://ai-release.org/guides/deepseek-harness-desktop-kak-ustanovit-i-podklyuchit-pl.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide), and there is also a route to [run an on-device assistant directly on a phone](https://ai-release.org/guides/ii-agent-pryamo-na-smartfone-kak-ustanovit-i-polzovatsy.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).