Terraphim is a privacy-first AI assistant that works for you under your complete control and is fully deterministic.
You can use it as a local search engine, configured to search for different types of content on StackOverflow, GitHub, and the local filesystem using a predefined folder, which includes your Markdown files.
Terraphim operates on local infrastructure and works exclusively for the owner's benefit.
https://github.com/terraphim/terraphim-ai/assets/175809/59c74652-bab4-45b2-99aa-1c0c9b90196b
There are growing concerns about the privacy of data and the sharing of individuals' data across an ever-growing list of services, some of which have questionable data ethics policies. 1,2,3,4
Individuals struggle to find relevant information in different knowledge repositories:
Terraphim aims to bridge this gap by providing a privacy-first AI assistant that operates locally on the user's hardware, enabling seamless access to various knowledge repositories without compromising privacy. With Terraphim, users can efficiently search personal, team-focused, and public knowledge sources, ensuring that their data remains under their control at all times.
Clone the repository:
git clone https://github.com/terraphim/terraphim-ai.git
cd terraphim-ai
Set up development environment:
# Install Git hooks for code quality (optional but recommended)
./scripts/install-hooks.sh
Start the backend server:
cargo run
This starts an API endpoint for indexing and querying documents.
Run the frontend (choose one):
Web Frontend:
cd desktop
yarn install
yarn run dev
Desktop App (Tauri):
cd desktop
yarn install
yarn run tauri dev
Terminal Interface (TUI):
cargo run --bin terraphim-tui
(See the desktop README and development setup guide for more details.)
When configuring or working on Terraphim, you will encounter the following terms and concepts:
The term is originally taken from the Relict series of science fiction novels by Vasiliy Golovachev. Terraphim is an artificial intelligence living inside a spacesuit (part of an exocortex), or inside your house or vehicle, and it is designed to help you with your tasks. You can carry it around with you. Similar entities now common in science fiction, for example Destiny 2 has entity called Ghost.
Or in Star Wars Jedi Survivor there is an AI assistant BD-1.
The compactness and mobility of such AI assistant drives the [[Design Decisions]] of Terraphim.
Terraphim is a trademark registered in the UK, US and internationally (WIPO). All other trademarks mentioned above are the property of their respective owners.
Terraphim supports multiple storage backends for different deployment scenarios:
The system uses local storage backends by default, requiring no additional configuration:
For production deployments, you can optionally enable cloud storage:
To use AWS S3 storage, set the following environment variables:
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export TERRAPHIM_PROFILE_S3_REGION="us-east-1"
export TERRAPHIM_PROFILE_S3_ENDPOINT="https://s3.amazonaws.com/"
Note: AWS credentials are completely optional. The system will automatically fall back to local storage if AWS credentials are not available, ensuring local development works without any cloud dependencies.
TERRAPHIM_SETTINGS_PATH
: Override the settings file pathTERRAPHIM_DATA_PATH
: Set the data directory locationLOG_LEVEL
: Set logging verbosity (debug, info, warn, error)brew install terraphim/terraphim-ai/terraphim-ai
This installs the server, TUI, and desktop app (macOS only).
# Download from GitHub releases
sudo dpkg -i terraphim-server_*.deb
sudo dpkg -i terraphim-tui_*.deb
sudo dpkg -i terraphim-ai-desktop_*.deb
docker run ghcr.io/terraphim/terraphim-server:latest
Download pre-built binaries from GitHub Releases.
For development, see our comprehensive Development Setup Guide which covers:
We welcome contributions! Here's how to get started:
Read our guides:
Set up your environment:
git clone https://github.com/terraphim/terraphim-ai.git
cd terraphim-ai
./scripts/install-hooks.sh # Sets up code quality tools
Code quality standards:
cargo fmt
Make your changes:
git checkout -b feat/your-feature
git commit -m "feat: add amazing feature"
Important: Some dependencies are pinned to specific versions to ensure compatibility:
wiremock = "0.6.4"
- Version 0.6.5 uses unstable Rust features requiring nightly compilerschemars = "0.8.22"
- Version 1.0+ introduces breaking API changesthiserror = "1.0.x"
- Version 2.0+ requires code migration for breaking changesThese constraints are enforced in .github/dependabot.yml
to prevent automatic updates that would break CI. Future upgrades require manual code migration work.
This project is licensed under the Apache license.