# Oracle setup

Oracle's public CLI reads, prepares, arms, signs, and broadcasts under owner
policy. Signing is the user wallet or `oracle signer` after an encrypted local
vault and sealed policy exist. Hosted web stays keyless. The private
`@oracle-agent/agent` package is not imported.

## Requirements

- Node.js `20.19.0` or newer
- npm
- A supported model login or API key for chat
- A user-controlled wallet, external or in the optional encrypted local vault

## Local self-hosted signer

Never paste a key or passphrase into Oracle, chat, or argv. Use a hidden TTY or
owner-only (`0600`) files:

```bash
oracle sign init
oracle sign import --key-file /protected/key --passphrase-file /protected/passphrase
oracle sign policy --policy-file /protected/policy.json
oracle sign doctor
oracle signer --credential-service oracle-local-signer --session-seconds 120
# protected-file fallback, and the required Windows behavior:
oracle signer --passphrase-file /protected/passphrase --session-seconds 120
oracle sign lock
```

Configure and HMAC-seal `~/.config/oracle/signer/signer-policy.json` with non-empty surface, action, chain,
destination, selector, spender, and owner allowlists plus explicit value,
approval, gas/fee, slippage, expiry, and RPC bounds. Empty allowlists fail
closed. Exact one-use confirmation binds the final gas-populated artifact. For
reviewed EVM swap/bridge batches the TTY review is decoded from calldata and
shows each approval's token/spender/amount, the reviewed provider, input/output
tokens, amount in, minimum out, recipient, bridge destination chain/asset, and
aggregate gas/value/maximum fee before asking for the digest. Caller summary
metadata is never used for this review. The decoded minimum out must exactly
match a fresh HMAC-authenticated auto-slippage quote bound to the full calldata;
the caller's `slippageBps` label is not authority. Swap and allowance selectors
known elsewhere in Oracle either use this strict decoded batch path or fail
closed on generic/unversioned EVM surfaces. Generic approvals are refused rather
than prompting without the exact token, spender, and amount. The artifact is checked again
immediately before broadcast. Lock/disarm always wins.

Autonomous mode additionally requires an Ed25519 trigger authority that is
separate from the signer and its HMAC policy-integrity key. Provision only that
authority's PEM public key as owner-only
`~/.config/oracle/signer/trigger-attestation-authority.pub`; keep the private key
outside the signer config and signer process. A trigger authority signs canonical
JSON containing exactly `triggerId`, `issuedAtMs`, `expiresAtMs`, and the final
`artifactDigest`, and sends `algorithm: "ed25519-canonical-json-v1"` plus the
base64 signature. `ORACLE_AUTONOMOUS_TRADING=1` does not bypass this verification.
The public `@oracle-agent/oracle/local-signer` export contains neither attestation
minting nor filesystem key-reading helpers.

Service templates ship under `public/service/` for Linux systemd, macOS
launchd, and Windows Task Scheduler/PowerShell. Linux/macOS can retrieve the
passphrase from the logged-in user's keyring; Windows currently requires an
ACL-protected file. Installation is deliberately not automatic. Never put a
passphrase in service argv or an inherited environment.

Linux, Windows, and macOS apps are in beta.

## 1. Install the standalone CLI

```bash
curl -fsSL https://oracle.demi.la/install.sh | bash
oracle --version
```

This installs into `~/.local/share/oracle` and puts `oracle` on `~/.local/bin`
(no sudo, no global `npm -g`). Re-run the same command to upgrade.

On an interactive terminal the installer prints a small ASCII globe banner
while it works. When stdout isn't a TTY (piped through another script, CI,
`TERM=dumb`, or `NO_COLOR` set), it skips the globe and stays to plain
`oracle-install: ...` log lines instead. Set `ORACLE_INSTALL_PLAIN=1` to force
the plain form even on an interactive terminal.

npm still works if you prefer:

```bash
npm i -g @oracle-agent/oracle
oracle --version
```

The package declares this floor through `engines`; `oracle doctor` treats an
unsupported Node runtime as blocking. npm may only warn unless the user's npm
configuration enables strict engine checks, so verify `node --version` yourself.

## 2. Authenticate a model provider

List every standalone choice with safe status and copyable setup commands:

```bash
oracle setup model
```

### OAuth

```bash
oracle setup model claude
# or
oracle setup model codex
oracle setup model grok
```

The command opens the provider's authorization flow and selects its default
model. Use `--no-browser` when the browser must be opened manually.

### API key

```bash
oracle setup model openrouter
oracle setup model qwen
oracle setup model glm
oracle setup model nous
# also supported: openai, anthropic, xai, deepseek, gemini, kimi, mistral, nous, custom
```

Interactive API-key entry is hidden. Do not put a key directly in the command
line, shell history, a screenshot, or Oracle chat. For controlled automation,
pipe the secret over stdin instead of passing it as an argument:

```bash
printf '%s\n' "$OPENROUTER_API_KEY" | oracle auth api-key openrouter --stdin
```

Check configuration without revealing credentials:

```bash
oracle auth status
oracle model --show
```

OAuth credentials and stored API keys use the OS credential store when
available, with a private `0600` local fallback.

## 3. Open Oracle

```bash
oracle
```

On a fresh TTY, the first `oracle`/`oracle chat` run walks through, in order:

1. Model setup (`oracle setup model`) if no provider is configured yet —
   OAuth first (`claude`, `codex`, `grok`), then API-key providers.
2. The onboarding splash: a welcome panel with the orb, Enter opens the
   chain picker, arrow keys + Enter select a chain (Esc skips at either
   screen), then a ready card. It shows once per install and is marked done
   under `ORACLE_CONFIG_DIR`; `ORACLE_ONBOARDING=0` skips it, `oracle chat
   --onboard` replays it.
3. Chat itself.

Useful first commands:

```bash
oracle chain list
oracle chain use hyperliquid
oracle chain show
oracle doctor
```

Inside chat:

- `/sessions`, `/new [title]`, `/1`–`/9`, `/resume [n]`, `/session rm <n>` —
  manage numbered chat sessions.
- `/chain` lists or selects the active chain.
- `/model` changes the model without changing the Oracle persona.
- `/setup` opens optional messaging setup.
- `/help` lists every in-chat command.

Chat always runs on Oracle's own native loop unless you explicitly opt into
Hermes with `ORACLE_CHAT_BACKEND=hermes` (or `oracle chat --backend
hermes`); the default `auto` resolution never selects Hermes on its own, and
an explicit `hermes` request fails closed with an actionable error if Hermes
isn't actually detected.

A model response is not authorization, a prepared object is not a transaction,
and a submitted transaction is not a confirmed receipt.

## Public capability boundary

| Surface | Available to a public install | Custody |
|---|---:|---|
| Chat, research, market data | yes | none |
| Quotes and simulations | yes | none |
| Unsigned transaction / typed-data preparation | yes | user's wallet reviews and signs |
| Signing, submission, broadcast | optional self-host only | encrypted local vault, sealed policy, exact local confirmation |
| Automatic trading | explicit self-host only | exact env `1`, autonomous policy mode, and verified trigger attestation |

Never paste a seed phrase, private key, hardware-wallet recovery phrase, vault
passphrase, signer token, bot token, or provider credential into chat.

## Optional Hermes integration

Hermes is optional. Add it only if you want specialist profiles, messaging
channels, durable sessions, or the MCP-based local read plane:

```bash
oracle bootstrap
oracle init                 # dry run
oracle init --apply
oracle data serve
oracle doctor
```

`oracle bootstrap` installs an isolated Hermes compatibility runtime under
Oracle's config directory and never modifies system Python. `oracle init
--apply` writes profiles and a local HMAC attestation secret; it does not write a
wallet key.

The data service binds to `127.0.0.1:8787`. Keep it on loopback.

## Optional public HTTP plane

```bash
oracle public serve --port 8799
```

The public plane binds to `127.0.0.1` and exposes read, connect, grant,
portfolio, approval, prepare, Buzz-auth, and audit contracts. It has no signer,
key, send, execute, or broadcast route.

The service is rate limited but unauthenticated and must not be exposed directly
to the internet, LAN, or tailnet. A hosted deployment needs a controlled reverse
proxy, TLS, edge limits, authentication, and per-user isolation.

Verify liveness only after starting it:

```bash
curl -fsS http://127.0.0.1:8799/public/health
curl -fsS http://127.0.0.1:8799/public/buzz
```

A static Oracle website does not imply that this API is running.

## Optional messaging

```bash
oracle setup
oracle setup telegram --allowed-users <telegram-user-id>
oracle setup status
oracle setup gateway start
```

Interactive bot-token entry is hidden. Do not use `--token` in a normal shell;
arguments can be retained in history or visible to other local processes. Do not
run one shared messaging bot without authentication and per-user session isolation.

## Public wallet addresses and portfolio reads

Portfolio and approval reads use public addresses only:

```bash
export ORACLE_EVM_ADDRESS=0x...
export ORACLE_SOLANA_ADDRESS=...
export ORACLE_BITCOIN_ADDRESS=bc1...
export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional; EVM address is the fallback
oracle data serve
```

Missing address families are reported as `not-configured`, provider failures as
`unavailable`, and unsupported families as `unsupported`. They are never
reported as zero. Portfolio history is stored profile-locally with mode `0600`
and contains public-address fingerprints and value observations, not wallet
keys or prepared transactions.

## Preparing an action

Preparation requires the real wallet that will sign. Placeholder and burn
addresses are rejected.

```js
import { data } from "@oracle-agent/oracle";

const prepared = await data.call("hl-perps", "prepareOrder", {
  /* exact market, side, size, limits, and owner wallet */
});
```

Review the chain, destination, calldata or typed data, amount, minimum output,
expiry, approvals, and fees. Hosted/default Oracle stops before signing and
hands the artifact to a user-controlled wallet. A self-hoster who initialized
`oracle signer` may sign that same reviewed artifact locally. Report success
only after a real transaction hash, successful receipt, and expected balance or
state change.

## Locals Only fee waiver

Oracle access is public. A Locals Only NFT only waives Oracle's integrator fee.
Use `oracle fees status` to check the configured wallet. See
[locals-only-fee-waiver.md](docs/locals-only-fee-waiver.md).

## Hyperliquid builder code

Eligible Hyperliquid core perpetual orders disclose a 2 bps builder fee before
wallet review; HIP-3 and HIP-4 use 1 bps. A verified Locals Only holder receives
a 0% Oracle rate. The main wallet must separately sign the revocable maximum-fee
approval; Oracle only prepares that unsigned action. See
[hyperliquid-builder-code.md](docs/hyperliquid-builder-code.md).

## Buzz integration

Oracle includes a public, unsigned Buzz HTTP contract. It does not embed the
private executor and it does not turn Buzz into a custody surface. Setup,
endpoints, and deployment status rules are documented in
[buzz-integration.md](docs/buzz-integration.md).

## Doctor output

```bash
oracle doctor --json
```

A clean standalone install can legitimately show warnings for:

- `data_server` when `oracle data serve` is not running;
- `agent_runtime` when optional Hermes is not installed;
- `hermes_lanes` before optional `oracle init --apply`.

A Node-version failure is blocking. Signing warnings from `oracle doctor`
refer to signer setup, not hosted web. Hosted web never signs.
`oracle sign doctor` and `oracle signer` are the local sign path.

## Upgrade

Re-run the same installer you used. Curl is the default:

```bash
curl -fsSL https://oracle.demi.la/install.sh | bash
oracle --version
oracle doctor
```

If you installed with npm:

```bash
npm i -g @oracle-agent/oracle@latest
oracle --version
oracle doctor
```

`oracle upgrade` updates installed Hermes agent lanes. It does not replace the
CLI package.

Review release notes before upgrading a machine that also runs private
owner-operated infrastructure.

## Uninstall

Curl install:

```bash
rm -f ~/.local/bin/oracle ~/.local/bin/oracle-data-mcp
rm -rf ~/.local/share/oracle
```

npm install:

```bash
npm rm -g @oracle-agent/oracle
```

The CLI does not silently delete local configuration or credentials. Remove
those separately only after confirming they are no longer needed.

## Build and test from source

```bash
git clone https://github.com/demi-hl/oracle.git
cd oracle
npm ci --no-audit --no-fund
npm run gate:release
npm run test:boundary
npm test
npm run typecheck
npm run build
npm run scan:secrets
```

The repository may be private or ahead of npm while a release is being staged.
The npm artifact remains the public installation source.

## Troubleshooting

### `oracle` says no provider is configured

Run `oracle auth login <provider>` or `oracle auth api-key <provider>`, then
confirm with `oracle auth status`.

### `oracle setup` says the local runtime is missing

Messaging uses optional Hermes. Run `oracle bootstrap`, then retry setup.
Standalone chat, chain selection, and public read/prepare commands do not require
Hermes.

### `oracle doctor` says the data server is down

Start it in another terminal with `oracle data serve`. Do not expose port `8787`
off-host.

### The public API or Buzz endpoint is unreachable

Start `oracle public serve --port 8799` and verify `/public/health`. Do not claim
the API is live based on the static site or source code alone.

### A prepared action cannot be signed

Hosted/default Oracle is prepare-only: hand the reviewed artifact to a
user-controlled wallet. Do not install private Administrator infrastructure
as a workaround. A self-hoster who already initialized `oracle sign` /
`oracle signer` signs locally under that policy.

## References

- [CLI reference](docs/cli.md)
- [Public API and environment surface](docs/public-surface.md)
- [Locals Only 0% fee waiver](docs/locals-only-fee-waiver.md)
- [Buzz integration](docs/buzz-integration.md)
- [Architecture](docs/architecture.md)
- [Security policy](SECURITY.md)