# How to Set Up Dexter Financial Research Agent: Complete Installation and Configuration Guide

> Learn to set up Dexter financial research agent easily. Follow our guide for installation, configuration with API keys, and launching Dexter for autonomous financial insights.

- Repository: [Virat Singh/dexter](https://github.com/virattt/dexter)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Install Bun v1.0+, clone the virattt/dexter repository, run `bun install`, configure your `.env` file with OpenAI and Financial Datasets API keys, and launch with `bun start` to begin autonomous financial research.**

Dexter is an open-source, CLI-based autonomous agent designed to answer complex finance questions through iterative tool execution and LLM reasoning. This guide walks you through setting up the Dexter financial research agent from the virattt/dexter repository, covering installation, configuration, and your first query.

## Prerequisites for Setting Up Dexter

Before installing Dexter, ensure your environment meets the following requirements.

### Install Bun Runtime

Dexter requires **Bun v1.0 or higher** as its JavaScript runtime and package manager. Install it via the official installer:

```bash
curl -fsSL https://bun.com/install | bash

```

For macOS, Linux, or Windows-specific instructions, refer to the repository's README.

### Obtain Required API Keys

You need API keys for the following services:

- **OpenAI API key** – Required for LLM inference
- **Financial Datasets API key** – Required for stock data and SEC filings
- **Exa or Tavily API key** – Optional, enables the `web_search` tool for broader research

## Clone and Install the Repository

Once prerequisites are satisfied, download the source code and install dependencies:

```bash
git clone https://github.com/virattt/dexter.git
cd dexter
bun install

```

The `bun install` command resolves all TypeScript dependencies and creates the `node_modules` directory.

## Configure Environment Variables

Dexter uses environment variables to manage API keys and feature flags. Copy the example configuration file and edit it with your credentials:

```bash
cp env.example .env

```

Edit `.env` and add your keys:

```bash
OPENAI_API_KEY=sk-...
FINANCIAL_DATASETS_API_KEY=...
EXASEARCH_API_KEY=...  # Optional

```

The CLI reads these variables at startup via [`src/utils/env.ts`](https://github.com/virattt/dexter/blob/main/src/utils/env.ts). Missing required keys trigger clear runtime errors in the LLM factory ([`src/model/llm.ts`](https://github.com/virattt/dexter/blob/main/src/model/llm.ts) lines 53-58).

## Launch Dexter and Run Your First Query

Start the interactive CLI interface:

```bash
bun start

```

This command launches the Ink-based terminal UI defined in [`src/cli.tsx`](https://github.com/virattt/dexter/blob/main/src/cli.tsx). You’ll see a welcome screen, model selector (if no model is cached), and an input prompt ready for financial queries.

### Understanding the Agent Loop

The core intelligence resides in [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts), which implements an iterative **agent-loop** pattern:

1. **System prompt construction** – Combines the selected LLM provider configuration with registered tool descriptions from [`src/tools/registry.ts`](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts).
2. **Iteration cycle** – The agent calls the LLM, parses tool invocations, and executes them via `AgentToolExecutor`.
3. **Scratchpad management** – Results accumulate in a scratchpad. When context exceeds token limits, `manageContextThreshold` discards the oldest tool results to maintain performance.
4. **Final synthesis** – Once no more tool calls are required, the agent generates a definitive answer using the complete scratchpad context.

### Example Financial Research Query

Try this query to test the setup:

```

> What was Apple's revenue growth YoY for the last 5 years?

```

Dexter will:

- **Plan** – Determine it needs `financial_search` and `financial_metrics` tools
- **Execute** – Call the Financial Datasets API via [`src/tools/finance/financial-search.ts`](https://github.com/virattt/dexter/blob/main/src/tools/finance/financial-search.ts) and [`financial-metrics.ts`](https://github.com/virattt/dexter/blob/main/financial-metrics.ts)
- **Iterate** – Fetch additional data if initial results are incomplete
- **Finalize** – Return a concise analysis of Apple's 5-year revenue trajectory

Intermediate tool calls are logged to `.dexter/scratchpad/` for debugging purposes.

### Changing Models and Exiting

- **Switch models** – Type `/model` at any prompt to enter the provider-selection flow (defined in [`src/cli.tsx`](https://github.com/virattt/dexter/blob/main/src/cli.tsx) lines 90-98 and [`src/hooks/useModelSelection.ts`](https://github.com/virattt/dexter/blob/main/src/hooks/useModelSelection.ts))
- **Exit** – Type `exit` or `quit` to close the session

## Optional: Connect Dexter via WhatsApp

To interact with Dexter from your mobile device, enable the WhatsApp gateway:

```bash
bun run gateway:login   # Scan the QR code with your phone

bun run gateway         # Start the listener

```

Messages you send to yourself on WhatsApp will receive responses prefixed with `[Dexter]`. Detailed configuration steps are documented in [`src/gateway/channels/whatsapp/README.md`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/README.md).

## Programmatic Usage and Custom Tools

### Using the Agent API Directly

You can integrate Dexter into existing Node.js applications without the CLI:

```typescript
import { Agent } from './src/agent/agent.js';

async function main() {
  const agent = Agent.create({ model: 'gpt-4o' });
  const query = "What is Nvidia's 2023 free cash flow?";

  for await (const event of agent.run(query)) {
    if (event.type === 'thinking') console.log('🧠', event.message);
    if (event.type === 'tool_result') console.log('🔧', event.toolName, event.result);
    if (event.type === 'answer_start') console.log('📢 Answer:');
    if (event.type === 'done') console.log(event.answer);
  }
}

main();

```

This uses the public `Agent` class (see [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts) lines 21-30).

### Registering Custom Tools

Extend Dexter's capabilities by adding custom data sources:

```typescript
// src/tools/custom/my-tool.ts
import { StructuredTool } from '@langchain/core/tools';

export const myTool = new StructuredTool({
  name: 'my_tool',
  description: 'Returns a static message for demo purposes.',
  async func(_: { }) {
    return 'Hello from my custom tool!';
  },
});

// Register it in src/tools/registry.ts
tools.push({
  name: 'my_tool',
  tool: myTool,
  description: 'Custom demo tool.',
});

```

After rebuilding (`bun install`), the LLM can invoke `my_tool` just like the built-in financial data sources.

## Summary

- **Dexter** is a CLI-based autonomous agent that answers finance questions through iterative tool execution and LLM reasoning.
- **Installation** requires Bun v1.0+, API keys for OpenAI and Financial Datasets, and a simple `bun install`.
- **Configuration** happens via `.env` file, validated at runtime in [`src/model/llm.ts`](https://github.com/virattt/dexter/blob/main/src/model/llm.ts) and [`src/utils/env.ts`](https://github.com/virattt/dexter/blob/main/src/utils/env.ts).
- **Architecture** follows an agent-loop pattern in [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts) with scratchpad management and automatic context threshold handling.
- **Extensibility** allows custom tools via [`src/tools/registry.ts`](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts) and programmatic usage through the `Agent` class API.

## Frequently Asked Questions

### What API keys are required to set up Dexter financial research agent?

You need an **OpenAI API key** and a **Financial Datasets API key** to run Dexter. These are mandatory for LLM inference and financial data access respectively. Optionally, you can add an **Exa** or **Tavily API key** to enable the web search tool for broader research capabilities.

### Can I use Dexter without the interactive CLI interface?

Yes. You can import the **Agent** class directly from [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts) and invoke it programmatically in Node.js applications. The `Agent.create()` method accepts a model configuration, and `agent.run()` returns an async iterator yielding thinking events, tool results, and final answers.

### How does Dexter handle long-running financial research tasks?

Dexter implements **context management** in [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts) through the `manageContextThreshold` function. When the scratchpad accumulates tool results that approach the LLM's token limit, the system automatically discards the oldest entries while preserving the most recent context, allowing the agent to continue iterative research without hitting context windows.

### Is it possible to add custom financial data sources to Dexter?

Yes. You can extend Dexter by creating a new **StructuredTool** class and registering it in [`src/tools/registry.ts`](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts). The registry dynamically discovers available tools based on environment variables and skill files, making custom integrations immediately available to the LLM for autonomous invocation during research tasks.