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.

The PolyClaw Trading macOS runner is a native Swift package that lives under Sources/PolyclawMacCore/ and Sources/PolyclawMac/. It replaces shell-specific workspace discovery, process launching, OpenClaw gateway startup, TUI retries, and the isolated Kilo worker loop with a single compiled CLI — no Python interpreter, no shell quoting edge cases, no external runtime required to start the system. The trading and risk logic stays entirely in Python; the Swift layer is purely a process supervisor and safe environment loader.

​
What the Runner Does

The polyclaw-mac binary handles everything that previously required per-shell scripts:
  • Workspace discovery — resolves the checkout path from the current directory or the OPENCLAW_WORKSPACE environment variable
  • Safe .env.local loading — reads key/value pairs without echoing sensitive values to the terminal
  • Process launching — starts the Python pipeline, OpenClaw gateway, OpenClaw TUI, and the Kilo worker loop as managed subprocesses
  • TUI retry logic — handles gateway startup races without manual sleep hacks in shell scripts
  • Kilo worker isolation — stores the Kilo profile under runtime/kilo-worker-* so it never disturbs the primary ~/.local/share/kilo profile
  • Dry-run pinning — the dry-run command forces LIVE_TRADING=0 and ALLOW_REDEEM=0 even if the inherited environment or .env.local says otherwise
JSON files under runtime/ remain the language boundary between the Swift runner and the Python modules. This design means trading stages can be individually migrated to Swift later without changing the inter-process contract.

​
Package Structure

The Swift package (Package.swift) targets macOS 13+ and produces three products: 
// swift-tools-version: 5.9

import PackageDescription

let package = Package(
  name: "PolyclawMac",
  platforms: [
    .macOS(.v13)
  ],
  products: [
    .library(name: "PolyclawMacCore", targets: ["PolyclawMacCore"]),
    .executable(name: "polyclaw-mac", targets: ["PolyclawMac"]),
    .executable(
      name: "polyclaw-mac-selftest",
      targets: ["PolyclawMacSelfTests"]
    ),
  ],
  targets: [
    .target(name: "PolyclawMacCore"),
    .executableTarget(
      name: "PolyclawMac",
      dependencies: ["PolyclawMacCore"]
    ),
    .executableTarget(
      name: "PolyclawMacSelfTests",
      dependencies: ["PolyclawMacCore"],
      path: "tests/PolyclawMacSelfTests"
    ),
  ]
)
  • PolyclawMacCore — reusable library: dotenv safety, process handling, workspace resolution
  • polyclaw-mac — the operator CLI
  • polyclaw-mac-selftest — dependency-free self-test executable covering CLI parsing, dry-run pinning, and workspace discovery

​
Installation

1

Install Xcode Command Line Tools

The Swift compiler is part of the Xcode command line tools. If you already have Xcode installed, you may already have them. Otherwise:
xcode-select --install
Confirm the installation by checking the Swift version:
swift --version
2

Run the self-test

Before building the release binary, run the built-in self-test. It requires no secrets and no network access:
swift run polyclaw-mac-selftest
This runs the dependency-free Swift self-tests for CLI parsing, dry-run pinning, and workspace discovery. All tests must pass before proceeding.
3

Build the release binary

swift build -c release
The compiled binary is placed at .build/release/polyclaw-mac. You can invoke it from the repository root without adding it to PATH:
.build/release/polyclaw-mac doctor
Or copy it to a directory on your PATH:
cp .build/release/polyclaw-mac /usr/local/bin/polyclaw-mac
4

Run the preflight check

.build/release/polyclaw-mac doctor
The doctor command validates that the workspace is correctly structured, .env.local is present, Python and uv are available, and the runtime directory exists.

​
Available Commands

# Preflight check — validates workspace, env, and dependencies
.build/release/polyclaw-mac doctor

# Run the test suite (audit subset — no secrets or network required)
.build/release/polyclaw-mac audit

# Dry-run pipeline pass (default; pins LIVE_TRADING=0 and ALLOW_REDEEM=0)
.build/release/polyclaw-mac run

# Live execution — requires the explicit flag; no shortcut
.build/release/polyclaw-mac run live --confirm-live

# One Kilo LLM analysis pass (isolated worker profile)
.build/release/polyclaw-mac kilo-worker --once
run live --confirm-live sends real orders through PolyClaw. The --confirm-live flag is required and cannot be omitted. Complete the manual wallet approval step before using this command for the first time.

​
Workspace Discovery

The runner resolves the checkout path in this order:
  1. The OPENCLAW_WORKSPACE environment variable, if set
  2. The current working directory
# Explicit workspace path
OPENCLAW_WORKSPACE=/opt/polyclaw-trading .build/release/polyclaw-mac run

# Implicit: run from the checkout directory
cd /opt/polyclaw-trading
.build/release/polyclaw-mac run
Setting OPENCLAW_WORKSPACE is recommended when running the binary from launchd, cron, or any context where the working directory is not guaranteed to be the repository root.

​
Environment Loading

The runner reads .env.local from the resolved workspace directory. Values are loaded without being echoed to the terminal or written to any log. The runner prefers .venv/uv for Python resolution, matching the same preference order as the native shell launchers.

​
Log Output

Pipeline output is written to runtime/macos-runner.log inside the resolved workspace. You can tail it while the runner is active: 
tail -f runtime/macos-runner.log

​
Dry-Run Safety Guarantee

The run command (without live --confirm-live) unconditionally pins: 
LIVE_TRADING=0
ALLOW_REDEEM=0
These values are set by the runner itself before the Python pipeline starts, overriding any value in .env.local or the inherited shell environment. There is no configuration that can make polyclaw-mac run send a live order.

​
Language Boundary

The Swift runner and the Python modules communicate exclusively through versioned JSON files under runtime/. The runner never inspects, parses, or modifies trade logic. This clean boundary means:
  • Trading stages can be migrated to Swift independently, one at a time
  • Any Python stage can be replaced or tested in isolation without rebuilding the runner
  • The full contract is documented in runtime/README.md

Build docs developers (and LLMs) love

Get started for freeTalk to us