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

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:

# 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

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, 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, 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.

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.

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 and the UI component 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:

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 and registered in 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 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.
• AI operations flow through 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}