Investi / Docs

Setup Guide

Everything you need to get Investi up and running. The whole process takes about 5 minutes.

Investi needs two configuration files to work:

  • .env — API keys and credentials that connect Investi to external services (Telegram, OpenRouter, Alpaca, etc.)
  • config.yaml — Runtime settings like which AI models to use, how often to check the market, and credit thresholds

The one-line installer handles both for you interactively. If you prefer to set things up manually, this guide walks through every parameter.

Installation

Pick your install method. The rest of this guide will adapt commands to your choice.

Terminal
curl -fsSL https://tryinvesti.co/install.sh | bash

This checks dependencies, clones the repo, walks you through every API key, and optionally starts Investi. The fastest way to get going.

Terminal
git clone https://github.com/gabriansa/investi.git
cd investi
cp .env.example .env     # fill in your keys
docker compose --profile auto-update up -d

Runs a watcher alongside the bot that checks GitHub every minute and restarts automatically on new releases.

Terminal
git clone https://github.com/gabriansa/investi.git
cd investi
cp .env.example .env     # fill in your keys
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Clone the repo, set up a virtual environment, install dependencies, and run directly with Python.

API Keys · .env

Telegram Bot Token

Required
TELEGRAM_BOT_TOKEN

This token lets Investi send and receive messages through Telegram. It's the core communication channel between you and your agents.

How to get it
  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts to name your bot
  3. BotFather will reply with a token like 123456789:ABCdef...
  4. Paste it into your .env file

Telegram User ID

Required
TELEGRAM_USER_ID

Your personal Telegram numeric ID. Investi uses this to make sure only you can interact with the bot. Messages from anyone else are silently ignored.

How to get it
  1. Open Telegram and message @userinfobot
  2. It will instantly reply with your numeric ID (e.g. 1119063281)
  3. Paste it into your .env file
Important: Make sure you start a conversation with your bot (send it any message) before starting Investi. Otherwise the bot can't reach you.

OpenRouter API Key

Required
OPENROUTER_API_KEY

Investi's AI agents run on large language models accessed through OpenRouter. This key authorizes those API calls. You'll need to add some credit to your account — most usage costs a few cents per request.

How to get it
  1. Sign up at openrouter.ai
  2. Go to Keys and create a new API key
  3. Top up your balance with a few dollars
  4. Paste the key into your .env file

You can also set OPENROUTER_BASE_URL if you're using a custom endpoint. The default is https://openrouter.ai/api/v1.

Alpaca API Keys

Required
ALPACA_API_KEY & ALPACA_SECRET_KEY

Alpaca is the brokerage Investi uses to fetch market data and execute trades. We strongly recommend using Paper Trading keys so you can test risk-free with virtual money. When setting up your paper account you can choose your starting simulated balance — up to $1,000,000.

How to get it
  1. Create a free account at alpaca.markets
  2. Open your dashboard and navigate to Paper Trading
  3. Set your starting simulated balance (up to $1,000,000)
  4. Generate API keys (you'll get a key + secret pair)
  5. Paste both into your .env file
Paper vs Live: Paper trading keys let you test everything with fake money. Only switch to live keys once you're fully confident in the system's behavior.

Twelve Data API Key

Recommended
TWELVE_DATA_API_KEY

An additional source of financial data — prices, technicals, and fundamentals. Having it improves data quality and coverage. If left empty, Investi falls back to other providers (Alpaca, Yahoo Finance).

How to get it
  1. Sign up (free tier available) at twelvedata.com
  2. Go to your dashboard and copy your API key
  3. Paste it into your .env file

OpenAI API Key

Optional
OPENAI_API_KEY

Only used for tracing and logging agent reasoning in the OpenAI Traces Dashboard. This lets you see exactly how each agent reasoned through a request. Investi works perfectly fine without it.

How to get it: Sign up at platform.openai.com and generate an API key.
Configuration · config.yaml

Agent Models

Each agent can run a different LLM. The defaults use a mix of Claude models balanced for cost and quality.

agents.portfolio_manager.model_name The "brain" — orchestrates the other agents. Uses a stronger model by default.
agents.trader.model_name Handles order placement, sizing, and execution.
agents.analyst.model_name Researches stocks, pulls fundamentals, screens by criteria.
agents.technical_analyst.model_name Reads charts, runs indicators, spots patterns.
agents.*.reasoning_effort How much "thinking time" each agent gets: minimal, low, medium, high, or xhigh. Higher = smarter but slower and more expensive.

You can browse available models at openrouter.ai/models. Use the provider/model-name format.

Credits

credits.min_credits_warning Dollar threshold for low-credit Telegram alerts. Default: 5
credits.credit_check_interval_hours How often (in hours) to check your OpenRouter balance. Default: 6

Heartbeat

The heartbeat is a background process that periodically checks market conditions and can proactively alert you or trigger analysis.

heartbeat.heartbeat_model LLM used for heartbeat reasoning. A lightweight model works fine here.
heartbeat.market_open_interval_seconds Check interval during market hours. Default: 1200 (20 min)
heartbeat.market_closed_interval_seconds Check interval outside market hours. Default: 7200 (2 h)

Session

session.ttl_seconds How long session memory lasts before expiring. Default: 86400 (24 hours). Conversation context resets after this period of inactivity.
Operations

Restarting

Investi reads .env and config.yaml once at startup. If you edit either file while the bot is running, the changes won't take effect until you restart.

If the installer set you up with Docker:

Terminal
cd investi
docker compose restart

If you chose to run locally instead:

Terminal
# Stop with Ctrl+C, then:
python main.py
Terminal
docker compose restart

If you're using the auto-update profile, Docker will also restart on new commits from GitHub:

Terminal
docker compose --profile auto-update up -d
Terminal
# Stop the running process with Ctrl+C, then:
python main.py

Stopping

To stop Investi and shut down all containers:

Terminal
cd investi
docker compose down

This gracefully stops the bot and removes the containers. Your data, logs, and configuration are preserved — just run docker compose up -d to start again.

Terminal
docker compose down

This gracefully stops the bot and removes the containers. Your data, logs, and configuration are preserved — just run docker compose up -d to start again.

Press Ctrl+C in the terminal where Investi is running. The bot will shut down gracefully.

Tip: docker compose down stops and removes containers but keeps your volumes (database, logs) intact. To also remove volumes, add -v — but this will delete your local database.

Startup Validation

When Investi starts, it automatically validates all your credentials before launching the bot:

  • Telegram bot token — verifies it's a valid token by calling the Telegram API
  • Telegram user ID — checks that the bot can reach you
  • Alpaca API keys — tests both paper and live endpoints
  • OpenRouter API key — validates the key against the OpenRouter API
  • Twelve Data API key — validates if provided (warning only, won't block startup)

If any required credential is invalid, Investi will exit immediately — it won't start the bot with broken keys. If your Telegram credentials work, you'll also get a notification on Telegram about any remaining issues.

Container exited right after starting? This almost always means a credential failed validation. Check the container logs for the specific error:
Terminal
docker compose logs investi

Check the terminal output or logs/bot-errors.log for the specific error.

Fix the issue in your .env or config.yaml, then restart.

Tip: Check logs/bot-errors.log for detailed error messages if something isn't working.

Logs

Investi writes two log files, both in the logs/ directory:

logs/bot-output.log General activity — startup, requests, completions. Rotates daily, keeps 7 days.
logs/bot-errors.log Errors only — API failures, invalid credentials, exceptions. Rotates daily, keeps 7 days.

If running via Docker, you can also stream live logs:

Terminal
docker compose logs -f

Stream live container logs with:

Terminal
docker compose logs -f

When running locally, logs are printed to the terminal and also written to the files above. You can tail them with:

Terminal
tail -f logs/bot-output.log

Telegram Commands

Investi's Telegram bot accepts the following commands in addition to plain-text messages:

/status Returns a live snapshot of your portfolio — account value, available cash, open positions with unrealized P/L, and your remaining OpenRouter credit balance.
← Back to home GitHub