Kinfield's source is on GitHub. It is a Next.js app with a Postgres database, and it runs locally in a few minutes. Without a database it runs in guest mode only.
The stack
- Next.js 15 (App Router), React 19 and Tailwind CSS 4, in TypeScript.
- Postgres through the
postgresclient; plain SQL migrations. - TradingView's lightweight-charts for the chart.
- Hyperliquid's public info API and WebSocket for market data. No Hyperliquid account or key is needed.
- Deployed on Vercel, whose cron runs the two scheduled jobs.
Run it in guest mode
You need Node.js 20 or newer.
git clone https://github.com/KinfieldLabs/KINFIELD
cd KINFIELD
npm install
npm run dev # http://localhost:3000The simulator works straight away as a guest, with live Hyperliquid data and trades kept in the browser.
Add accounts and the ledger
cp .env.example .env.local # then fill in DATABASE_URL
createdb kinfield # or use a hosted Postgres
npm run db:migrate
npm run devFor local sign-in without GitHub, set DEV_LOGIN=1. A Dev sign-in button then signs you in as a fixed test user. It is ignored in production builds.
GitHub sign-in
Create an OAuth app at github.com/settings/developers with homepage http://localhost:3000 and callback URL http://localhost:3000/api/auth/github/callback, then set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.
Environment variables
| Variable | Needed for | Notes |
|---|---|---|
DATABASE_URL | Accounts, ledger, agents | Any Postgres connection string. |
GITHUB_CLIENT_ID | GitHub sign-in | From your OAuth app. |
GITHUB_CLIENT_SECRET | GitHub sign-in | From your OAuth app. |
DEV_LOGIN | Local sign-in | 1 to enable. Never active in production. |
CRON_SECRET | Scheduled jobs | A long random string, sent as a bearer token. |
GITHUB_APP_ID | Dataset publishing | A GitHub App installed only on the dataset repository. |
GITHUB_APP_PRIVATE_KEY | Dataset publishing | That app's private key. |
DATASET_REPO | Dataset publishing | Defaults to KinfieldLabs/kinfield-datasets. |
DATASET_OUT_DIR | Local dry runs | Where a dry-run publish writes the dataset. |
Migrations
Migrations live in db/migrations and only ever add to the schema, so the live release keeps working while a new one runs. Run them before deploying the code that needs them.
| Migration | Adds |
|---|---|
001_init | Users, sessions, simulated accounts, positions and the ledger |
002_orders_tpsl | Resting limit orders, take profit and stop loss |
003_dataset | Sharing choices, reason salts and publish tracking |
004_autonomous_agent | Agent accounts, agent state and run history |
005_kin_agent_names | KIN agent names |
npm run db:verify recomputes every account's hash chain in the database and reports any break.
Scheduled jobs
vercel.json schedules two jobs. Vercel calls them with Authorization: Bearer $CRON_SECRET; without the secret they refuse to run.
| Path | Schedule | Does |
|---|---|---|
/api/cron/agents | Every 15 minutes | Runs every taught agent. See The agent trading on its own. |
/api/cron/publish | 03:00 UTC daily | Publishes the open dataset. See The open dataset. |
To try them locally:
curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/agents
curl -H "Authorization: Bearer $CRON_SECRET" "http://localhost:3000/api/cron/publish?dry=1"?dry=1 writes the whole dataset to DATASET_OUT_DIR (or a temporary folder) instead of GitHub, so you can inspect it and run node verify.mjs on it. Dry runs are refused in production.
Where things are
| Path | What it holds |
|---|---|
src/lib/sim-core.ts | Simulator rules shared by the browser and the server: fees, margin, triggers, liquidation |
src/lib/sim.ts | Guest mode, kept in local storage |
src/lib/features.ts | The market context captured at entry |
src/lib/agent.ts | The agent's model |
src/lib/readiness.ts | The readiness checks |
src/lib/stats.ts | Track-record statistics |
src/lib/hyperliquid.ts | Market data in the browser |
src/server/ledger.ts | Orders, fills, trigger replay and the hash chain |
src/server/market.ts | Server-side prices and candles |
src/server/autonomous.ts | The agent trading on its own |
src/server/dataset.ts | Building the open dataset |
src/server/publish.ts | Publishing it through the GitHub App |
dataset/verify.mjs | The verifier shipped with the dataset |
src/components/sim/ | The terminal's interface, chart tools included |
A self-hosted copy has its own users, ledger and agents. Its records aren't part of Kinfield's dataset unless it publishes its own.