docs/setup/QUICKSTART.md
Rama main · réplica de lectura del repositorio original.
# Machine Setup Guide
> Works on any Windows, macOS, or Ubuntu machine.
> FlintTrade `v0.0.1` is not production ready; use Practice, and example data,
> before connecting any live broker workflow.
## 1. Install FlintTrade
FlintTrade is a self-hosted web app. The one-line installer needs nothing
pre-installed — no Python, no Node, no git, no bash and no make:
```bash
# macOS / Linux
curl -fsSL https://flinttrade.vercel.app/web-install.sh | bash
```
```powershell
# Windows 10/11
# Run in a normal (non-Administrator) PowerShell window
irm https://flinttrade.vercel.app/web-install.ps1 | iex
```
It provisions a pinned, checksum-verified toolchain (`uv`, Python 3.14, Node
and pnpm) under `~/.flinttrade/tools`, builds FlintTrade from a managed source
checkout at `~/.flinttrade/web-src/FlintTrade`, and installs a `flinttrade-web`
launcher. Open http://127.0.0.1:5100 and complete Setup — no `.env` file is
required.
Uninstalling keeps your workspace and data. Run **one** of these:
```bash
# macOS / Linux — keep data
curl -fsSL https://flinttrade.vercel.app/uninstall.sh | bash
# macOS / Linux — also delete recognised FlintTrade data (irreversible)
curl -fsSL https://flinttrade.vercel.app/uninstall.sh | bash -s -- --purge
```
```powershell
# Windows 10/11 — keep data
irm https://flinttrade.vercel.app/uninstall.ps1 | iex
# Windows 10/11 — also delete recognised FlintTrade data (irreversible)
& ([scriptblock]::Create((irm https://flinttrade.vercel.app/uninstall.ps1))) -Purge
```
### If the site is unreachable (repo-direct fallback)
Use this whenever any command above fails: the hosted URLs are only a redirect
to the scripts in this repository, so a site outage answers `503` rather than
the script. Fetch the same files straight from GitHub — swap
`flinttrade-web-install` for `flinttrade-uninstall` to remove FlintTrade:
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/navaneeshnagarajan/FlintTrade/main/scripts/install/flinttrade-web-install.sh | bash
```
```powershell
# Windows 10/11
# Run in a normal (non-Administrator) PowerShell window
irm https://raw.githubusercontent.com/navaneeshnagarajan/FlintTrade/main/scripts/install/flinttrade-web-install.ps1 | iex
```
Or run `scripts/install/flinttrade-web-install.sh` /
`scripts/install/flinttrade-uninstall.sh` (macOS/Linux), or the matching `.ps1`
files (Windows), from a clone instead.
### Electron desktop shell
The Electron desktop shell wraps that same local backend. The public download
surface distinguishes the source-built web-app install above from Electron
shell installers and withholds Electron commands and downloads unless one
release contains all four canonical installers plus `SHA256SUMS.txt`.
To build and verify the Electron shell locally (these lines run unchanged in
bash, zsh and Windows PowerShell):
```bash
git clone https://github.com/navaneeshnagarajan/FlintTrade.git
cd FlintTrade
pnpm install --frozen-lockfile
python scripts/ft.py desktop-test
python scripts/ft.py desktop-package
```
`make desktop-test` and `make desktop-package` are the POSIX aliases. Generated
packages live under `packages/apps/desktop/release/electron/`. On first launch
the shell verifies pinned tools, builds a managed source checkout, creates your
OS workspace and opens Setup after the guardian is healthy. No `.env` file is
required. See [the desktop guide](../DESKTOP.md) for the release availability,
source-bootstrap and ad-hoc macOS signing boundaries.
## 2. Contributor Source Setup
Use this only when developing FlintTrade from source.
`python scripts/ft.py <target>` is the cross-platform runner — it needs no make
and no bash, and behaves identically on Windows, macOS and Linux.
`make <target>` is the POSIX alias.
```bash
python scripts/ft.py setup
python scripts/ft.py dev
```
## 3. Configure Broker Access
A broker session cannot be started from the terminal today. Practice mode and example data work without a broker. Broker writes return 503 and broker reads return 409. Start with
Practice. Credentials belong in the encrypted gateway vault.
## 4. Start and Verify
Native app users can skip this section. Contributors running from source can
use:
The same three lines run unchanged in Windows PowerShell. On POSIX,
`make start`, `make status` and `make test` are aliases for the same targets.
## 5. Run Terminal
Native app users can skip this section. Contributors running from source can
use:
```bash
pnpm --filter @flinttrade/terminal dev # Terminal on http://localhost:5173
```
### Web UI (no desktop app)
The backend serves the built terminal itself, so a plain browser is a full
client. Build the terminal once, then start the backend and open
http://127.0.0.1:5100:
```bash
pnpm --filter @flinttrade/terminal build
python scripts/ft.py start
```
To reach it from another machine (for example over Tailscale), bind the backend
to that interface. The environment variable is set separately from the command
because Windows PowerShell has no `VAR=value command` prefix form:
```bash
# macOS / Linux
export FLINTTRADE_BACKEND_HOST=<tailnet-ip>
python scripts/ft.py start
```
```powershell
# Windows 10/11
$env:FLINTTRADE_BACKEND_HOST = "<tailnet-ip>"
python scripts/ft.py start
```
## 6. Start Building
Read [`contributing.md`](../../contributing.md) for the contribution flow, then check the [issue tracker](https://github.com/navaneeshnagarajan/FlintTrade/issues) — the `good first issue` label is a good place to land your first PR. If you use a CLAUDE-aware or AGENTS-aware coding agent (Claude Code, Cursor, Aider, Continue, Codex, etc.), run `bash scripts/setup-agent-context.sh` once to scaffold your machine-local agent context. That helper is a bash script: on Windows run it in WSL2 or Git Bash, or copy the templates from `templates/agent-context/` by hand.
---
## Terminal Env
There is no terminal-side `.env` template. Vite proxy overrides are developer
only, and production/native connection settings must come from Setup or
Settings so they remain runtime user choices rather than build-time bundle
constants.