# Install Omnius

This guide gets a machine ready to run Omnius from npm or from the workspace.

## Requirements

- Node.js 22 or newer
- npm 10 or newer for published CLI use
- pnpm 9 or newer for workspace development
- A local model endpoint, remote OpenAI-compatible endpoint, or sponsor/peer endpoint

## Install From npm

```bash
npm install -g omnius
omnius
```

No compiler toolchain is required for the base install. Omnius installs its
AIWG companion separately without optional native indexing modules, so missing
`make`, C++, or Python cannot abort installation of the CLI.

If npm completes but the shell cannot find `omnius`, npm's global command
directory is not on that shell's `PATH`. Repair the current shell with:

```bash
export PATH="$(npm prefix -g)/bin:$PATH"
hash -r
omnius --version
```

Persist the same export in your shell profile (or open a new terminal after
configuring nvm/fnm). You can use `npx omnius@latest` immediately without
waiting for a profile reload.

The first launch opens the setup flow, probes local capabilities, and asks which endpoint and model path to use.

The installer prints a short agent-discovery primer. It does not print keys or
other secrets. You can run the discovery commands at any time:

```bash
omnius discover "bring your own inference"
omnius show tool.web-search
omnius docs
omnius init
```

`omnius init` adds a managed Omnius discovery block to the project guidance
files without replacing content outside that block. `--check` reports whether
the guidance is current and `--dry-run` previews changes.

## Start The REST Daemon

```bash
omnius serve
```

Default daemon URL:

```text
http://127.0.0.1:11435
```

Open API docs:

```text
http://127.0.0.1:11435/docs
```

Agent-readable daemon entrypoints:

```text
http://127.0.0.1:11435/help
http://127.0.0.1:11435/openapi.json
http://127.0.0.1:11435/v1/discovery/bootstrap
http://127.0.0.1:11435/v1/tools
http://127.0.0.1:11435/v1/skills
```

## Start Automatically On Linux

Omnius supports a systemd service running as your normal account. To install and enable a system service from your current CLI installation:

```bash
sudo env "PATH=$PATH" "$(command -v omnius)" daemon install --system --user "$USER" --enable
```

If an older user service is running, stop and disable that owner before starting the system service:

```bash
systemctl --user disable --now omnius-daemon.service
omnius daemon start --scope system
omnius daemon status --json
```

The service waits for its required filesystem mounts and network, uses a private `~/.config/omnius/daemon.env` for optional overrides, and allows up to two minutes for graceful shutdown. Explicit `omnius daemon stop`, `restart`, `enable`, and `disable` commands use the installed service scope. Install with `--scope user --enable --start` instead for a per-user service.

Linux service installation also registers the Omnius tray indicator with the graphical session. A headless boot starts only the daemon; desktop login starts its tray companion. Registered Telegram workspaces start automatically unless disabled or paused. Manage them through the daemon's Projects page or the tray's Telegram menu.

## Workspace Development

```bash
pnpm install
pnpm -r build
pnpm docs:check
```

Useful focused checks:

```bash
pnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts
pnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts
```

## Runtime State

Omnius stores project runtime state under `.omnius/`. This directory includes settings, jobs, context, sponsor state, scoped Telegram persona state, and generated connector artifacts.

Do not commit `.omnius/`. Omnius adds it to `.gitignore` automatically for repositories that have or later create a `.gitignore`.

## Recover A Blocked Automatic Update

If an older installation repeatedly opens **Waiting for the update worker**,
use another shell in the affected project to disable automatic installation:

```bash
omnius config set updateMode manual
omnius config set updateMode manual --local
```

Close and relaunch the TUI. Manual mode still reports available releases; it
installs only when requested. After installing a release with the recovery fix,
`/update auto` restores automatic updates.

On Linux, update recovery checks the worker's boot and process-start identity.
A valid ownership guard left by a dead process can be recovered after a crash
or reboot. A live, incomplete or replaced guard is retained and reported as an
error with a Close action instead of an indefinite queued dialog. Avoid deleting
the update state or locks while an installer may still be running.

Worker runtime initialization has a 30-second limit before an installer starts.
Package preparation and a running installation retain their own lifecycle; the
initialization limit does not interrupt them. The progress view distinguishes
dispatch, runtime initialization and package preparation. Its elapsed counter
measures time, not proof of worker activity.
