File size: 3,617 Bytes
9fe4fad a746412 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | ---
title: Getting Started
summary: Install TerraFin, configure the runtime, and run the first Python, CLI, and hosted-agent flows.
---
# Getting Started
This page is the shortest path from clone to a working TerraFin environment.
## Prerequisites
- Python 3.11+
- A local `.env` file if you want FRED, SEC EDGAR, private-access widgets, or
hosted-model credentials
## Install
Core install:
```bash
pip install .
```
Editable install:
```bash
pip install -e .
```
Useful extras:
```bash
pip install -e ".[dev]"
pip install -e ".[db]"
pip install -e ".[notebooks]"
```
## Configure The Runtime
Start with the example file:
```bash
cp .env.example .env
```
The most common env vars are:
| Variable | Why you care |
|----------|---------------|
| `FRED_API_KEY` | Enables FRED-backed economic series |
| `TERRAFIN_SEC_USER_AGENT` | Required for SEC EDGAR filings and guru 13F holdings |
| `TERRAFIN_HOST` / `TERRAFIN_PORT` | Server bind address |
| `TERRAFIN_AGENT_MODEL_REF` | Hosted model ref in `provider/model` format |
| `TERRAFIN_AGENT_TRANSCRIPT_DIR` | Optional override for local hosted chat history storage |
For the full matrix, read [Configuration](configuration.md).
## First Python Request
```python
from TerraFin import configure
from TerraFin.data import DataFactory
configure()
data = DataFactory()
spy = data.get("S&P 500")
aapl = data.get("AAPL")
```
## First CLI Request
```bash
terrafin-agent snapshot AAPL
terrafin-agent macro-focus "S&P 500" --view weekly
```
## First Hosted Agent Session
```bash
terrafin-agent runtime-create-session terrafin-assistant
```
Then send a message:
```bash
terrafin-agent runtime-message runtime:example "Give me a compact AAPL market snapshot."
```
The hosted assistant can also be used from the browser widget once the
interface server is running.
Hosted agent chat history is stored locally as transcript files under
`.terrafin/agent/sessions/` by default.
## Run The Interface
From `src/TerraFin/interface/`:
```bash
python server.py run
```
Useful commands:
| Command | Behavior |
|---------|----------|
| `python server.py run` | Run in the foreground |
| `python server.py start` | Start in the background |
| `python server.py stop` | Stop the background process |
| `python server.py status` | Show whether the background process is running |
| `python server.py restart` | Restart the background process |
Default pages:
| URL | Purpose |
|-----|---------|
| `http://127.0.0.1:8001/chart` | Interactive chart surface |
| `http://127.0.0.1:8001/dashboard` | Dashboard and cache status |
| `http://127.0.0.1:8001/market-insights` | Macro and portfolio views |
| `http://127.0.0.1:8001/stock/AAPL` | Stock analysis page |
| `http://127.0.0.1:8001/calendar` | Earnings and macro calendar |
## Notebooks And Scripts
Keep notebook setup explicit:
```python
from TerraFin import configure, load_terrafin_config
configure()
config = load_terrafin_config()
```
Use `configure(dotenv_path="/absolute/path/to/.env")` if the kernel is not
started from a directory where TerraFin can discover `.env` normally.
Notebook rules and layout guidance live in [Notebooks](notebooks.md).
## Next Reads
- [Configuration](configuration.md)
- [Deployment & Operations](deployment.md)
- [Examples & Workflows](examples.md)
- [Agent Docs](agent/index.md) — both Hosted TerraFin Agent (Mode A) and the
external-agent skill / HTTP surface (Mode B).
- [TerraFin skill on GitHub](https://github.com/KiUngSong/TerraFin/blob/main/skills/terrafin/SKILL.md) —
drop-in for Claude Code / Codex (`cp -r skills/terrafin ~/.claude/skills/`).
|