> ## Documentation Index > Fetch the complete documentation index at: https://docs.trysinker.xyz/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Complete command reference for the sinker binary. ## Overview `sinker` is a single binary that starts the transaction sidecar **and** provides developer commands for inspecting its live state. No separate installation required — build once, use everywhere. ```bash theme={null} cd sinker cargo build --release ./target/release/sinker --help ``` *** ## Sidecar commands ### `sinker up` Start the full stack — sidecar **and** AI agent (Synapse) together in a single terminal. Both processes share stdout; agent lines are prefixed with `[ AGENT ]` to keep the streams readable. ```bash theme={null} sinker up ``` This is the recommended command for normal development and production. The Synapse layer connects to the sidecar via `/internal/agent/presence` on startup, registers its model/provider, and begins driving submissions. *** ### `sinker start` Start the sidecar only — without spawning the AI agent. The sidecar streams slots, maintains the tip oracle and leader buffer, and exposes the HTTP API. The Synapse agent must be started separately (e.g. `sinker agent` in another terminal). ```bash theme={null} sinker start ``` **Decision mode** defaults to `cortex` (LLM on every submission). Set `AGENT_DECISION_MODE=reflex` in `.env` to boot in reflex mode, or flip at runtime via `POST /internal/mode`. ### `sinker start --bypass` Skip the AI agent entirely. Submits transactions at a fixed tip the instant they are enqueued. Useful for testing the frontend → sidecar → Jito path without the AI layer. ```bash theme={null} sinker start --bypass sinker start --bypass --tip 50000 ``` | Flag | Description | | ------------------ | -------------------------------------------------------------------- | | `--bypass` | Disable Synapse; submit immediately on each `tx_enqueued` event | | `--tip ` | Fixed tip in lamports (default: `10000`). Only used with `--bypass`. | *** ### `sinker agent` Start the Synapse TypeScript agent in a separate process. Runs `npm run dev` inside the `agents/` directory (override with `AGENT_DIR` env var). ```bash theme={null} sinker agent ``` ### `sinker web` Start the Next.js dashboard. Runs `npm run dev` inside the `web/` directory (override with `WEB_DIR` env var). ```bash theme={null} sinker web ``` ### `sinker smoke` Run the `stream_smoke` integration test — connects to Yellowstone, waits for a Jito leader window, submits one bundle, and polls until finalization. ```bash theme={null} sinker smoke ``` *** ## Inspect commands Inspect commands query a **running sidecar** at `http://localhost:{API_PORT}` (default 7777). Start the sidecar first with `sinker start` or `sinker up`. ### `sinker status` Print a summary of the current sidecar state: slot, leader identity, whether the current leader is running Jito, tip floor (p50/p75), active decision mode, and pending queue depth. ```bash theme={null} $ sinker status ┌─ Sidecar Status ───────────────────────────────── │ slot : 318456201 │ leader : 9xRc… │ jito leader : true │ tip p50 : 9850 lamports │ tip p75 : 14200 lamports │ stale : false │ queue : 0 pending tx(s) └────────────────────────────────────────────────── ``` ### `sinker tip` Print the full tip floor percentile table. ```bash theme={null} $ sinker tip ┌─ Tip Floor Percentiles ────────────────────────── │ p25 : 6500 lamports │ p50 : 9850 lamports │ p75 : 14200 lamports │ p95 : 31000 lamports │ p99 : 75000 lamports │ ema : 9200 lamports │ stale: false └────────────────────────────────────────────────── ``` ### `sinker queue` Print the pending transaction queue contents with age and priority. ```bash theme={null} $ sinker queue pending: 2 (evicted_total: 0) tx_id=3fa2… age=3slots priority=normal tx_id=7b1c… age=1slots priority=high ``` ### `sinker lifecycle` Print recent bundle lifecycle history. Shows the most recent 10 entries by default. ```bash theme={null} sinker lifecycle sinker lifecycle --last 25 ``` ``` showing 3/3 entries (most recent last): bundle_id stage slot failure tip ────────────────────────────────────────────────────────────────────── 8f3a1b2c4d5e6f70 finalized 318456120 — 9850L 2e7d4c3b1a0f9e8d failed 318456185 fee_too_low 8000L 5c9a2f1e8b4d3c70 finalized 318456198 — 14200L ``` Each entry shows the decision tier (`reflex` / `cortex`) and whether the Reflex path escalated to the LLM. | Flag | Description | | ------------------- | --------------------------------------- | | `--last N` / `-l N` | Number of entries to show (default: 10) | ### `sinker bundle ` Print the full JSON lifecycle entry for a specific bundle, including the AI decision trace, commitment timeline (submitted → processed → confirmed → finalized), tip floor at submit time, and all transaction signatures. ```bash theme={null} sinker bundle 8f3a1b2c4d5e6f70abcdef1234567890abcdef12 ``` ```json theme={null} { "bundle_id": "8f3a1b2c4d5e6f70…", "stage": "finalized", "slot_submitted": 318456120, "tip_lamports": 9850, "decision_mode": "reflex", "escalated": false, "submitted_to_processed_ms": 412, "processed_to_confirmed_ms": 389, "confirmed_to_finalized_ms": 478, "transactions": ["5xKp…"], "ai_decision_trace": null } ``` *** ## Policy commands `sinker policy` gates what the Synapse agent is allowed to do — tip caps, retry limits, queue depth, and throughput controls. Settings persist in `sinker.policy.json` between restarts. ```bash theme={null} sinker policy show # print all values and override status sinker policy set max-tip 200000 # hard ceiling on tip size sinker policy set tip-percentile p95 # target a higher percentile sinker policy set max-retries 5 # retry up to 5 times before expiry sinker policy set expiry-slots 150 # drop bundles older than 150 slots sinker policy set escalation-step 5000 # max tip increase per retry (lamports) sinker policy set max-queue 10 # reject enqueues above 10 in-flight sinker policy set rate-limit 30 # max 30 tx/min across all callers sinker policy set priority high # pin all bundles to high priority sinker policy validate # check for contradictions sinker policy reset max-tip # reset one key to built-in default sinker policy reset # reset all keys sinker policy clear # delete file, revert all to defaults sinker policy export --path ./prod.json # save resolved policy for sharing sinker policy import ./prod.json # apply a saved policy ``` Full reference for all 10 policy keys and 7 sub-commands. *** ## The Synapse AI layer Sinker's AI layer — **Synapse** — is the decision junction that evaluates each transaction cycle and routes it to one of two tiers: | Tier | Trigger | Behaviour | Measured latency | | ---------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | **Reflex** | Every cycle (if `AGENT_DECISION_MODE=reflex`) | Deterministic fast-path: reads tip oracle, applies policy, submits. Escalates to the LLM only on hard cases (stale tip, fee rejection, escalation). | \~374 ms decision | | **Cortex** | Every cycle (default) | LLM called on every submission. Full reasoning trace attached to the lifecycle entry. Highest accuracy; slower. | \~4,200 ms decision | Both tiers are LLM-backed. Reflex routes most cycles deterministically and only calls the model when it encounters an edge case. Cortex calls the model unconditionally. ### Switching modes at runtime ```bash theme={null} # Via environment variable at startup AGENT_DECISION_MODE=reflex sinker start # Via API while running (no restart required) curl -X POST http://localhost:7777/internal/mode \ -H 'Content-Type: application/json' \ -d '{"decision_mode": "reflex"}' # Check current mode curl http://localhost:7777/internal/mode ``` ### Agent presence The Synapse agent keeps a persistent SSE connection open to `/internal/agent/presence`. When it connects, it registers its model and provider. Check agent status: ```bash theme={null} curl http://localhost:7777/internal/agent/info # {"model": "claude-opus-4-8", "provider": "anthropic"} ``` *** ## Environment variables | Variable | Default | Description | | ----------------------- | ------------------------------- | ------------------------------------------- | | `YELLOWSTONE_ENDPOINT` | required | Yellowstone gRPC endpoint | | `YELLOWSTONE_X_TOKEN` | — | Yellowstone auth token (if required) | | `RPC_URL` | required | Solana RPC URL (mainnet Helius recommended) | | `JITO_BLOCK_ENGINE_URL` | `mainnet.block-engine.jito.wtf` | Jito block engine | | `JITO_UUID` | — | Jito auth UUID for higher rate limits | | `KEYPAIR_PATH` | `~/.config/solana/id.json` | Path to signing keypair | | `API_PORT` | `7777` | Sidecar API port | | `AGENT_DECISION_MODE` | `cortex` | Boot decision tier: `cortex` or `reflex` | | `BYPASS_AGENT` | `0` | Set `1` to enable bypass mode via env | | `BYPASS_TIP_LAMPORTS` | `10000` | Fixed tip for bypass mode (lamports) | | `AGENT_DIR` | `../agents` | Directory for `sinker agent` | | `WEB_DIR` | `../web` | Directory for `sinker web` | | `SINKER_POLICY_FILE` | `./sinker.policy.json` | Custom path for the policy file | | `LIFECYCLE_PATH` | `./lifecycle.jsonl` | Path for the bundle audit log |