Expected installation behavior — 0.4.11-beta

This describes intended source behavior, not a clean-device certification. Use the matching reviewer evidence and inspect actual effects on a disposable Windows environment. Do not supply real broker credentials for installation QA.

First setup and normal launch

Extract program files to a local folder writable by your Windows user. Review Start Ballast.pyw before opening it. Python 3.11 or newer, including Tcl/Tk and the Windows .pyw file association, is a separately installed prerequisite; the reviewed build environment is recorded in the SBOM. The .pyw entry opens a responsive setup window when setup is needed. It creates .venv under the extracted folder and installs pinned bootstrap and runtime wheels using pip's isolated/hash/wheel-only options. These child processes use hidden windows; progress and sanitized failure guidance appear in the setup window. The .venv/ballast-ready marker is replaced atomically only after both installation stages succeed. Package traffic uses PyPI and its distribution infrastructure. Internet access is needed for uncached wheels.

A failed setup does not start Ballast or mark the environment ready. Retry in the setup window after checking connectivity, free disk space and folder access. An interrupted setup can be retried by reopening Start Ballast.pyw. Closing the window during a stage waits for that stage to finish and skips launch; it does not forcibly interrupt pip. Setup never removes a private profile. An unknown Start Ballast.new.bat is preserved and blocks launch pending update recovery.

Start Ballast.bat is a compatibility dispatcher to the same .pyw entry, without running pip itself. Double-clicking a batch file can briefly create a Windows console. An explicitly opened terminal is left open and usable. The default .pyw route is the windowless target; actual console visibility requires a disposable Windows acceptance test, beyond mocked process tests. If no Python file association exists, use the compatibility batch for prerequisite guidance.

Normal launches use .venv/Scripts/pythonw.exe and dashboard.launcher, then a loopback dashboard and an app/browser window. Hidden console windows are not hidden processes: inspect Python/browser processes normally in Windows. Closing the browser can leave the supervisor running. Use System > Quit Ballast for managed shutdown. No application step should require disabling antivirus, SmartScreen, UAC or execution policy.

New private state goes to the local Windows profile's Ballast/data directory. An existing ledger remains in place unless a verified offline migration is explicitly chosen. DATA_DIR can explicitly select another location; inspect the actual path in System. State includes SQLite, logs, update/recovery records and a DPAPI-protected local access vault. Saved credentials are encrypted; the complete trading database and backups are not encrypted by Ballast.

Persistence and network access

Login startup is off unless explicitly enabled. Enabling it records consent bound to this installation and creates a current-user startup shortcut. Disabling it removes that shortcut and consent. Migration can remove the earlier Ballast Watchdog scheduled task. Compatibility setup_scheduler.ps1/watchdog.ps1 filenames are not proof of automatically installed persistence; inspect their call paths.

The dashboard listens on 127.0.0.1, by default port 8600. A local launcher session, Host/Origin checks and mutation token protect private endpoints. No public hosting or inbound firewall exception is required for intended local use. The configured port can differ for a separate review installation.

Outbound behavior depends on features: broker authorization/account/trading requests; enabled market/news/data providers; paid AI requests when selected or permitted by configuration; Ballast release/referral services; configured alerts; and optional community sharing. UI assets and third-party provider links may create browser traffic. Source literal hosts are included in the companion as an inspection aid, with file/line references. Dynamic URLs, request payloads, redirects and actual runtime traffic still require review. API-DIRECTORY.md describes providers; a listed provider or saved key does not prove it works.

Updates and removal

Updates require user approval and verified release signatures/hashes, stage locked dependencies, stop managed processes, patch program-owned files and keep rollback evidence. Private state survives. A downloaded release is not proof that installation completed; check the running version afterward.

For removal, disable automatic startup, use Quit Ballast and verify its processes have stopped before removing the extracted program folder. Private data is separate and is deliberately not deleted by removing program files. Review the displayed storage path and backups, export anything needed, then choose whether to remove them. Never delete a private ledger while the app is running. Revoke provider credentials through the providers when appropriate. Removal cannot erase cloud history or cancel broker orders already submitted.

The disposable review launch keeps a separate profile, forces paper mode and disables scheduled cycles. It is not evidence of working live connections, reliable fills, or a full clean-Windows installation test.

Optional background paper worker (0.4.5)

When explicitly enabled while LIVE is selected, Ballast starts a hidden, below-normal-priority Python paper worker. It uses a paper-only temporary database under the private profile's paper-lab directory, public quote providers, and simulated orders. It makes no live orders or paid AI news calls. Live cycles cancel unfinished paper work; shutdown and a 180-second deadline stop abandoned workers. Failed or interrupted results are discarded. Completed results briefly update only paper state in the main database after a stale-source check. This is not a sandbox against malicious software running as your Windows user.

Launcher v2 authenticates the local server with a port-bound challenge and uses a one-use browser ticket. Updating from older versions invalidates old browser sessions once; reopen Start Ballast. The reusable DPAPI key is not sent to the listener.