Skip to content
Back to search

milady

terminally online

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/milady-ai--milady/badge.svg)](/listings/milady-ai--milady)

HTML

<a href="/listings/milady-ai--milady"><img src="/api/listings/milady-ai--milady/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

New Environment Setup (recommended)

curl -fsSL https://get.milady.ai | bash
milady setup

Then start Milady:

milady

First run walks you through onboarding:

┌  WELCOME TO MILADY!
│
◇  ♡♡milady♡♡: Hey there, I'm.... err, what was my name again?
│  ● Sakuya
│  ○ Reimu
│  ○ Koishi
│  ○ Marisa
│  ○ Custom...
│
◇  Sakuya: Now... how do I like to talk again?
│  ● uwu~       (soft & sweet)
│  ○ hell yeah   (bold & fearless)
│  ○ lol k       (terminally online)
│  ○ Noted.      (composed & precise)
│  ○ hehe~       (playful trickster)
│  ○ ...         (quiet intensity)
│  ○ lmao kms    (unhinged & dark)
│
◇  Connect a brain
│  ● Anthropic (Claude)
│  ○ OpenAI (GPT)
│  ○ Ollama (local, no key)
│  ○ Skip for now
│
◇  API key?
│  sk-ant-•••••••••••••••••
│
└  Starting agent...

   Dashboard: http://localhost:2138
   Gateway:   ws://localhost:18789/ws

   she's alive. go say hi.

Alternative install paths

Windows:

irm https://get.milady.ai/install.ps1 | iex

NPM global:

npm install -g miladyai
milady setup

Building from source (developers)

Milady builds against the **published `@elizaos/*` npm packages** (`beta` dist-tag) by default. The repo no longer tracks `eliza/` as a submodule — a fresh clone has no `eliza/` checkout and `bun install` resolves everything from npm.

**First install after cloning:**

git clone https://github.com/milady-ai/milady.git
cd milady

./install                 # Unix / macOS — chmod +x install if needed
# install.cmd on Windows
# With no args, the wrapper opens a Space/Enter multi-select picker:
# packages, local elizaOS source, or all developer paths.

# Non-interactive examples:
./install --profile packages
./install --profile local
./install --profile all

# Plain `bun install` is package-mode only and runs a preflight doctor.
# If Node/Python is outside the supported native install lane, run ./install.

elizaOS source modes (eject / uneject)

Milady has two source modes for `@elizaos/*` packages, selected via `MILADY_ELIZA_SOURCE`:

| Mode | When to use | What resolves `@elizaos/*` | |---|---|---| | `packages` (default) | App development, builds, releases | npm registry (`beta` dist-tag) | | `local` | Patching elizaOS upstream alongside Milady | A repo-local `eliza/` checkout linked into `node_modules/` |

**Switch to local mode (uneject)** — clones `eliza/` if absent, links workspace packages, swaps the root tsconfig to source-priority paths:

bun run eliza:local            # clone (or restore) eliza/, link packages, run bun install

**Switch back to packages mode (eject)** — rewrites the root `package.json` to pin npm versions, swaps the root tsconfig back to packages-mode-clean, and regenerates the lockfile:

bun run eliza:packages                  # default: beta tag
bun run eliza:packages:alpha            # explicit alpha (legacy)
bun run eliza:packages -- --tag beta    # any other dist-tag
bun run eliza:packages -- --version 2.0.0-alpha.116   # pin an exact version
bun run eliza:packages -- --rename      # also rename eliza/ → .eliza.ci-disabled/

**What each mode mutates** — both kept in sync by [scripts/lib/tsconfig-mode.mjs](scripts/lib/tsconfig-mode.mjs):

- `tsconfig.json` — sourced from [scripts/templates/tsconfig.packages-mode.json](scripts/templates/tsconfig.packages-mode.json) (default) or [scripts/templates/tsconfig.local-mode.json](scripts/templates/tsconfig.local-mode.json) (local) - `package.json` — rewritten on eject (backup at `package.json.pre-disable-backup`); restored on uneject - `bun.lock` — regenerated on every mode switch - `eliza/` directory — left in place by default; renamed to `.eliza.ci-disabled/` only with `--rename`

The checked-in `tsconfig.json` always matches the packages-mode template; the [standalone contract test](scripts/standalone-eliza-package-contract.test.ts) enforces this invariant. Run `bun run verify:standalone` to check.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 695 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Milady
  2. [![CI](https://github.com/milady-ai/milady/actions/workflows/ci.yml/badge.svg)](https://github.com/milady-ai/milady/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. [![CodeFactor](https://www.codefactor.io/repository/github/milady-ai/milady/badge)](https://www.codefactor.io/repository/github/milady-ai/milady)
  5. > *your schizo AI waifu that actually respects your privacy*
  6. **Milady** is a personal AI assistant that is **local-first by default** and can also connect to **Eliza Cloud** or a **remote self-hosted backend** when you want hosted runtime access. Built on [elizaOS](https://github.com/elizaOS).
  7. Manages your sessions, tools, and vibes through a Gateway control plane. Connects to Telegram, Discord, whatever normie platform you use. Has a cute WebChat UI too.
  8. tl;dr: local AI gf that's actually fast and doesn't phone home
  9. ### Energy and polish (desktop)
  10. Milady is **not** a full IDE: the product bet is **fewer wasted GPU frames and wakeups** when you are not looking at the app—especially **on battery**—while keeping the **companion visually strong** when you are. Background polling, off-screen WebGL, and battery-aware render quality are tuned toward that (see [Desktop — battery and energy](docs/apps/desktop.md#battery-and-energy-use-macos)). Comparing to **Cursor** or other heavy dev tools is **workload-dependent**; the north star is **great UX per watt** for a local assistant, not matching an editor’s surface area.
  11. ### Desktop 3D avatar (Electrobun / Vite)
  12. If the **VRM** or **Gaussian splat** background fails only in the **desktop** build, the usual cause is **two copies of `three`** in the bundle (nested `node_modules` vs repo root), which breaks Spark’s **`splatDefines`** shader chunk. Milady forces **one** Three resolution path in Vite and isolates world-load failures so the **avatar** can still load. **Why it matters:** the companion is an **agent surface** (visibility + voice sync), not decoration. See **[Desktop VRM, Three.js, and Spark — WHYs](docs/apps/desktop-vrm-three-and-spark.md)**.
  13. ### Dashboard chat: progressive action updates
  14. When **actions** call `HandlerCallback` several times in one turn (same idea as Discord **progressive messages**), the Milady API **replaces** the last action-produced segment in the SSE stream instead of concatenating every status line. **Why:** Live status should read like **edits to one message**, not a glued blob. The elizaOS contract stays **`callback({ text, source })`**. **Docs:** [Action callbacks and SSE streaming](docs/runtime/action-callback-streaming.md).
  15. ---
  16. ## BSC / BNB Chain Integration
  17. Milady ships with native **BNB Smart Chain (BSC)** support — your agent can trade tokens, track meme launches, and interact with DeFi on BSC out of the box.
  18. ### Trading (PancakeSwap)
  19. The built-in `EXECUTE_TRADE` action lets your agent swap tokens on BSC via PancakeSwap. Supports buy/sell with configurable slippage.
  20. To enable BSC trading, add to your `.env` or `~/.local/state/milady/.env`:
  21. ```bash
  22. EVM_PRIVATE_KEY=0x... # wallet private key (hex, 0x-prefixed)
  23. ELIZA_TRADE_PERMISSION_MODE=agent # "agent" for autonomous, "user" for manual confirm
  24. ```
  25. Optional RPC configuration (defaults to public BSC RPC):
  26. ```bash
  27. ALCHEMY_API_KEY=... # or use ANKR_API_KEY / INFURA_API_KEY
  28. EVM_RPC_PROVIDER=alchemy # alchemy | infura | ankr | elizacloud
  29. ```
  30. Once configured, just tell your agent: *"buy 0.1 BNB of \<token address\>"* or *"sell all my \<token\>"*.
  31. ### Meme Token Discovery (Binance Skills Hub)
  32. Install the **meme-rush** skill from [Binance Skills Hub](https://github.com/binance/binance-skills-hub) to track meme token launches across BSC and Solana:
  33. - **Meme Rush** — real-time token lists from Pump.fun, Four.meme across new, finalizing, and migrated stages
  34. - **Topic Rush** — AI-powered market hot topics with tokens ranked by net inflow
  35. Install from the Skills Marketplace in the app, or ask your agent to install it.
  36. ### Wallet
  37. Milady auto-generates EVM and Solana wallet addresses on startup. For BSC trading you need to import your own private key (see above). If connected to **Eliza Cloud**, managed wallets via Steward are available without local key management.
  38. View your agent's wallet addresses in the Settings tab or ask: *"what's my wallet address?"*
  39. ---
  40. ## Downloads
  41. ### Desktop App (recommended for normies)
  42. Grab from **[Releases](https://github.com/milady-ai/milady/releases/latest)**:
  43. | Platform | Download | |
  44. |----------|----------|---|
  45. | macOS (Apple Silicon) | [latest macOS installer](https://github.com/milady-ai/milady/releases/latest) | for your overpriced rectangle |
  46. | macOS (Intel) | [latest macOS installer](https://github.com/milady-ai/milady/releases/latest) | boomer mac (why separate arm64/x64: [Build & release](docs/build-and-release.md#macos-why-two-dmgs-arm64-and-x64)) |
  47. | Windows | [latest Windows installer](https://github.com/milady-ai/milady/releases/latest) | for the gamer anons |
  48. | iOS | App Store (coming soon) | for the privacy-pilled |
  49. | Android | [Google Play](https://play.google.com/store/apps/details?id=ai.milady.app) / [APK](https://github.com/milady-ai/milady/releases/latest) | for the degen on the go |
  50. | Linux | [`stable-linux-x64-Milady-Setup.tar.gz`](https://github.com/milady-ai/milady/releases/latest) | I use arch btw — see [Linux install](#linux) |
  51. Signed and notarized. No Gatekeeper FUD. We're legit.
  52. ### Verify (for the paranoid kings)
  53. ```bash
  54. cd ~/Downloads
  55. curl -fsSLO https://github.com/milady-ai/milady/releases/latest/download/SHA256SUMS.txt
  56. shasum -a 256 --check --ignore-missing SHA256SUMS.txt
  57. ```
  58. ### Desktop: reset app data
  59. **Milady → Reset Milady…** (menu bar) confirms in the **native** dialog, then the **main process** calls **`POST /api/agent/reset`**, restarts the agent (embedded or external API), and tells the renderer to apply the **same local state wipe** as the end of Settings reset (onboarding, API client, cloud UI, conversations). **Why main does HTTP:** on macOS/WKWebView, the webview can fail to run **`fetch`** immediately after a native dialog, so a renderer-only reset looked stuck. **Why the renderer still runs teardown:** one implementation of “clear UI + `MiladyClient`” avoids duplicating logic in TypeScript main vs React.
  60. - **Docs:** [Desktop app](docs/apps/desktop.md) (native application menu section), [Main-process reset — WHYs](docs/apps/desktop-main-process-reset.md)
  61. - **Optional network / TTS:** with the agent orchestrator loaded, Edge TTS may call **Microsoft’s cloud** unless you set **`MILADY_DISABLE_EDGE_TTS=1`** — see [Environment variables](docs/cli/environment.mdx#runtime-behavior) and [TTS plugin](docs/plugin-registry/tts.md)
  62. ---
  63. ## Getting Started
  64. ### New Environment Setup (recommended)
  65. ```bash
  66. curl -fsSL https://get.milady.ai | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 109 on GitHub
  67. milady setup
  68. ```
  69. Then start Milady:
  70. ```bash
  71. milady
  72. ```
  73. First run walks you through onboarding:
  74. ```
  75. ┌ WELCOME TO MILADY!
  76. │
  77. ◇ ♡♡milady♡♡: Hey there, I'm.... err, what was my name again?
  78. │ ● Sakuya
  79. │ ○ Reimu
  80. │ ○ Koishi
  81. │ ○ Marisa
  82. │ ○ Custom...
  83. │
  84. ◇ Sakuya: Now... how do I like to talk again?
  85. │ ● uwu~ (soft & sweet)
  86. │ ○ hell yeah (bold & fearless)
  87. │ ○ lol k (terminally online)
  88. │ ○ Noted. (composed & precise)
  89. │ ○ hehe~ (playful trickster)
  90. │ ○ ... (quiet intensity)
  91. │ ○ lmao kms (unhinged & dark)
  92. │
  93. ◇ Connect a brain
  94. │ ● Anthropic (Claude)
  95. │ ○ OpenAI (GPT)
  96. │ ○ Ollama (local, no key)
  97. │ ○ Skip for now
  98. │
  99. ◇ API key?
  100. │ sk-ant-•••••••••••••••••
  101. │
  102. └ Starting agent...
  103. Dashboard: http://localhost:2138
  104. Gateway: ws://localhost:18789/ws
  105. she's alive. go say hi.
  106. ```
  107. ### Alternative install paths
  108. Windows:
  109. ```powershell
  110. irm https://get.milady.ai/install.ps1 | iex
  111. ```
  112. NPM global:
  113. ```bash
  114. npm install -g miladyai
  115. milady setup
  116. ```
  117. ### Building from source (developers)
  118. Milady builds against the **published `@elizaos/*` npm packages** (`beta` dist-tag) by default. The repo no longer tracks `eliza/` as a submodule — a fresh clone has no `eliza/` checkout and `bun install` resolves everything from npm.
  119. **First install after cloning:**
  120. ```bash
  121. git clone https://github.com/milady-ai/milady.git
  122. cd milady
  123. ./install # Unix / macOS — chmod +x install if needed
  124. # install.cmd on Windows
  125. # With no args, the wrapper opens a Space/Enter multi-select picker:
  126. # packages, local elizaOS source, or all developer paths.
  127. # Non-interactive examples:
  128. ./install --profile packages
  129. ./install --profile local
  130. ./install --profile all
  131. # Plain `bun install` is package-mode only and runs a preflight doctor.
  132. # If Node/Python is outside the supported native install lane, run ./install.
  133. ```
  134. #### elizaOS source modes (eject / uneject)
  135. Milady has two source modes for `@elizaos/*` packages, selected via `MILADY_ELIZA_SOURCE`:
  136. | Mode | When to use | What resolves `@elizaos/*` |
  137. |---|---|---|
  138. | `packages` (default) | App development, builds, releases | npm registry (`beta` dist-tag) |
  139. | `local` | Patching elizaOS upstream alongside Milady | A repo-local `eliza/` checkout linked into `node_modules/` |
  140. **Switch to local mode (uneject)** — clones `eliza/` if absent, links workspace packages, swaps the root tsconfig to source-priority paths:
  141. ```bash
  142. bun run eliza:local # clone (or restore) eliza/, link packages, run bun install
  143. ```
  144. **Switch back to packages mode (eject)** — rewrites the root `package.json` to pin npm versions, swaps the root tsconfig back to packages-mode-clean, and regenerates the lockfile:
  145. ```bash
  146. bun run eliza:packages # default: beta tag
  147. bun run eliza:packages:alpha # explicit alpha (legacy)
  148. bun run eliza:packages -- --tag beta # any other dist-tag
  149. bun run eliza:packages -- --version 2.0.0-alpha.116 # pin an exact version
  150. bun run eliza:packages -- --rename # also rename eliza/ → .eliza.ci-disabled/
  151. ```
  152. **What each mode mutates** — both kept in sync by [scripts/lib/tsconfig-mode.mjs](scripts/lib/tsconfig-mode.mjs):
  153. - `tsconfig.json` — sourced from [scripts/templates/tsconfig.packages-mode.json](scripts/templates/tsconfig.packages-mode.json) (default) or [scripts/templates/tsconfig.local-mode.json](scripts/templates/tsconfig.local-mode.json) (local)
  154. - `package.json` — rewritten on eject (backup at `package.json.pre-disable-backup`); restored on uneject
  155. - `bun.lock` — regenerated on every mode switch
  156. - `eliza/` directory — left in place by default; renamed to `.eliza.ci-disabled/` only with `--rename`
  157. The checked-in `tsconfig.json` always matches the packages-mode template; the [standalone contract test](scripts/standalone-eliza-package-contract.test.ts) enforces this invariant. Run `bun run verify:standalone` to check.
  158. **Configuration env vars** (read by `scripts/lib/eliza-package-mode.mjs`):
  159. - `MILADY_ELIZA_SOURCE` — `local` or `packages` (default)
  160. - `MILADY_ELIZAOS_DIST_TAG` / `ELIZAOS_NPM_TAG` — npm dist-tag in packages mode (default `beta`)
  161. - `MILADY_ELIZAOS_VERSION` — pin an exact version
  162. - `MILADY_ELIZA_GIT_URL` / `MILADY_ELIZA_BRANCH` — override the eliza source clone target
  163. - `MILADY_SKIP_LOCAL_UPSTREAMS=1` — legacy flag equivalent to `MILADY_ELIZA_SOURCE=packages`
  164. **Test coverage in each mode:**
  165. - `bun run test`, `bun run verify:typecheck`, `bun run verify:lint`, `bun run build:web`, `bun run build:android` — work in both modes.
  166. - `bun run build:desktop` and `bun run build:ios` (plus `dev:desktop`) require **local mode** first (`bun run eliza:local`). Packages mode ships no `platforms/` directory, so the published `@elizaos/app-core` tarball has nothing for Electrobun / the iOS Capacitor shell to resolve against.
  167. - The packaged-Electrobun E2E suite at `apps/app/test/electrobun-packaged/` requires **local mode** (it imports source-level test helpers from `eliza/packages/app-core/test/helpers/`).
  168. #### Windows: enable long paths
  169. Bun's cache stores packages in deep directory trees that exceed the default Windows `MAX_PATH` limit (260 characters). Native builds (e.g. `llama-cpp-capacitor` via CMake/ninja) will fail with `mkdir: No such file or directory` unless long paths are enabled at the OS level.
  170. Run once in an elevated PowerShell, then reboot:
  171. ```powershell
  172. New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  173. -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
  174. ```
  175. Also enable long paths in Git:
  176. ```bash
  177. git config --global core.longPaths true
  178. ```
  179. ### Homebrew (macOS / Linux)
  180. ```bash
  181. brew tap milady-ai/tap
  182. brew install milady-ai/tap/milady # CLI
  183. brew install --cask milady-ai/tap/milady # Desktop app (macOS only)
  184. ```
  185. <a id="linux"></a>
  186. ### Linux
  187. The Linux desktop app ships as a single installer tarball: **`stable-linux-x64-Milady-Setup.tar.gz`** on the [latest release](https://github.com/milady-ai/milady/releases/latest). There is no AppImage, `.deb`, Snap, Flatpak, or APT repo today.
  188. ```bash
  189. cd ~/Downloads
  190. curl -fsSLO https://github.com/milady-ai/milady/releases/latest/download/stable-linux-x64-Milady-Setup.tar.gz
  191. tar -xzf stable-linux-x64-Milady-Setup.tar.gz
  192. # Extracts `installer` + `README.txt` into the current directory; run the installer:
  193. ./installer
  194. ```
  195. x86_64 only. (Prefer the terminal? The `curl … | bash` CLI install above works on any Linux box.)
  196. ### Security: API token
  197. The API server binds to `127.0.0.1` (loopback) by default — only you can reach it. If you expose it to the network (e.g. `MILADY_API_BIND=0.0.0.0` for container/cloud deployments), **set a token**:
  198. ```bash
  199. echo "MILADY_API_TOKEN=$(openssl rand -hex 32)" >> .env
  200. ```
  201. Without a token on a public bind, anyone who can reach the server gets full access to the dashboard, agent, and wallet endpoints.
  202. ### Hosting Modes
  203. On first run, onboarding now asks where the backend should live:
  204. - `Local` — run the backend on the current machine, exactly like the existing local flow.
  205. - `Cloud` — either use `Eliza Cloud` or attach to a `Remote Milady` backend with its address and access key.
  206. If you choose `Eliza Cloud`, the app provisions and connects to a managed backend. If you choose `Remote Milady`, the frontend rebinds to the backend you specify and continues against that API.
  207. ### Remote Backend Deployment
  208. Use this when you want the Milady frontend to connect to a backend running on your VPS, homelab box, or another machine.
  209. 1. Install Milady on the target machine.
  210. 2. Bind the API to a reachable address.
  211. 3. Generate a strong API token.
  212. 4. Allow the frontend origin explicitly.
  213. 5. Expose the backend over HTTPS or a private Tailscale URL.
  214. Recommended server environment:
  215. ```bash
  216. export MILADY_API_BIND=0.0.0.0
  217. export MILADY_API_TOKEN="$(openssl rand -hex 32)"
  218. export MILADY_ALLOWED_ORIGINS="https://app.milady.ai,https://milady.ai,https://elizacloud.ai,https://www.elizacloud.ai"
  219. milady start
  220. ```
  221. The access key the user enters in onboarding is the value of `MILADY_API_TOKEN`.
  222. If you want to connect from the desktop shell instead of the web frontend:
  223. ```bash
  224. MILADY_DESKTOP_API_BASE=https://your-milady-host.example.com \
  225. MILADY_API_TOKEN=your-token \
  226. bun run dev:desktop
  227. ```
  228. ### Tailscale
  229. For private remote access without opening the backend publicly, expose it over your tailnet:
  230. ```bash
  231. tailscale serve --https=443 http://127.0.0.1:2138
  232. ```
  233. If you intentionally want a public Tailscale URL:
  234. ```bash
  235. tailscale funnel --https=443 http://127.0.0.1:2138
  236. ```
  237. Then use the Tailscale HTTPS URL as the backend address in onboarding and keep using the same `MILADY_API_TOKEN` as the access key.
  238. ### Eliza Cloud
  239. `Milady` uses the existing `Eliza Cloud` deployment directly at `https://elizacloud.ai`. The managed control plane, auth surface, billing, and instance dashboard all live there; there is no separate Milady-hosted cloud control plane to deploy.
  240. Managed browser flow:
  241. 1. Sign in on `https://elizacloud.ai/login?returnTo=%2Fdashboard%2Fmilady`
  242. 2. Open or create a Milady instance in `https://elizacloud.ai/dashboard/milady`
  243. 3. Eliza Cloud redirects to `https://app.milady.ai` with a one-time launch session
  244. 4. `app.milady.ai` exchanges that launch session directly with Eliza Cloud and attaches to the selected managed backend
  245. The desktop/local app still exposes local `/api/cloud/*` passthrough routes for cloud login, billing, and compat management so it can persist the Eliza Cloud API key into the local config/runtime. That is local app plumbing, not a separate hosted Milady server.
  246. The integration plan lives in [docs/eliza-cloud-rollout.md](docs/eliza-cloud-rollout.md).
  247. The implementation and proxy runbook lives in [docs/eliza-cloud-deployment.md](docs/eliza-cloud-deployment.md).
  248. ---
  249. ## Terminal Commands
  250. ```bash
  251. milady # start (interactive, opens dashboard)
  252. milady start # server-only mode (API server, no interactive chat loop)
  253. milady --verbose # enable informational runtime logs
  254. milady --debug # enable debug-level runtime logs
  255. ```
  256. ### Setup & Config
  257. ```bash
  258. milady setup # first-time setup / refresh workspace after update
  259. milady configure # interactive config wizard
  260. milady config get <key> # read a config value
  261. milady config path # print resolved config file path
  262. milady config show # display all config values grouped by section
  263. ```
  264. ### Dashboard & UI
  265. ```bash
  266. milady dashboard # open web UI in browser
  267. milady dashboard --port 3000 # custom port
  268. ```
  269. ### Models
  270. ```bash
  271. milady models # list configured model providers
  272. ```
  273. ### Plugins
  274. ```bash
  275. milady plugins list # browse registry plugins
  276. milady plugins installed # what's installed
  277. milady plugins install <name> # install a plugin
  278. milady plugins uninstall <name>
  279. milady plugins search <query> # search by keyword
  280. ```
  281. ### Misc
  282. ```bash
  283. milady --version # version check
  284. milady --help # help
  285. milady doctor # diagnose issues
  286. ```
  287. ---
  288. ## TUI (Terminal UI)
  289. When running, milady shows a live terminal interface:
  290. ```
  291. ╭─────────────────────────────────────────────────────────────╮
  292. │ milady v2.0.0 ▲ running │
  293. ├─────────────────────────────────────────────────────────────┤
  294. │ │
  295. │ Agent: mila │
  296. │ Model: anthropic/claude-opus-4.7 │
  297. │ Sessions: 2 active │
  298. │ │
  299. │ ┌─ Activity ──────────────────────────────────────────┐ │
  300. │ │ 12:34:02 [web] user: hey mila │ │
  301. │ │ 12:34:05 [web] mila: hi anon~ what's up? │ │
  302. │ │ 12:35:11 [telegram] user joined │ │
  303. │ │ 12:35:15 [telegram] user: gm │ │
  304. │ │ 12:35:17 [telegram] mila: gm fren │ │
  305. │ └─────────────────────────────────────────────────────┘ │
  306. │ │
  307. │ Tokens: 12,847 in / 3,291 out Cost: $0.42 │
  308. │ │
  309. ╰─────────────────────────────────────────────────────────────╯
  310. [q] quit [r] restart [d] dashboard [l] logs [?] help
  311. ```
  312. ### TUI Hotkeys
  313. | Key | Action |
  314. |-----|--------|
  315. | `q` | quit gracefully |
  316. | `r` | restart gateway |
  317. | `d` | open dashboard in browser |
  318. | `l` | toggle log view |
  319. | `c` | compact/clear activity |
  320. | `?` | show help |
  321. | `↑/↓` | scroll activity |
  322. ### Server-only mode
  323. Don't want the interactive TUI? Use the `start` command, which runs in server-only mode (API server, no interactive chat loop):
  324. ```bash
  325. milady start
  326. ```
  327. Logs go to `stdout/stderr`. Daemonize with your favorite process manager.
  328. ---
  329. ## Chat Commands (in any chat session)
  330. | Command | What it do |
  331. |---------|------------|
  332. | `/status` | session status, tokens, cost |
  333. | `/new` `/reset` | memory wipe, fresh start |
  334. | `/compact` | compress context (she summarizes) |
  335. | `/think <level>` | reasoning: off\|minimal\|low\|medium\|high\|max |
  336. | `/verbose on\|off` | toggle verbose responses |
  337. | `/usage off\|tokens\|full` | per-message token display |
  338. | `/model <id>` | switch model mid-session |
  339. | `/restart` | restart the gateway |
  340. | `/help` | list commands |
  341. ---
  342. ## Ports
  343. **Production** (`milady start`):
  344. | Service | Default | Env Override |
  345. |---------|---------|--------------|
  346. | Dashboard + API | `2138` | `MILADY_PORT` |
  347. | Gateway (WebSocket + HTTP) | `18789` | `MILADY_GATEWAY_PORT` |
  348. | Home Dashboard | `2142` | `MILADY_HOME_PORT` |
  349. | WeChat Webhook | `18790` | `MILADY_WECHAT_WEBHOOK_PORT` |
  350. **Development** (`bun run dev`):
  351. | Service | Default | Env Override |
  352. |---------|---------|--------------|
  353. | API + WebSocket | `31337` | `MILADY_API_PORT` |
  354. | Dashboard UI (Vite) | `2138` | `MILADY_PORT` |
  355. | Gateway | `19001` | `MILADY_GATEWAY_PORT` (set by `--profile dev`) |
  356. **If a default port is already in use:** `bun run dev` / `dev-server.ts` can bind to a different port and then **sync `MILADY_API_PORT` / `ELIZA_PORT`** to match. **`dev:desktop` / `dev:desktop:watch`** resolve **free** loopback ports **before** spawning Vite + API + Electrobun so proxy, `MILADY_RENDERER_URL`, and `MILADY_DESKTOP_API_BASE` stay aligned—**why:** Vite reads `vite.config.ts` once; guessing the API port only inside the API process would desync the UI proxy. The **packaged Electrobun** shell picks the next free port from `MILADY_PORT` for the embedded child instead of `lsof`+SIGKILL by default—**why:** two Milady installs (separate state dirs) should coexist. Opt-in old reclaim: **`MILADY_AGENT_RECLAIM_STALE_PORT=1`**. See [Desktop local development](docs/apps/desktop-local-development.md#when-default-ports-are-busy) and [Desktop — Port configuration](docs/apps/desktop.md#port-configuration).
  357. ```bash
  358. # custom ports
  359. MILADY_GATEWAY_PORT=19000 MILADY_PORT=3000 milady start
  360. ```
  361. ---
  362. ## Config
  363. Lives at `~/.local/state/milady/milady.json` (override with `MILADY_CONFIG_PATH` or `MILADY_STATE_DIR`)
  364. ```json5
  365. {
  366. agent: {
  367. name: "mila",
  368. model: "anthropic/claude-opus-4.7",
  369. },
  370. env: {
  371. ANTHROPIC_API_KEY: "<ANTHROPIC_API_KEY>",
  372. },
  373. }
  374. ```
  375. Or use `~/.local/state/milady/.env` for secrets.
  376. ---
  377. ## Model Providers
  378. | Provider | Env Variable | Vibe |
  379. |----------|--------------|------|
  380. | [Anthropic](https://anthropic.com) | `ANTHROPIC_API_KEY` | **recommended** — claude is cracked |
  381. | [OpenAI](https://openai.com) | `OPENAI_API_KEY` | gpt-4o, o1, the classics |
  382. | [OpenRouter](https://openrouter.ai) | `OPENROUTER_API_KEY` | 100+ models one API |
  383. | [Google Gemini](https://ai.google.dev) | `GOOGLE_API_KEY` | gemini pro, flash, ultra |
  384. | [Google Antigravity](https://cloud.google.com/vertex-ai) | `GOOGLE_CLOUD_API_KEY` | vertex AI / cloud models |
  385. | [Ollama](https://ollama.com) | — | local, free, no API key, full privacy |
  386. | [Groq](https://groq.com) | `GROQ_API_KEY` | fast af |
  387. | [xAI](https://x.ai) | `XAI_API_KEY` | grok, based |
  388. | [DeepSeek](https://deepseek.com) | `DEEPSEEK_API_KEY` | reasoning arc |
  389. | [Mistral](https://mistral.ai) | `MISTRAL_API_KEY` | mistral + mixtral |
  390. | [Together AI](https://together.ai) | `TOGETHER_API_KEY` | open-source model hosting |
  391. | [Cohere](https://cohere.com) | `COHERE_API_KEY` | command R+ and embed |
  392. | [Perplexity](https://perplexity.ai) | `PERPLEXITY_API_KEY` | search-augmented gen |
  393. | [Qwen](https://qwen.ai) | — | alibaba's qwen models (configure via plugin entry) |
  394. | [MiniMax](https://minimaxi.com) | — | minimax language models (configure via plugin entry) |
  395. | [Zai](https://homunculuslabs.com) | `ZAI_API_KEY` | homunculus labs zai |
  396. | [Vercel AI Gateway](https://sdk.vercel.ai) | `AI_GATEWAY_API_KEY` | unified gateway |
  397. See [Model Providers](docs/model-providers.mdx) for the full provider reference with configuration details. The `milady models` command checks which providers are configured.
  398. ### Using Ollama (local models)
  399. [Ollama](https://ollama.com) lets you run models locally with zero API keys. Install it, pull a model, and configure Milady:
  400. ```bash
  401. # install ollama
  402. curl -fsSL https://ollama.com/install.sh | sh
  403. # pull a model
  404. ollama pull gemma3:4b
  405. ```
  406. > **⚠️ Known issue:** The `@elizaos/plugin-ollama` has an SDK version incompatibility with the current AI SDK. Use Ollama's **OpenAI-compatible endpoint** as a workaround:
  407. Edit `~/.local/state/milady/milady.json`:
  408. ```json5
  409. {
  410. env: {
  411. OPENAI_API_KEY: "ollama", // any non-empty string works
  412. OPENAI_BASE_URL: "http://localhost:11434/v1", // ollama's openai-compat endpoint
  413. SMALL_MODEL: "gemma3:4b", // or any model you pulled
  414. LARGE_MODEL: "gemma3:4b",
  415. },
  416. }
  417. ```
  418. This routes through the OpenAI plugin instead of the broken Ollama plugin. Works with any Ollama model — just make sure `ollama serve` is running.
  419. > **OpenRouter (`@elizaos/plugin-openrouter`):** Milady pins the dependency to **`2.0.0-alpha.13`**. **Why:** npm **`2.0.0-alpha.12`** published **truncated** JavaScript bundles: the files export `openrouterPlugin` / default but never define them (the main plugin chunk is missing), so Bun fails when loading the plugin. A caret range would allow that broken version again. See [Plugin resolution — pinned OpenRouter](docs/plugin-resolution-and-node-path.md#pinned-elizaosplugin-openrouter) and [OpenRouter plugin doc](docs/plugin-registry/llm/openrouter.md#milady-pinned-version-and-upstream-bundle-bug).
  420. **Recommended models for local use:**
  421. | Model | Size | Vibe |
  422. |-------|------|------|
  423. | `gemma3:4b` | ~3GB | fast, good for chat |
  424. | `llama3.2` | ~2GB | lightweight, quick responses |
  425. | `mistral` | ~4GB | solid all-rounder |
  426. | `deepseek-r1:8b` | ~5GB | reasoning arc |
  427. ---
  428. ## Prerequisites
  429. | | Version | Check | Install |
  430. |---|---------|-------|---------|
  431. | **Node.js** | >= 22 | `node --version` | [nodejs.org](https://nodejs.org) |
  432. | **Bun** | latest | `bun --version` | `curl -fsSL https://bun.sh/install \| bash` |
  433. | **Git** | any | `git --version` | system package manager |
  434. **Optional** (for vision/TTS plugins with native deps):
  435. - macOS: `xcode-select --install`
  436. - Linux: `sudo apt install build-essential python3 libcairo2-dev libjpeg-dev libpango1.0-dev`
  437. ## Build from Source
  438. ```bash
  439. git clone https://github.com/milady-ai/milady.git
  440. cd milady
  441. ./install # interactive source setup picker (Space selects, Enter installs)
  442. bun run build
  443. bun run milady start
  444. ```
  445. For scripted package-mode setup, run `./install --profile packages`. Plain
  446. `bun install` remains supported when you only need the default published-package
  447. dependency graph.
  448. > `bun run build` runs the production build via Node ([scripts/run-production-build.mjs](scripts/run-production-build.mjs) — forks between published `@elizaos/app-core` and the local `eliza/` checkout depending on `MILADY_ELIZA_SOURCE`).
  449. ### Dev mode (recommended for development)
  450. ```bash
  451. bun run dev # API (:31337) + Vite dashboard UI (:2138); hot reload (defaults; see Ports if busy)
  452. bun run dev:web:ui # explicit alias for the same browser dashboard stack
  453. bun run dev:desktop # desktop dev orchestrator + Electrobun, using built renderer assets when fresh
  454. bun run dev:desktop:watch # same desktop orchestrator with Vite watch/HMR
  455. ```
  456. **Why separate entry points:** `dev` / `dev:web:ui` are the **browser dashboard** stack only. `dev:desktop` / `dev:desktop:watch` are the **Electrobun** workflow (multi-process: orchestrator, API, optional Vite, native shell) so desktop env and ports stay aligned without changing the default headless-friendly dev command.
  457. The web-ui orchestrator frees the listen port when needed, waits for the API to be healthy, then starts Vite with an `/api` proxy to **`MILADY_API_PORT`**.
  458. ### Desktop shell (Electrobun)
  459. ```bash
  460. bun run dev:desktop # API + Electrobun; skips vite build when apps/app/dist is fresh
  461. bun run dev:desktop:watch # + Vite dev server and MILADY_RENDERER_URL (HMR for UI work)
  462. ```
  463. **Why a separate flow:** the desktop stack runs **multiple processes** (orchestrator, Vite and/or built assets, API, Electrobun). The orchestrator **pre-allocates** free **API** and **Vite** ports when defaults are taken so every child gets consistent env—**why:** misaligned ports cause blank UI or 502s on `/api`. See **[docs/apps/desktop-local-development.md](docs/apps/desktop-local-development.md)** (including [when default ports are busy](docs/apps/desktop-local-development.md#when-default-ports-are-busy)) for signals, shutdown when you quit the app, and env vars.
  464. **IDE / agent hooks** — Editors and agents do not see the native window or auto-discover localhost. **Why we added hooks:** with desktop dev running, the API exposes **`GET /api/dev/stack`** (JSON: ports, renderer URL, which features are on). **`bun run desktop:stack-status -- --json`** probes ports and merges stack + health + status. By default, **`~/.local/state/milady/desktop-dev-console.log`** mirrors prefixed child logs and **`GET /api/dev/cursor-screenshot`** (loopback) returns a full-screen PNG via OS capture — both are opt-out via env (see doc). Cursor uses **`.cursor/rules/milady-desktop-dev-observability.mdc`** plus that guide.
  465. ```bash
  466. bun run verify # typecheck + lint + test (run before committing; `check` aliases this)
  467. bun run test # parallel test suite
  468. bun run milady:doctor # diagnose environment issues (`doctor` aliases this)
  469. bun run setup:sync # re-run postinstall hooks (`repair` aliases this)
  470. bun run workspace:deps:sync # normalize workspace:* / local checkout edges (`fix-deps` aliases sync)
  471. bun run workspace:deps:check # verify workspace deps without writing (`fix-deps:check`)
  472. ```
  473. **Why workspace scripts:** Local **`./eliza`** and **`plugins/*`** checkouts frequently drift dependency edges; the scripts automate what used to be manual `package.json` surgery. See **[Developer diagnostics and workspace](docs/guides/developer-diagnostics-and-workspace.md)**.
  474. See **[Architecture](docs/architecture.mdx)** for the full development guide including architecture overview and config reference. See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for contribution guidelines.
  475. ### Documentation (with WHYs)
  476. - **[Developer diagnostics and workspace](docs/guides/developer-diagnostics-and-workspace.md)** — Why optional-plugin logs include **load provenance**, why stagehand path **walks parents**, why life-ops migrations use explicit **transactions** and **deferred indexes**, and why **workspace:** scripts / **gitignore** rules exist for local checkouts.
  477. - **[Plugin resolution and NODE_PATH](docs/plugin-resolution-and-node-path.md)** — Why we set `NODE_PATH` in three places so dynamic plugin imports resolve when building from source (CLI, desktop dev, Electrobun). Includes **pinned `@elizaos/plugin-openrouter`**, **why** `alpha.12` must not be resolved until upstream fixes the published bundle, and **optional plugin provenance** when a package is missing.
  478. - **[Build and release](docs/build-and-release.md)** — Why the release pipeline uses strict shell, retries, `actions/setup-node@v4` + `check-latest: false`, Bun cache, timeouts; why size-report pipelines handle SIGPIPE; why Windows plugin build uses `npx -p typescript tsc`.
  479. - **[Desktop local development](docs/apps/desktop-local-development.md)** — Why `dev:desktop` / `dev:desktop:watch` orchestrate Vite, API, and Electrobun; HMR vs `vite build --watch`; Ctrl-C, Quit, and `detached` children; **IDE/agent observability** (`/api/dev/stack`, aggregated console, screenshot proxy, WHY loopback and opt-out).
  480. - **[Desktop main-process reset](docs/apps/desktop-main-process-reset.md)** — Why **Reset Milady…** runs HTTP in the Electrobun main process after native confirm, how the renderer syncs UI state, reachable API probing (`res.ok`), and where tests live.
  481. - **[Darwin vs macOS version (Electrobun WebGPU)](docs/apps/electrobun-darwin-macos-webgpu-version.md)** — Why **`uname -r` / `os.release()`** is not the macOS marketing major after Tahoe, how we map **Darwin 25 → macOS 26**, and why the WebGPU gate used to print “macOS 16.”
  482. - **[Changelog](docs/changelog.mdx)** — Shipped features and fixes with rationale (**WHY** bullets in each update).
  483. - **[Roadmap](docs/roadmap.md)** — Direction and follow-ups; points to changelog for what already landed.
  484. ---
  485. ## Contributing
  486. **This project is built by agents, for agents.**
  487. Humans contribute as QA testers — use the app, find bugs, report them. That's the most valuable thing you can do. All code contributions are reviewed and merged by AI agents. No exceptions.
  488. Read [CONTRIBUTING.md](./CONTRIBUTING.md) for the full details.
  489. ---
  490. ## License
  491. **MIT License**
  492. free to use, free to modify, free to distribute. see [LICENSE](LICENSE) for details.
  493. ---
  494. *built by agents. tested by humans. that's the split.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.