> For the complete documentation index, see [llms.txt](https://berinis-organization.gitbook.io/ono/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://berinis-organization.gitbook.io/ono/developers/run-a-node.md).

# Run a node

An ONO node (`ono-core`) is a single Node.js process: an HTTP API, a WebSocket p2p server, a PostgreSQL-backed ledger, and — optionally — a proof-of-burn forger.

Source code: [github.com/ONO-coins/core](https://github.com/ONO-coins/core)

## Requirements

* **Node.js 20.6+** (env files are loaded with `node --env-file`)
* **PostgreSQL** (any recent version)
* A small server is plenty — forging is a once-per-second check, not a hash race

## Setup

1. Clone the [`ono-core` repository](https://github.com/ONO-coins/core) and install dependencies:

   ```bash
   git clone https://github.com/ONO-coins/core.git
   cd core
   npm install
   ```
2. Create a `.env` file:

   ```bash
   # HTTP API
   HTTP_PORT=4000

   # p2p
   P2P_PORT=5002
   DEFAULT_PEERS=["wss://core.ono.gg/ws"]

   # forging (see below)
   FORGING=false

   # network: false = mainnet, true = testnet
   TESTNET=false

   # wallet seed location (created on first run)
   SECRET_PATH=./secrets/secret.txt

   # database
   DATABASE_HOST=localhost
   DATABASE_NAME=ono
   DATABASE_USERNAME=postgres
   DATABASE_PASSWORD=postgres
   DATABASE_DIALECT=postgres
   DATABASE_FORCE_SYNC=false

   # operator endpoints (/secure/*) — keep disabled unless you need them
   ALLOW_SECURE_ROUTES=false
   SECURE_ROUTES_AUTHORIZATION_HEADER=change-me

   LOG_LEVEL=info
   ```
3. Start the node:

   ```bash
   npm start        # production: raw JSON logs
   npm run dev      # development: file watching + pretty logs
   ```

On boot the node connects to its peers, downloads the chain in batches of 30 blocks, and then follows the network live. On the very first run it also generates a wallet: a new mnemonic is logged once and the seed is written to `SECRET_PATH` — **back up that file (or the logged mnemonic); it is your node's wallet.**

{% hint style="warning" %}
`DATABASE_FORCE_SYNC=true` drops and recreates all tables on boot — a full resync from genesis. Only use it deliberately.
{% endhint %}

## Key environment variables

| Variable                             | Meaning                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| `HTTP_PORT`                          | REST API + WebSocket feed port                                                      |
| `P2P_PORT`                           | Node-to-node WebSocket port                                                         |
| `DEFAULT_PEERS`                      | JSON array of peer addresses to dial on boot (peers learned later are persisted)    |
| `FORGING`                            | `true` to forge blocks                                                              |
| `TESTNET`                            | `true` to join the testnet (different genesis and HD derivation path)               |
| `SECRET_PATH`                        | Wallet seed file (default `/secrets/secret.txt`, relative to the working directory) |
| `DATABASE_*`                         | PostgreSQL connection settings                                                      |
| `DATABASE_FORCE_SYNC`                | `true` drops and recreates all tables (destructive)                                 |
| `ALLOW_SECURE_ROUTES`                | Enables the `/secure/*` operator endpoints                                          |
| `SECURE_ROUTES_AUTHORIZATION_HEADER` | The value the `authorization` header must match on `/secure/*`                      |
| `LOG_LEVEL`                          | pino log level (`info`, `debug`, …)                                                 |

## Enable forging

1. Start the node once and note its wallet address (the logged public key).
2. Fund the address, then **burn at least 100 ONO** from it — send them to the burn address (`0000…000`, 66 zeros). See [Proof of burn](/ono/learn/proof-of-burn.md).
3. Set `FORGING=true` and restart.

The node now checks every second whether its burned balance has won the right to forge the next block, and collects the fees of every block it forges.

## Operator endpoints

With `ALLOW_SECURE_ROUTES=true`, two extra endpoints are available under `/secure/*`, guarded by the `authorization` header (must equal `SECURE_ROUTES_AUTHORIZATION_HEADER`):

* `GET /secure/stats` — node statistics
* `GET /secure/remove-chain-to/{blockId}` — roll the local chain back to a block (recovery tool; the node will resync forward from peers)

Keep these disabled on public nodes.

## Running two local nodes (development)

For testing p2p and forging locally, the repo ships two dev profiles that run two nodes against separate env files and databases:

```bash
npm run dev-test-1   # uses .env.development.local-1
npm run dev-test-2   # uses .env.development.local-2
```

Point each node's `DEFAULT_PEERS` at the other's p2p port and you have a two-node network on one machine.