# How to Get Started with Terax AI: Installation, Setup, and First Steps

> Get started with Terax AI by downloading the latest binary or building from source. Configure your AI provider in Settings to begin your journey.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: getting-started
- Published: 2026-07-06

---

**To get started with Terax AI, download the latest binary from the Releases page or build from source using `pnpm install` followed by `pnpm tauri dev`, then configure your AI provider in Settings.**

Terax AI is a lightweight, terminal-first development workspace built on **Tauri 2**, **Rust**, and **React 19**. This guide walks you through installing the application, understanding its two-process architecture, and configuring the AI side-panel to get started with Terax AI development.

## Installation Options

### Download Pre-built Binaries

The fastest way to get started with Terax AI is to download the latest installer from the **Releases** page on the `crynta/terax-ai` repository. Run the installer for your platform to receive a native binary with the PTY backend, WebGL-accelerated terminal, integrated code editor, and AI side-panel.

### Build from Source

For developers who want to customize the application or contribute to the codebase, build from source using these commands:

```bash

# Install dependencies

pnpm install

# Run the app in dev mode with auto-reload

pnpm tauri dev

# Or build a production bundle

pnpm tauri build

```

The `pnpm tauri dev` command runs the Rust backend (`cargo run`) while hot-reloading the React frontend, enabling rapid iteration on the `src/` directory.

## Development Prerequisites

Before building from source, ensure your environment meets these requirements:

- **Rust** (stable) via https://rustup.rs
- **Node.js** 20+ and **pnpm**
- Platform-specific Tauri prerequisites listed in the [official Tauri documentation](https://tauri.app/start/prerequisites/)

The Rust backend handles all OS access including PTY management, filesystem operations, Git operations, and network requests, while the webview frontend in `src/` manages UI rendering and user interaction.

## Launching the Application

When you launch Terax AI—either via the binary or `pnpm tauri dev`—the application window starts hidden and only appears after the React tree mounts. This logic is implemented in [`src/main.tsx`](https://github.com/crynta/terax-ai/blob/main/src/main.tsx), which also seeds the launch directory for the initial working directory of your first terminal tab.

The entry point determines the initial working directory through [`src/lib/launchDir.ts`](https://github.com/crynta/terax-ai/blob/main/src/lib/launchDir.ts), ensuring your terminal sessions open in the correct project context.

## Configuring the AI Provider

To enable AI assistance, open **Settings → AI** and select your preferred provider (OpenAI, Anthropic, or local models). Paste your API key, which is stored exclusively in the OS keychain via the `secrets_set` command defined in [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs).

The security model ensures that API keys are never written to disk in plain text. Instead, the backend validates and retrieves credentials using the OS keychain, accessible only through the verified IPC boundary.

## Using the AI Side-Panel

Once configured, access the AI side-panel by clicking the AI tab in the bottom dock. The AI subsystem uses the **Vercel AI SDK v6** with `streamText` and tool definitions managed in [`src/modules/ai/lib/agent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/agent.ts).

### Reading and Generating Code

Try typing a prompt like "Write a Python function that returns the Fibonacci sequence." The AI generates responses using the `runAgentStream` function, which builds a language model based on your selected provider through `buildLanguageModel`.

### Handling Edit Diffs

When the AI proposes file modifications, they appear in an `ai-diff` tab before any changes are written to disk. This approval flow is implemented in [`src/modules/ai/tools/edit.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/edit.ts) and the UI component [`src/modules/ai/components/AiToolApproval.tsx`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/components/AiToolApproval.tsx). Mutating tools like `write_file` and `edit` set `needsApproval:true`, pausing the stream until you explicitly accept the hunk.

Read-only tools such as `read_file`, `grep`, and `glob` execute automatically after passing the security deny-list validation.

## Understanding the Two-Process Architecture

Terax AI follows a strict two-process model where the **Rust backend** (`src-tauri/src/`) owns all privileged operations and the **Webview frontend** (`src/`) handles rendering. All communication flows through Tauri’s `invoke()` API.

For example, to read a file, the frontend calls:

```typescript
import { invoke } from "@tauri-apps/api/core";

async function readFile(path: string): Promise<string> {
  const content = await invoke<string>("fs_read_file", { path });
  return content;
}

```

The `fs_read_file` command is implemented in [`src-tauri/src/modules/fs.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/fs.rs) and registered in [`src-tauri/src/lib.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/lib.rs) at line 191. This boundary ensures the webview never accesses the filesystem or spawns processes directly, with all paths validated against workspace authorization registries.

## Summary

- **Download binaries** from the Releases page for immediate installation, or use `pnpm install` and `pnpm tauri dev` to build from source.
- **Prerequisites** include Rust (stable), Node.js 20+, pnpm, and platform-specific Tauri dependencies.
- **Launch** triggers window visibility logic in [`src/main.tsx`](https://github.com/crynta/terax-ai/blob/main/src/main.tsx) after the React tree mounts.
- **Configure AI** through Settings → AI, with API keys stored securely in the OS keychain via [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs).
- **AI operations** flow through [`src/modules/ai/lib/agent.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/agent.ts), with mutating tools requiring explicit approval before executing.
- **Security** relies on the two-process model where all privileged commands are registered in [`src-tauri/src/lib.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/lib.rs) and invoked through typed IPC calls.

## Frequently Asked Questions

### How do I build Terax AI from source?

Clone the repository and run `pnpm install` to install dependencies, then `pnpm tauri dev` to start the development server. This compiles the Rust backend in `src-tauri/` and serves the React frontend with hot-reload enabled. For production builds, use `pnpm tauri build` to generate platform-specific installers.

### Where are my API keys stored?

API keys are stored exclusively in your operating system's keychain using the `secrets_set` command implemented in [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs). They are never written to disk or accessible to the frontend webview, ensuring credentials remain secure even if the application process is compromised.

### Why does the AI require approval for some actions but not others?

The AI subsystem distinguishes between read-only tools (`read_file`, `grep`, `glob`) and mutating tools (`write_file`, `edit`, `bash_run`). Mutating tools set `needsApproval:true` in their configuration within `src/modules/ai/tools/`, causing the stream to pause until you accept the diff in the `ai-diff` tab. This prevents accidental file modifications while allowing automatic context gathering.

### Can I use local models instead of cloud providers?

Yes. The provider configuration in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts) supports both cloud and local providers. To add a local model, extend the `PROVIDERS` array, update the model registry, and add a branch in `buildLanguageModel` to handle your local endpoint. The AI subsystem uses the Vercel AI SDK v6, which supports various local hosting options compatible with the `streamText` interface.