# nebula

> A Mantle-native, policy-aware AI treasury assistant. The AI advises; deterministic code enforces the fund controls. Nebula does real on-chain work on Mantle (balances, transfers, swaps, lending, yield discovery) from the terminal, Telegram, or a web console. Every value-moving action runs through a four-gate pipeline: policy (pure, unit-tested caps and allowlists) -> simulate (dry-run before gas) -> approval (material-risk actions prompt a human even under YOLO) -> execute (broadcast + receipt).

## Install

bun is REQUIRED. Nebula is a Bun + Biome monorepo and the CLI runs on Bun.

```
bun install
export OPENAI_API_KEY=sk-...
bun run nebula init
bun run nebula chat
```

The brain is any OpenAI-compatible model (default `gpt-4o-mini`), swappable via `NEBULA_LLM_BASE_URL` and `NEBULA_LLM_MODEL`. The default identity is a plain EOA; there is no on-chain mint to start.

## For AI agents

The fund-control policy lives in `NEBULA_POLICY_*` environment variables (caps, allowlists, slippage, autonomy tier, read-only), not in the prompt. The model cannot raise a limit, skip a simulation, or grant its own approval; those decisions are deterministic code. Use the Mantle Sepolia testnet (chainId 5003) for exploratory work, then mainnet (chainId 5000). Full install model, anti-patterns, and the safety model: https://nebula.xyz/docs/agents.md

- Full single-file dump: https://nebula.xyz/llms-full.txt
- Per-page raw markdown: https://nebula.xyz/docs/<slug>.md (e.g. https://nebula.xyz/docs/quickstart.md)

## Docs

- [Introduction](https://nebula.xyz/docs/introduction.md): A Mantle-native, policy-aware AI treasury assistant. The AI advises; deterministic code enforces the fund controls.
- [Quickstart](https://nebula.xyz/docs/quickstart.md): Install, configure the brain, init, chat. From zero to a policy-gated agent in a few commands.
- [Architecture](https://nebula.xyz/docs/architecture.md): A Bun monorepo. An advisory brain, a deterministic control layer, and a four-gate write pipeline on Mantle.
- [Identity](https://nebula.xyz/docs/identity.md): The agent is a plain EOA with a local encrypted keystore. No on-chain mint required to start.
- [Memory](https://nebula.xyz/docs/memory.md): A local, content-addressed store. Markdown notes plus an index, kept on the operator's machine.
- [Brain](https://nebula.xyz/docs/brain.md): Any OpenAI-compatible model. Advisory only, never the safety boundary.
- [Tools](https://nebula.xyz/docs/tools.md): The Mantle limbs plus the host harness. Reads run freely; every write crosses the gates.
- [CLI](https://nebula.xyz/docs/cli.md): The nebula binary. Init an agent, chat, bridge Telegram, run the gateway.
- [Configuration](https://nebula.xyz/docs/configuration.md): Configure the brain and the fund-control policy entirely from the environment. No code changes.
- [Console](https://nebula.xyz/docs/console.md): A browser-side operator dashboard. Sign in with your wallet, then observe and audit your agent.
- [For Agents](https://nebula.xyz/docs/agents.md): How AI agents (Claude Code, Codex, Cursor) install and operate Nebula for a human. What works, what to hand back, what never to claim.

## Reference

- README: https://github.com/rstfulzz/nebula#readme
- Console: https://nebula.xyz/console
- Releases: https://github.com/rstfulzz/nebula/releases
- Networks: mainnet chainId 5000 (https://rpc.mantle.xyz, https://mantlescan.xyz), Sepolia testnet chainId 5003 (https://rpc.sepolia.mantle.xyz, https://sepolia.mantlescan.xyz)
- Gas token: MNT
- Integrations: Agni Finance (trading), Aave V3 (lending), DeFiLlama (yield discovery, read-only)