Reference

Run Kinfield yourself

Set up the code locally: database, GitHub sign-in, scheduled jobs and the dataset publisher.

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 postgres client; 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:3000

The 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 dev

For 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

VariableNeeded forNotes
DATABASE_URLAccounts, ledger, agentsAny Postgres connection string.
GITHUB_CLIENT_IDGitHub sign-inFrom your OAuth app.
GITHUB_CLIENT_SECRETGitHub sign-inFrom your OAuth app.
DEV_LOGINLocal sign-in1 to enable. Never active in production.
CRON_SECRETScheduled jobsA long random string, sent as a bearer token.
GITHUB_APP_IDDataset publishingA GitHub App installed only on the dataset repository.
GITHUB_APP_PRIVATE_KEYDataset publishingThat app's private key.
DATASET_REPODataset publishingDefaults to KinfieldLabs/kinfield-datasets.
DATASET_OUT_DIRLocal dry runsWhere 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.

MigrationAdds
001_initUsers, sessions, simulated accounts, positions and the ledger
002_orders_tpslResting limit orders, take profit and stop loss
003_datasetSharing choices, reason salts and publish tracking
004_autonomous_agentAgent accounts, agent state and run history
005_kin_agent_namesKIN 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.

PathScheduleDoes
/api/cron/agentsEvery 15 minutesRuns every taught agent. See The agent trading on its own.
/api/cron/publish03:00 UTC dailyPublishes 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

PathWhat it holds
src/lib/sim-core.tsSimulator rules shared by the browser and the server: fees, margin, triggers, liquidation
src/lib/sim.tsGuest mode, kept in local storage
src/lib/features.tsThe market context captured at entry
src/lib/agent.tsThe agent's model
src/lib/readiness.tsThe readiness checks
src/lib/stats.tsTrack-record statistics
src/lib/hyperliquid.tsMarket data in the browser
src/server/ledger.tsOrders, fills, trigger replay and the hash chain
src/server/market.tsServer-side prices and candles
src/server/autonomous.tsThe agent trading on its own
src/server/dataset.tsBuilding the open dataset
src/server/publish.tsPublishing it through the GitHub App
dataset/verify.mjsThe 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.