Skip to content

QUICKSTART.md

Latest commit

 

History

History
309 lines (208 loc) · 9.33 KB

QUICKSTART.md

File metadata and controls

309 lines (208 loc) · 9.33 KB
Raw

Quickstart

Use this guide when you want to run Trench Tools on a local Windows or Linux machine. If you are starting from a fresh VPS, use VPS_SETUP.md instead; the VPS path can be up in about 5-10 minutes with the startup script and a Helius Developer tier plan.

If setup feels annoying, it is completely fine to use an AI coding assistant to help. Cursor, Codex, Claude, and similar tools can walk through dependency installs, .env editing, startup commands, and log errors.

What You Are Starting

  • execution engine (execution-engine, http://127.0.0.1:8788) handles extension trades, wallets, presets, fee/route resolution, sends, confirmations, and PnL events.
  • Trench Tools extension injects into supported terminals and talks to the execution engine for trading.
  • LaunchDeck (launchdeck-engine, http://127.0.0.1:8789, plus launchdeck-follow-daemon on 8790) handles launchpad deploy/snipe/follow flows.

Run both when you want the full stack. Run ee when you only need extension trading.

1. Install Dependencies

Windows

Use PowerShell.

Install:

After first installing Rust, reopen PowerShell.

Linux

These commands assume Debian or Ubuntu. On another distro, install the equivalent packages.

sudo apt-get update
sudo apt-get install -y git curl build-essential pkg-config libssl-dev
curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"

Install Node.js 20. One common Linux path is nvm:

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 20
nvm use 20

2. Install Project Dependencies

Clone the repository if you do not already have it:

git clone https://github.com/0xD3bt/Trench-Tools.git
cd Trench-Tools

Then install dependencies from the repo root:

npm install

3. Create .env

Copy the starter file:

Windows:

Copy-Item .env.example .env

Linux:

cp .env.example .env

Fill the practical starter values:

  • SOLANA_PRIVATE_KEY or the SOLANA_PRIVATE_KEY* wallet slots you want to load
  • SOLANA_RPC_URL
  • SOLANA_WS_URL
  • USER_REGION
  • TRENCH_TOOL_FEE only if you want to turn the voluntary fee off or increase it
  • WARM_RPC_URL moves compatible warm/cache traffic off the primary RPC
  • HELLOMOON_API_KEY only if you want Hello Moon
  • BAGS_API_KEY only if you use Bags launchpad flows
  • LAUNCHDECK_METADATA_UPLOAD_PROVIDER=pinata and PINATA_JWT for the recommended Pump/Bonk metadata upload path

Recommended Helius/Shyft examples:

SOLANA_RPC_URL=https://beta.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY
SOLANA_WS_URL=wss://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY
WARM_RPC_URL=https://rpc.shyft.to?api_key=YOUR_SHYFT_API_KEY
WARM_WS_URL=wss://rpc.shyft.to?api_key=YOUR_SHYFT_API_KEY

Put your Helius key immediately after api-key=. Put your Shyft key immediately after api_key=.

For LaunchDeck Pump/Bonk metadata uploads, Pinata is recommended and the free tier is enough for normal use. Create a free account at pinata.cloud, create an API key, copy the JWT, and set:

LAUNCHDECK_METADATA_UPLOAD_PROVIDER=pinata
PINATA_JWT=YOUR_PINATA_JWT

For the full list of advanced options, see .env.advanced and ENV_REFERENCE.md.

4. Choose A Run Mode

Choose what you want to run in .env:

# blank also means both
TRENCH_TOOLS_MODE=both

Modes:

  • ee - execution-engine only. Use this for extension trading and PnL.
  • ld - launchdeck-engine plus launchdeck-follow-daemon. Use this for standalone LaunchDeck.
  • both - all three processes. This is the normal full setup.

Then use the simple repo-root commands:

npm start
npm stop
npm restart

You can still override the mode for a one-off run.

Windows:

.\trench-tools-start.ps1 --mode both

If PowerShell blocks direct script execution, use the npm command above or run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\trench-tools-start.ps1 --mode both

Linux:

./trench-tools-start.sh --mode both

The first startup can take a few minutes while Rust builds the binaries. Later starts should be much faster.

After startup passes health checks, the launcher exits and leaves the selected services running in the background. Use npm stop when you want to stop them.

VPS + Local Browser Tunnel

If Trench Tools runs on a VPS but Chrome/Edge runs on your own computer, your browser cannot directly see the VPS loopback ports. 127.0.0.1 in the browser means your computer, not the VPS.

That VPS setup is the recommended real trading path because it keeps services private and lets you run closer to RPC/provider endpoints. Follow VPS_SETUP.md for the full 5-10 minute startup-script flow.

Minimum tunnel command:

ssh -L 8788:127.0.0.1:8788 -L 8789:127.0.0.1:8789 root@YOUR_SERVER_IP

Keep that SSH session open while using the browser. With the tunnel open, the extension Options page still uses local-looking URLs:

  • Execution host URL -> http://127.0.0.1:8788
  • LaunchDeck host URL -> http://127.0.0.1:8789

Quick checks from the browser machine:

Test-NetConnection 127.0.0.1 -Port 8788
Test-NetConnection 127.0.0.1 -Port 8789

Linux:

curl http://127.0.0.1:8788/api/extension/auth/bootstrap
curl http://127.0.0.1:8789/health

5. Find The Auth Token

The shared default bearer token is written here after startup:

.local/trench-tools/default-engine-token.txt

Read it from the repo root.

Windows:

Get-Content .local\trench-tools\default-engine-token.txt

Linux:

cat .local/trench-tools/default-engine-token.txt

Use the contents of that file in the extension Options page:

  • Execution host URL -> http://127.0.0.1:8788
  • LaunchDeck host URL -> http://127.0.0.1:8789
  • Shared access token -> paste the token from .local/trench-tools/default-engine-token.txt

The same token authenticates the extension to both execution-engine and launchdeck-engine.

6. Install The Extension

Follow EXTENSION.md for the full guide. Short version:

  1. Open Chrome or Edge.
  2. Open chrome://extensions or edge://extensions.
  3. Enable Developer mode.
  4. Download trench-tools-extension.zip from the latest extension release to the PC running Chrome/Edge and unzip it.
  5. Click Load unpacked.
  6. Select the unzipped trench-tools-extension folder. If you are using a git checkout, select extension/trench-tools.
  7. Open the extension Options page and fill the host URLs and shared access token.

EXTENSION.md shows the packaged zip link, full-repo option, and git sparse-checkout flow if you only want to pull extension/trench-tools.

Unpacked Chrome/Edge extensions do not auto-update. After each Trench Tools patch, download the latest trench-tools-extension.zip again, replace the old unzipped folder, and click reload for Trench Tools on chrome://extensions or edge://extensions. Store distribution is planned once extension updates are less frequent.

7. Verify Setup

Before using real size:

  • execution-engine is reachable on http://127.0.0.1:8788
  • launchdeck-engine is reachable on http://127.0.0.1:8789 when running both or ld
  • auth token exists at .local/trench-tools/default-engine-token.txt
  • extension Options -> Global settings shows the expected host connection state
  • Axiom shows the enabled Trench Tools surfaces
  • J7Tracker shows the enabled Trench Tools surfaces
  • the toolbar popup shows host status, active preset, wallet/group selection, and quick-buy amount

Start with a small test amount and the recommended providers: Helius Sender or Hello Moon.

First Extension Use

For the first live test, keep the flow simple:

  1. Open the Trench Tools toolbar popup.
  2. Confirm it is connected to the host.
  3. Choose one execution preset.
  4. Choose one wallet or wallet group.
  5. Set a small quick-buy amount, or leave it blank and use the panel buttons.
  6. Open Axiom and refresh the page after changing Options.

The popup and panel share the same selection. If you change the preset or wallets in the popup, the Axiom controls use that selection too.

8. Stop The Runtime

Use the simple command first:

npm stop

Or stop a specific one-off mode directly.

Windows:

.\trench-tools-stop.ps1 --mode both

Linux:

./trench-tools-stop.sh --mode both

Logs

If startup fails, check:

Windows:

.local\logs\execution-engine.log
.local\logs\execution-engine.stderr.log
.local\logs\launchdeck-engine.log
.local\logs\launchdeck-engine.stderr.log
.local\logs\launchdeck-follow-daemon.log
.local\logs\launchdeck-follow-daemon.stderr.log

Linux:

.local/logs/execution-engine.log
.local/logs/launchdeck-engine.log
.local/logs/launchdeck-follow-daemon.log

For common issues, see TROUBLESHOOTING.md.