Getting started

From a clean machine to a verified Oracle chat in a few minutes. The default path needs a model login, not a wallet key.

Run doctor before preparing a live action.
Treat a degraded provider as unavailable, not healthy.
Do not put keys in command arguments, shell history, screenshots, or Oracle chat.

LinuxmacOSWindows beta

Requirements

Node.js 20.19.0 or newer
npm
A supported model OAuth login or API key
A user-controlled wallet only when you want to sign a prepared action

Install Oracle

recommended

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

The installer writes to ~/.local/share/oracle and exposes oracle through ~/.local/bin. Re-run the installer to upgrade.

npm alternative

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

Configure a model

Run the interactive model picker. OAuth is available for Claude, Codex, and Grok. API-key providers include OpenRouter, OpenAI, Anthropic, xAI, DeepSeek, Gemini, Kimi, Mistral, Nous Portal, Qwen, GLM, and compatible endpoints.

terminal

oracle setup model

# direct OAuth choices
oracle setup model claude
oracle setup model codex
oracle setup model grok

# safe status, never prints credentials
oracle auth status
oracle model --show

Keep credentials out of argv

Interactive API-key entry is hidden. Do not put keys in command arguments, shell history, screenshots, or Oracle chat.

First run

Open Oracle

Run oracle or oracle chat. First-run onboarding can select a chain and opens the native agent loop.

Select a chain

List supported chains, select one, and inspect the active selection.

Verify the posture

Run doctor before preparing a live action. Treat a degraded provider as unavailable, not healthy.

terminal

oracle
oracle chain list
oracle chain use hyperliquid
oracle chain show
oracle doctor

Useful in-chat commands include /sessions, /new, /resume, /chain, /model, /setup, and /help.

Update or remove

Re-run the curl installer to upgrade a user-local installation. For npm installs, update the package through npm.

update

curl -fsSL https://oracle.demi.la/install.sh | bash
# or
npm i -g @oracle-agent/oracle@latest

Before removing Oracle, export anything you need from your local config. Never copy vault files into a public backup.

Server credentials in 0.36.0

Public and hosted requests spend no server keys by default. The operator can opt in named providers with ORACLE_PUBLIC_ALLOW_SERVER_KEY_PROVIDERS, a comma-separated, whitespace-trimmed, case-sensitive list of canonical IDs. Empty is the default; there is no wildcard grant.

The legacy MAD_PUBLIC_ALLOW_SERVER_KEY_PROVIDERS is read only when the Oracle variable is unset or exactly empty. Any other Oracle value takes precedence, even whitespace or commas only, which then grants nothing. Source: credential sink rules (packages/oracle/src/data/http.mjs, revision 12f21dd5).

Request alias	Canonical opt-in ID
0x	zerox
1inch	oneinch
opensea	opensea-nft
magiceden	magiceden-sol

Aliases still normalize on requests, but alias entries in the operator list are refused with the canonical replacement; independent valid entries remain effective.

Voice uses openai or elevenlabs; watched portfolio RPC overrides use evm-rpc. An aggregator grant does not cover its dependencies. Sources: credential sink rules (packages/oracle/src/data/http.mjs, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).

oracle public serve and the public MCP handler always apply the public allowlist policy, regardless of public-mode environment flags. Setting ORACLE_PUBLIC_ALLOW_SERVER_KEY_PROVIDERS therefore means unauthenticated callers of those surfaces can spend the listed providers' server keys; that is the operator's opt-in.

Verified local CLI/stdio owner entry points and authenticated local HTTP/app requests retain credential access. On local owner surfaces (CLI, desk, app and charts) outside public/hosted mode, an anonymous local request needs owner authentication to spend server credentials; the allowlist does not grant it there.

Missing request scope is anonymous, and HTTP listeners discard launcher authority. Public/hosted mode requires operator opt-in even with owner tokens. Existing authentication, origin checks, caps and operation restrictions still apply.

Sources: credential sink rules (packages/oracle/src/data/http.mjs, revision 12f21dd5), app authority (apps/oracle-app/lib/oracle/swap-server-keys.ts, revision 12f21dd5), public HTTP authority (packages/oracle/src/public-api/http.mjs, revision 12f21dd5), public MCP handler (packages/oracle/bin/oracle-data-mcp.mjs, revision 12f21dd5).

A configured endpoint may contain credentials in its host, path or query. Without authority, Oracle uses a reviewed built-in public default or refuses before upstream work.

Even a keyless private/loopback endpoint can fall back to a third party, exposing requested addresses there. Authenticate as local owner to retain the configured endpoint. Source: credential sink rules (packages/oracle/src/data/http.mjs, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).