Self-hosting the keeper

Before you start#

You need a checkout of the Aqueduct monorepo, Node.js 24 or newer and pnpm. Install once from the repository root:

pnpm install

Run it with paper vaults#

By default the keeper uses the paper executor: two simulated vaults kept in a JSON file, seeded with 250,000 and 100,000 USDC, with the program's caps enforced. Rates, the sentinel, the planner and the API are all real. It needs no keys, wallet or RPC.

pnpm --filter @aqueduct/keeper dev          # API on http://localhost:8787, restarts on code changes
pnpm --filter @aqueduct/keeper cycle:once   # one cycle for both tiers, printed as tables, then exits
pnpm --filter @aqueduct/keeper test
pnpm --filter @aqueduct/keeper typecheck

The keeper reads configuration from environment variables only and does not load a .env file by itself. Copy apps/keeper/.env.example to .env and either export the variables, or start it with Node's loader from apps/keeper:

node --env-file=.env --import tsx src/index.ts

Configuration#

Run it against a local validator#

To see the keeper sign real transactions, give it a deployment of its own on a local validator:

1. Build and load the program

   anchor build
   solana-test-validator --reset --bpf-program BweEZpNS6bhcwjxgEgScgZSWRSkKC9tqmC2PpfZdFbhm target/deploy/aqueduct.so

2. Create the vaults

   The setup script creates a test USDC mint, the config, both vaults and every strategy, seeds starter deposits, generates a keeper key at KEEPER_KEYPAIR_PATH if none exists there, and writes packages/sdk/src/deployments/localnet.json. It reuses the asset mint recorded in that file, so on a fresh validator delete the file first.

   RPC_URL=http://127.0.0.1:8899 CLUSTER=localnet KEEPER_KEYPAIR_PATH=/path/to/keeper.json pnpm --filter @aqueduct/sdk setup

3. Start the keeper

   EXECUTOR=chain RPC_URL=http://127.0.0.1:8899 KEEPER_KEYPAIR=/path/to/keeper.json DATA_DIR=/tmp/aqueduct-keeper pnpm --filter @aqueduct/keeper dev

   The keeper warns at startup if its key is not the deployment's keeper; every transaction would then fail with Unauthorized.

Docker#

The image builds from the repository root, because the keeper depends on the SDK workspace package:

docker build -f apps/keeper/Dockerfile -t aqueduct-keeper .
docker run --rm -p 8787:8787 -v keeper-data:/app/apps/keeper/data aqueduct-keeper

It runs the TypeScript sources with tsx on Node 24 and keeps its state in /app/apps/keeper/data, so mount a volume there.

Railway#

The hosted keeper runs on Railway from apps/keeper/railway.json: it builds the Dockerfile, redeploys on changes under apps/keeper or packages/sdk, checks /health at deploy time, restarts on failure and runs exactly one replica. To run your own:

1. Create a service from the repository with the root as its build context; Railway picks up the config file.
2. Attach a volume and set DATA_DIR to its mount path, so decisions and rebalancer memory survive redeploys.
3. Set EXECUTOR, RPC_URL and KEEPER_KEYPAIR as service variables. Treat the keypair as a secret and never commit it.
4. Keep one replica. Two would double every move.

State#

The rebalancer writes its memory before it sends a transaction, so a crash and restart never repeat a move.

Point the app at your keeper#

The dashboard reads rates and decisions from the keeper API. In the app, open Settings, enter your keeper's base URL under Keeper API and choose Save & reload; it is stored in that browser only. For your own build of the web app, set it at build time:

NEXT_PUBLIC_KEEPER_URL=http://localhost:8787
NEXT_PUBLIC_DATA_SOURCE=chain                  # read vaults on-chain through the SDK instead of the built-in simulation
NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_CLUSTER=devnet                     # or localnet

The API is described in Keeper HTTP API.

Operating it in production#