Getting Started

The first-run goal

The first successful setup should prove three things before any paper cycle:

• the local Python runtime can start
• provider, model, broker, and runtime-mode readiness are visible
• the operator surfaces reflect lower-layer truth instead of inventing state

Start with the checks below. If one fails, fix that layer before trusting the Web GUI, Ink TUI, or any background service.

Source install requirements

The repository currently assumes a Python plus Node workflow. The Python runtime still owns the actual trading logic, while webgui/, docs/, and tui/ are managed from the root pnpm workspace.

Recommended baseline:

• Python 3.13.x through uv-managed .venv
• uv for Python dependency management
• Node 20+ and pnpm
• Optional: tmux, asciinema, and browser tooling for QA
• Optional: Ollama if you are using the default local model path
• Optional: Firecrawl and Camofox when you explicitly enable research helpers

Before installing everything, run the system-tool dry run:

make bootstrap-dry-run

If the plan looks right, use the interactive bootstrap:

make bootstrap

It asks before system installs, browser-helper dependencies, Firecrawl setup, or PATH symlink changes. Missing optional research helpers are degraded readiness, not a blocker for core paper operation.

Install the Python runtime

uv python install 3.13
pnpm run install:python

Install the Node workspace from the repository root:

pnpm install
pnpm approve-builds --all

After uv is available, use either shortcut:

pnpm run setup
# or
make setup

Check readiness before trading

Run these checks before a paper cycle:

python main.py doctor
agentic-trader provider-diagnostics --json
agentic-trader v1-readiness --json
agentic-trader finance-ops --json

If you rely on the installed CLI entrypoint, validate that too:

agentic-trader doctor

Do this before debugging the Web GUI or Ink TUI. If doctor is already wrong, the UI is usually reflecting a real lower-layer problem. provider-diagnostics shows the current source ladder, API-key readiness, and fallback warnings without fetching secrets or pretending missing evidence is complete. v1-readiness shows whether local paper operation and Alpaca paper readiness gates are satisfied; add --provider-check when you intentionally want it to call the configured model service.

What readiness means

Configure environment files

The project follows an example-plus-local-override pattern.

• Root runtime settings should live in .env.local.
• Keep tracked examples in .env.example.
• The GitHub Pages docs build does not need docs/.env.local.

Docs feedback on Pages prepares a browser-local GitHub issue draft. If a future Node-hosted docs instance re-enables server-side forwarding, keep its credentials in docs/.env.local and never in tracked config.

Local model setup

The repo is still Ollama-oriented by default, but the direction is becoming more provider-aware. Typical local model settings look like this:

export AGENTIC_TRADER_MODEL_NAME=qwen3:8b
export AGENTIC_TRADER_BASE_URL=http://localhost:11434/v1

Do not treat raw Ollama traffic as proof that the system is healthy. Model reachability, runtime readiness, and recent logs should agree.

If you want Agentic Trader to own the local Ollama process for this project, start with the read-only status and then start the app-owned service:

agentic-trader model-service status --json
agentic-trader model-service start
agentic-trader model-service pull qwen3:8b

The app-managed service binds to loopback only, writes its own state and log tails under runtime/model_service/, and never stops an external Ollama process. If another Ollama is already running on the default port, the app-managed service chooses another loopback port and reports whether AGENTIC_TRADER_BASE_URL matches it.

Run one safe paper cycle

Run one strict cycle:

python main.py run --symbol AAPL --interval 1d --lookback 180d

Then inspect the review output, dashboard/status JSON, and any evidence bundle before treating the run as a trustworthy example.

Bring up the main surfaces

Open the operator launcher:

agentic-trader

Open the Ink control room directly:

agentic-trader tui

Run the Web GUI as an app-owned loopback service:

agentic-trader webgui-service start

Or run it as a foreground development server:

pnpm dev:webgui

Run the docs site locally:

pnpm dev:docs

Run the Ink TUI directly:

pnpm start:tui
AGENTIC_TRADER_UI_LOCALE=tr pnpm start:tui

Terminal surfaces share the Python locale setting. Use agentic-trader --locale tr locale --json for a one-command preview or agentic-trader locale --set tr to persist AGENTIC_TRADER_UI_LOCALE=tr in the local environment file.

First places to inspect when something feels wrong

• doctor output
• provider-diagnostics --json
• v1-readiness --json
• broker-status --json
• finance-ops --json
• supervisor-status --json
• runtime status in the CLI or observer surface
• recent runtime logs
• model service readiness
• latest review or trade context
• environment file differences between the repo root and nested apps

Near-term onboarding direction

The intended V1 hardening path is:

1. platform-aware prerequisite detection
2. optional provider and model setup
3. environment creation and dependency install
4. readiness validation
5. automatic launch into the Web GUI and docs surface

That future flow should reduce setup friction without hiding failures.