Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deniszidbaev-cmyk/polyclaw-trading/llms.txt

Use this file to discover all available pages before exploring further.

PolyClaw Trading supports a portable deployment model for Linux and macOS VPS instances. The scripts/create_portable_bundle.ps1 script assembles a self-contained ZIP — source code, launcher scripts, the Swift native runner, and an optional runtime snapshot — that can be copied to any server and started immediately. Every execution is journaled locally in runtime/executions/, and the cron_run.sh script makes scheduled recurring runs straightforward.

​
Creating the Portable Bundle

The bundle script is a PowerShell script that runs on Windows (or on Linux/macOS with pwsh). It stages files into a timestamped directory under dist/ and compresses them into a ZIP: 
# Default: creates dist/kilo-claw-vps-YYYYMMDD-HHmmss/ and a matching .zip
pwsh -File scripts/create_portable_bundle.ps1

# Custom output directory and bundle name
pwsh -File scripts/create_portable_bundle.ps1 -OutputDir C:\deploy -BundleName polyclaw-prod

# Include opaque secret-bearing files (use only for machine-to-machine transfers)
pwsh -File scripts/create_portable_bundle.ps1 -IncludeSecrets
By default the bundle excludes .env.local, openclaw.json, and all runtime state. This makes it safe to store in version control or share without exposing secrets. Use -IncludeSecrets only for direct machine-to-machine transfers where the ZIP is treated as sensitive material.
The bundle includes:
  • Root launcher scripts (*.sh, *.cmd, *.bat)
  • Dockerfile and docker-compose.yml
  • Package.swift and Sources/ (the native macOS runner)
  • All Python source under src/, scripts/, bot/, openclaw_bot/, llm_clients/
  • prompts/ (editable LLM role prompts)
  • tests/ (audit suite)
  • A runtime snapshot (empty executions/ and logs/ directories, plus any existing JSON state files excluding market_reports.lock)

​
Self-Verifying Plugin Build

The scripts/build_plugin.py script produces an OpenClaw plugin bundle in dist/. The build is self-verifying: the staged tree must pass the audit test set before the ZIP is written. A SHA-256 checksum is included in the bundle manifest. 
uv run python scripts/build_plugin.py

# Skip the audit verification step (for CI smoke tests only)
uv run python scripts/build_plugin.py --skip-verify
The plugin bundle lands at dist/polyclaw-trading-plugin-<version>.zip and includes an openclaw.plugin.json manifest with the plugin ID, version, and configSchema for the safety-critical environment variables.

​
VPS Requirements

Any Linux or macOS VPS will work. The requirements are minimal:
  • Python 3.12+ — python3 --version to verify
  • uv — pip install uv or see the uv install docs
  • git — git --version to verify
  • SSH key authentication — recommended over password auth
If you are deploying the Swift native runner, you additionally need:
  • Xcode command line tools (macOS) — xcode-select --install

​
Deploying to a VPS

1

Transfer the bundle

Copy the ZIP to your server using scp or rsync:
scp dist/kilo-claw-vps-20250101-120000.zip user@your-vps:/opt/

# Or with rsync for incremental updates
rsync -avz dist/kilo-claw-vps-20250101-120000.zip user@your-vps:/opt/
2

Unpack and install dependencies

ssh user@your-vps
cd /opt
unzip kilo-claw-vps-20250101-120000.zip
cd kilo-claw-vps-20250101-120000
uv sync
3

Configure the environment

Copy the example file and fill in your values. Keep file permissions to 600 so only your user can read it:
cp .env.example .env.local
chmod 600 .env.local
$EDITOR .env.local
At minimum you need:
POLYMARKET_WALLET_ADDRESS=0x...
CHAINSTACK_NODE=https://...
OPENROUTER_API_KEY=sk-...
LIVE_TRADING=0
4

Run the audit to verify the setup

uv run python scripts/run_pipeline.py audit
All tests should pass with no secrets or network access required.
5

Run a dry-run pass

Make the scripts executable and run one pipeline pass:
chmod +x cron_run.sh scripts/*.sh
./cron_run.sh dry-run
Output is appended to runtime/cron_status.log.

​
cron_run.sh

cron_run.sh is the recommended entry point for recurring scheduled runs on Linux and macOS. It refreshes bankroll state, runs the pipeline in the specified mode, and logs timestamps and exit codes to runtime/cron_status.log: 
#!/bin/bash
# Usage: ./cron_run.sh [dry-run|live]

MODE="${1:-dry-run}"
WORKSPACE="${OPENCLAW_WORKSPACE:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
LOGDIR="$WORKSPACE/runtime"
Run modes: 
# One dry-run pass (safe default)
./cron_run.sh dry-run

# One live pass (requires LIVE_TRADING=1 in .env.local)
./cron_run.sh live
cron_run.sh resolves the workspace path from OPENCLAW_WORKSPACE first, then falls back to the script’s own directory. When running from cron or launchd, the working directory is not guaranteed to be the repository root — always set OPENCLAW_WORKSPACE explicitly in your cron entry:
OPENCLAW_WORKSPACE=/opt/polyclaw-trading

​
Example cron Entry

# Edit crontab
crontab -e

# Dry-run every 5 minutes
*/5 * * * * OPENCLAW_WORKSPACE=/opt/polyclaw-trading /opt/polyclaw-trading/cron_run.sh dry-run >> /opt/polyclaw-trading/runtime/cron_status.log 2>&1

​
Google Cloud VPS Setup

The repository includes a Google Cloud-specific setup helper. On Windows it delegates to PowerShell; on the VPS it can be run directly: 
REM Windows
scripts\run_google_setup_vps.cmd

# PowerShell directly
pwsh -File scripts/run_google_setup_vps.ps1
The script pulls a Docker image (ghcr.io/kilo-org/google-setup:latest) and runs the Kilo setup container with your setup token. The token is read from KILO_SETUP_TOKEN if set, or prompted securely at the terminal.

​
Security Notes

Never commit .env.local to git. It is listed in .gitignore and tests/test_secret_scanner.py will fail the build if secret-like patterns appear in any tracked file. If you accidentally commit secrets, rotate them immediately and purge the commit from history.
  • Set .env.local permissions to 600: chmod 600 .env.local
  • Use SSH key authentication on your VPS; disable password authentication
  • The real OpenClaw home config (~/.openclaw/openclaw.json) is modified exclusively through openclaw_patch.py, which takes a timestamped backup before every patch
  • Never pass secrets as command-line arguments — they appear in ps aux and shell history
  • Keep the runtime/ directory on a filesystem accessible only to your user account

​
Runtime Directory Layout

All pipeline output lands in runtime/. The layout is consistent across Docker, native macOS, Windows, and VPS deployments:
PathContents
runtime/decisions.jsonLatest trade decisions from the deterministic engine
runtime/bankroll_state.jsonCurrent equity, reserve, and risk limit state
runtime/trade_history.jsonFull history of all trade decisions
runtime/open_positions_snapshot.jsonCurrent open positions
runtime/manual_review.jsonFallback queue when no usable candle feed exists
runtime/executions/YYYYMMDD.jsonDaily execution ledger (dry-run and live)
runtime/cron_status.logTimestamps and exit codes from cron_run.sh
runtime/macos-runner.logOutput from the Swift macOS runner
runtime/kilo-worker-*/Isolated Kilo worker profile directories
runtime/logs/Additional service logs
Dry-run executions are recorded in the daily ledger just like live executions, so behavior is fully auditable before going live.

​
Repository Layout Boundaries

The repository is an intentional polyglot workspace where each language has one bounded responsibility:
LayerResponsibility
PythonTrading logic, risk management, orchestration, dashboard, operator CLIs
SwiftSources/ and tests/PolyclawMacSelfTests/ only; launches Python through file/CLI contracts
Shell / CMD / Batch / PowerShellPlatform launchers only; no business rules
JavaScript / TypeScriptConfined to extensions/kimi-claw and extensions/kimi-search
New reusable library code belongs under src/. New operator-only commands belong under scripts/. Business rules must not be implemented in launcher scripts.

Build docs developers (and LLMs) love

Get started for freeTalk to us