satran004 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json
@@ -15,6 +15,7 @@
   "mcp-integration": "MCP Integration",
   "commands": "Yaci CLI Commands",
   "node-configuration": "Node Configuration",
+  "user-settings": "User Settings",
   "multi-node-setup": "Multi-node setup",
   "rollback-testing": "Rollback Testing",
   "ci-integration": "CI/CD Integration",

diff --git a/docs/pages/getting-started/_meta.json b/docs/pages/getting-started/_meta.json
@@ -1,5 +1,6 @@
 {
   "docker": "Docker Setup",
-  "zip": "Zip Setup", 
-  "npm": "NPM Setup"
+  "zip": "Zip Setup",
+  "npm": "NPM Setup",
+  "homebrew": "Homebrew Setup"
 }
diff --git a/docs/pages/getting-started/homebrew.mdx b/docs/pages/getting-started/homebrew.mdx
@@ -0,0 +1,117 @@
+import { Callout } from 'nextra/components'
+
+# Homebrew Setup
+
+The Homebrew distribution installs the native Yaci CLI and its configuration with `brew`, and keeps it up to date with `brew upgrade`. It provides the same `yaci-devkit` command as the [NPM distribution](/getting-started/npm), without needing Node.js.
+
+## Prerequisites
+
+### Supported Platforms
+
+1. **macOS 15 (Arm64) or later**
+2. **Linux x86**: Tested on Ubuntu 22.04 and later ([Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux))
+
+### Requirements
+
+- **Homebrew**: [brew.sh](https://brew.sh)
+- **Available ports**: Default ports should be free (3001, 8080, 10000)
+
+For Ogmios and Kupo, ensure ports 1337 and 1442 are also available if you plan to use these services.
+
+## Installation
+
+For latest stable version:
+```bash
+brew install bloxbean/tap/yaci-devkit
+```
+
+For latest beta version:
+```bash
+brew install bloxbean/tap/yaci-devkit-beta
+```
+
+Both formulas install the same `yaci-devkit` command, so install only one of them. To switch, uninstall the other first:
+
+```bash
+brew uninstall yaci-devkit-beta
+brew install bloxbean/tap/yaci-devkit
+```
+
+Check that the command comes from Homebrew:
+
+```bash
+which yaci-devkit
+```
+
+It should print `/opt/homebrew/bin/yaci-devkit` on macOS or `/home/linuxbrew/.linuxbrew/bin/yaci-devkit` on Linux.
+
+<Callout type="info">
+**Switching from NPM?** An NPM install also provides a `yaci-devkit` command, and an older `sudo npm install -g` puts it in `/usr/local/bin`, which usually comes before Homebrew on the `PATH`. Remove it first:
+
+```bash
+npm uninstall -g @bloxbean/yaci-devkit
+# for an install made with sudo:
+sudo npm uninstall -g --prefix /usr/local @bloxbean/yaci-devkit
+```
+
+Devnets and downloaded components in `$HOME/.yaci-cli` are kept, and are used by the Homebrew install too.
+</Callout>
+
+### Upgrade
+
+```bash
+brew update
+brew upgrade yaci-devkit
+```
+
+### Uninstall
+
+```bash
+brew uninstall yaci-devkit
+```
+
+This does not remove `$HOME/.yaci-cli` (devnets, downloaded components and `devkit.properties`).
+
+## Getting Started
+
+The `yaci-devkit` command takes the same options as with the NPM distribution:
+
+```bash
+# Devnet with Cardano node only
+yaci-devkit up
+
+# Devnet with Yaci Store (Blockfrost-compatible APIs)
+yaci-devkit up --enable-yaci-store
+
+# Sub-second block time (200ms)
+yaci-devkit up --enable-yaci-store --block-time 0.2 --slot-length 0.2
+
+# Devnet with the interactive Yaci CLI prompt
+yaci-devkit up --interactive
+```
+
+To see all supported options:
+```bash
+yaci-devkit up --help
+```
+
+See the [NPM Setup](/getting-started/npm#basic-usage) page for more examples, service URLs and CLI commands.
+
+Yaci Viewer is not included. Install it separately through NPM: see [Install Yaci Viewer](/getting-started/npm#step-2-install-yaci-viewer-optional).
+
+## Configuration
+
+The bundled `application.properties`, `node.properties` and `download.properties` are inside the Homebrew installation and are replaced on every upgrade. Put your settings in `$HOME/.yaci-cli/devkit.properties` instead:
+
+```properties
+yaci.store.enabled=true
+prometheus.port=12799
+```
+
+See [User Settings](/user-settings) for details.
+
+## Next Steps
+
+- **Learn all commands**: Check out [Yaci CLI Commands](/commands)
+- **CI/CD integration**: Set up [automated testing](/ci-integration)
+- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development
diff --git a/docs/pages/getting-started/npm.mdx b/docs/pages/getting-started/npm.mdx
@@ -177,6 +177,10 @@ yaci-devkit up --port 3002 --interactive
 yaci-devkit up -e 30 --interactive
 ```
 
+## Configuration
+
+The bundled configuration files are inside the NPM package and are replaced on every upgrade. Put your own settings, for example `yaci.store.enabled=true` or `prometheus.port=12799`, in `$HOME/.yaci-cli/devkit.properties`. See [User Settings](/user-settings).
+
 ## Yaci Viewer Setup
 
 ### Starting Yaci Viewer
@@ -312,4 +316,4 @@ See [Known Issues](../known-issues#devnet-node-does-not-start-while-another-card
 
 - **Learn all commands**: Check out [Yaci CLI Commands](/commands)
 - **CI/CD integration**: Set up [automated testing](/ci-integration)
-- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development
+- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development, or [Homebrew Setup](/getting-started/homebrew) to install without Node.js
diff --git a/docs/pages/getting-started/zip.mdx b/docs/pages/getting-started/zip.mdx
@@ -15,10 +15,6 @@ The Zip distribution is perfect for:
 **Note**: Yaci Viewer is not included in the Zip distribution. To add viewer functionality, you can install Yaci Viewer separately through NPM. See the [NPM installation guide](/getting-started/npm#step-2-install-yaci-viewer-optional) for details.
 </Callout>
 
-<Callout type="warning">
-PV11-compatible Ogmios/Kupo binaries are currently published only as Linux x86_64 builds. On macOS arm64 native CLI, those specific Ogmios/Kupo defaults cannot run directly. Use Docker as a workaround, or set custom `ogmios.url` / `kupo.url` values when compatible native builds are available.
-</Callout>
-
 ## Key Advantages
 
 - **Reduced Disk Space**: Requires less disk space than Docker, containing only the Yaci CLI binary and configuration files
@@ -40,6 +36,8 @@ Yaci CLI is currently supported on:
 ```bash
 rm -rf $HOME/.yaci-cli
 ```
+
+This also removes your [User Settings](/user-settings) file, `$HOME/.yaci-cli/devkit.properties`. Copy it somewhere else first if you have one.
 </Callout>
 
 ## Installation
@@ -173,6 +171,10 @@ yaci-cli:> create-node -o --block-time 5 --slot-length 5 --start
 
 The `config` folder contains three important configuration files:
 
+<Callout type="info">
+A new release comes with a new `config` folder. To keep your settings across upgrades, put them in `$HOME/.yaci-cli/devkit.properties` instead: it can hold any key from these three files and wins over them. See [User Settings](/user-settings).
+</Callout>
+
 ### application.properties
 
 Main configuration file for Yaci CLI functionality.

diff --git a/docs/pages/introduction.mdx b/docs/pages/introduction.mdx
@@ -35,7 +35,7 @@ The ZIP distribution includes only the Yaci CLI and allows selective downloading
 
 **Supported Environments:**
 - Linux x64
-- macOS arm64
+- macOS 15 (arm64) or later
 
 ### 3. NPM Distribution
 
@@ -50,7 +50,18 @@ Supported environments include: Linux x64, MacOS arm64
 
 **Supported Environments:**
 - Linux x64
-- macOS arm64
+- macOS 15 (arm64) or later
+
+### 4. Homebrew Distribution
+
+The Homebrew distribution installs the same native Yaci CLI and `yaci-devkit` command as the NPM distribution, through `brew`, without needing Node.js.
+
+- `brew install bloxbean/tap/yaci-devkit`
+- Updates with `brew upgrade`
+
+**Supported Environments:**
+- Linux x64
+- macOS 15 (arm64) or later
 
 ## Getting Started
 
@@ -61,6 +72,7 @@ For the quickest setup experience, we recommend starting with the [Docker Setup]
 - [Docker Setup](/getting-started/docker) - Installation method
 - [Zip Setup](/getting-started/zip) - Non-Docker installation
 - [NPM Setup](/getting-started/npm) - NPM package installation
+- [Homebrew Setup](/getting-started/homebrew) - Homebrew installation
 - [Yaci CLI Commands](/commands) - Learn about available CLI commands
 
 ## Important Notes

diff --git a/docs/pages/known-issues.mdx b/docs/pages/known-issues.mdx
@@ -106,7 +106,7 @@ For technical details about this issue, see: [GitHub Issue #65](https://github.c
 
 ### Devnet node does not start while another cardano-node runs
 
-Applies to the zip, npm and native/JAR distributions. Docker is not affected: the devnet node runs in the container's own network, and its Prometheus port is not published to the host.
+Applies to the zip, npm, Homebrew and native/JAR distributions. Docker is not affected: the devnet node runs in the container's own network, and its Prometheus port is not published to the host.
 
 #### Current Behavior
 
@@ -128,7 +128,8 @@ Stop the other node, or give the devnet a free port. The port is written into th
 |---|---|---|
 | Zip / native binary | `create-node -o --prometheus-port 12799` | `prometheus.port=12799` in `config/application.properties`, or `./yaci-cli -Dprometheus.port=12799` |
 | JAR | `create-node -o --prometheus-port 12799` | `java -Dprometheus.port=12799 -jar yaci-cli.jar` |
-| NPM | `yaci-devkit up --prometheus-port 12799` | `PROMETHEUS_PORT=12799 yaci-devkit up` |
+| NPM / Homebrew | `yaci-devkit up --prometheus-port 12799` | `PROMETHEUS_PORT=12799 yaci-devkit up` |
+| Zip / NPM / Homebrew (v0.12.0+) | | `prometheus.port=12799` in `$HOME/.yaci-cli/devkit.properties` (see [User Settings](/user-settings)) |
 
 The `PROMETHEUS_PORT=12799` environment variable works with every distribution. Use one of the "Every time" forms if you also create devnets through the admin API or Yaci Viewer, which use the `prometheus.port` property.
 

diff --git a/docs/pages/user-settings.mdx b/docs/pages/user-settings.mdx
@@ -0,0 +1,58 @@
+import { Callout } from 'nextra/components'
+
+# User Settings (devkit.properties)
+
+`$HOME/.yaci-cli/devkit.properties` holds your own Yaci CLI settings. It is read by the [Homebrew](/getting-started/homebrew), [NPM](/getting-started/npm) and [Zip](/getting-started/zip) distributions, and is kept across upgrades: an upgrade replaces the bundled configuration files, but never this file.
+
+<Callout type="info">
+Available from Yaci DevKit `v0.12.0`. The [Docker distribution](/getting-started/docker) does not read it: use its `config/env` and `config/node.properties` files instead.
+</Callout>
+
+## Create the file
+
+The file is optional. Create it when you need it:
+
+```bash
+mkdir -p $HOME/.yaci-cli
+nano $HOME/.yaci-cli/devkit.properties
+```
+
+It can hold any key from the bundled `application.properties`, `node.properties` or `download.properties`, in the same `key=value` format. For example:
+
+```properties
+# Start Yaci Store with every devnet
+yaci.store.enabled=true
+
+# Devnet node's Prometheus port, when another cardano-node on this machine uses 12798
+prometheus.port=12799
+
+# Node mode (node.properties)
+nodeMode=yano-only
+
+# Your own Plutus cost models (a folder with plutus-costmodels-v10.json and plutus-costmodels-v11.json)
+yaci.cli.plutus-costmodels-path=/Users/me/cardano/costmodels
+```
+
+The settings are read when `yaci-devkit` (or `yaci-cli`) starts: restart it after changing the file.
+
+## Precedence
+
+From highest to lowest:
+
+1. Command options, such as `yaci-devkit up --prometheus-port 12799` or `create-node --block-time 2`, for that command
+2. `-D` options, such as `yaci-devkit -Dprometheus.port=12799 up` or `./yaci-cli -Dprometheus.port=12799`
+3. Environment variables, such as `PROMETHEUS_PORT=12799` or `YACI_STORE_ENABLED=true`
+4. `$HOME/.yaci-cli/devkit.properties`
+5. The bundled `application.properties`, `node.properties` and `download.properties`
+
+A setting in `devkit.properties` therefore wins over the same setting in the bundled files, including the `config` folder of the Zip distribution.
+
+The environment variable for a property is its name in upper case, with `.` replaced by `_` and `-` removed: `yaci.store.enabled` becomes `YACI_STORE_ENABLED`.
+
+## Things to know
+
+- **Location**: the file is always `$HOME/.yaci-cli/devkit.properties`, even when you set `yaci.cli.home` to store devnets and components elsewhere.
+- **Devnet settings**: genesis and node settings (from `node.properties`, and properties such as `prometheus.port`) are written into the devnet when it is created. Re-create the devnet after changing them: `create-node -o`, or `yaci-devkit up` (which creates a new devnet).
+- **Paths**: use absolute paths. A relative path resolves against the directory you run `yaci-devkit` or `yaci-cli` from.
+- **Shared**: Homebrew, NPM and Zip installs on the same machine all use `$HOME/.yaci-cli`, so they share this file, as they share devnets and downloaded components.
+- **Clean reinstall**: removing `$HOME/.yaci-cli` removes this file too. Copy it somewhere else first if you want to keep it.