Installation

Native installation guide for Asta on Linux, macOS, and Windows. No Docker required.

Requirements

Backend

Python 3.12 or 3.13(3.14 not supported yet)

Desktop App

Node.js 18+Rust toolchain

Optional

OllamaFor local AI and RAG

Python 3.14 is not yet supported due to pydantic and ChromaDB compatibility issues. Use Python 3.12 or 3.13.

Quick Install (Linux / macOS)

The fastest way to get started using the control script:

git clone https://github.com/helloworldxdwastaken/asta.git
cd asta
cp .env.example backend/.env
# Edit backend/.env with your API keys (optional for first run)

./asta.sh start

Open http://localhost:8010/docs for API documentation. The desktop app connects to http://localhost:8010.

Platform-Specific Installation

macOS
Linux
Windows

Prerequisites

Install Python 3.12 or 3.13 using Homebrew:

brew install [email protected]

Backend Setup

cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start Backend

uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

Or use the control script:

./asta.sh start

Desktop App

Install dependencies and run in development mode:

cd MACWinApp/asta-app
npm install
npx tauri dev

Build Release (DMG)

cd MACWinApp/asta-app
npx tauri build

The DMG will be created in src-tauri/target/release/bundle/dmg/.

Apple Notes Integration: When running the backend, launch it from Terminal (not as a background service). The first time you ask Asta to check notes, macOS will prompt for permission. Approve it so the backend process can access Notes.

Prerequisites

Install Python 3.12 or 3.13:

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12 python3.12-venv

# Fedora
sudo dnf install python3.12

# Arch
sudo pacman -S python

Backend Setup

cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start Backend

uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

Or use the control script:

./asta.sh start

Desktop App

Install Node.js and Rust:

# Node.js (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build and run:

cd MACWinApp/asta-app
npm install
npx tauri dev

Run ./asta.sh install to add the asta command to your PATH for system-wide access.

Prerequisites

Python 3.12 or 3.13 from python.org
Node.js 18+ from nodejs.org
Rust from rustup.rs

Environment Setup

copy .env.example backend\.env
# Edit backend\.env with your API keys

Backend Setup

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Start Backend

uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

Desktop App

cd MACWinApp\asta-app
npm install
npx tauri dev     # Development mode
npx tauri build   # Build MSI installer

The MSI installer will be created in src-tauri\target\release\bundle\msi\.

Open PowerShell as Administrator if you encounter permission issues during installation.

Environment Configuration

Copy .env.example to backend/.env and configure your settings:

cp .env.example backend/.env

Essential Variables

GROQ_API_KEY

string

Groq API key (recommended for speed)

GEMINI_API_KEY

string

Google Gemini API key

ANTHROPIC_API_KEY

string

Claude API key from Anthropic

OPENAI_API_KEY

string

OpenAI API key

OPENROUTER_API_KEY

string

OpenRouter API key (access to 300+ models)

OLLAMA_BASE_URL

string

default:"http://localhost:11434"

Ollama server URL for local AI

Security Settings

ASTA_ALLOWED_PATHS

string

Comma-separated directories for file access (e.g., /Users/you/Documents,/Users/you/Notes)

ASTA_EXEC_ALLOWED_BINS

string

Comma-separated list of executable binaries Asta can run (e.g., memo,things)

ASTA_EXEC_SECURITY

string

default:"allowlist"

Execution security mode:

allowlist - Only allowed binaries (default, recommended)
full - Allow any command (dangerous)
deny - Disable exec completely

ASTA_JWT_SECRET

string

JWT signing secret (auto-generated on first login if not set)

Optional Integrations

TELEGRAM_BOT_TOKEN

string

Bot token from @BotFather

SPOTIFY_CLIENT_ID

string

Spotify app client ID from developer dashboard

SPOTIFY_CLIENT_SECRET

string

Spotify app client secret

HUGGINGFACE_API_KEY

string

Hugging Face token for FLUX.1-dev image generation fallback

Multi-User Authentication

On first run with no users in the database, Asta operates in single-user mode (open access, no login required).

Enable Multi-User Mode

Create the first admin user via the API (while in single-user mode):

curl -X POST http://localhost:8010/api/auth/users \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password", "role": "admin"}'

After creating the first user:

The desktop app will show a login screen
Sign in with the admin credentials
Admin can create additional users from Settings → Users
Users can self-register via the login page

User Roles

Admin

Full Access

All settings and configuration
User management
Skills, tools, and agents
Exec, files, and reminders

User

Limited Access

Chat with safe tools only
Web search, weather, math, GIFs, PDF, time
No settings or admin features
No exec, files, or reminders

JWT tokens are auto-generated on first login and stored in backend/.env as ASTA_JWT_SECRET. Tokens expire after 30 days.

Optional: Ollama Setup

Ollama provides local AI inference and embeddings for RAG (learning/knowledge).

Install Ollama

macOS
Linux
Windows

brew install ollama

curl -fsSL https://ollama.com/install.sh | sh

Setup for RAG

Use the provided setup script:

./scripts/setup_ollama_rag.sh

Or manually:

ollama pull nomic-embed-text
ollama serve

Set the base URL in backend/.env:

OLLAMA_BASE_URL=http://localhost:11434

If Ollama is unavailable, learning/RAG endpoints will be disabled until it’s running.

Control Script Reference

The asta.sh script provides commands for managing the backend:

./asta.sh start
# Creates venv, installs deps, starts backend

What `asta.sh start` Does

Python Detection

Searches for python3.12, python3.13, or compatible python3 (skips 3.14+)

Virtual Environment

Creates .venv in backend directory if it doesn’t exist

Dependencies

Installs all packages from requirements.txt

Port Management

Frees port 8010 if occupied by previous instances

Database Cleanup

Releases any stale SQLite locks

Tailscale Integration

Auto-starts Tailscale if installed for remote access

Background Process

Starts uvicorn as a background daemon

Health Check

Waits up to 25 seconds for API to respond

Pre-Built Releases

For end users who don’t want to build from source: Download the latest release from GitHub Releases:

macOS (Apple Silicon)

Asta_<version>_aarch64.dmg

macOS (Intel)

Asta_<version>_x64.dmg

Windows

Asta_<version>_x64-setup.msi

Install the DMG/MSI, then start the backend separately:

./asta.sh start

Troubleshooting

Address already in use (8010)

The port is occupied by a previous instance:

./asta.sh restart

Or manually kill the process:

lsof -ti:8010 | xargs kill -9

Cannot reach Asta API / API off

Backend is not running. Start it:

./asta.sh start

Or manually:

cd backend
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8010

No AI provider available

Add at least one API key to backend/.env:

GROQ_API_KEY=gsk_...
# or GEMINI_API_KEY, OPENAI_API_KEY, etc.

Then restart:

./asta.sh restart

Backend can't find .env

The backend reads backend/.env only (not root .env):

cp .env.example backend/.env

Wrong Python version

Install Python 3.12 or 3.13:

# macOS
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.12 python3.12-venv

Reminders not firing

Reminders are loaded on backend startup. Restart once:

./asta.sh restart

faster-whisper is not installed (audio notes)

Reinstall dependencies:

cd backend
source .venv/bin/activate
pip install -r requirements.txt

First run may download the Whisper model (~140 MB).

Tauri build fails

Ensure you have the Rust toolchain:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update Rust
rustup update

Then try building again:

cd MACWinApp/asta-app
npx tauri build

Next Steps

Configuration

Configure API keys, skills, and advanced settings

Desktop App

Learn about the Tauri-based desktop application

Telegram Bot

Set up Telegram integration for mobile access

Skills

Enable and configure built-in skills

Get Started

Core Concepts

Desktop App

Features

Configuration

Guides

Troubleshooting

​Requirements

Backend

Desktop App

Optional

​Quick Install (Linux / macOS)

​Platform-Specific Installation

​Prerequisites

​Backend Setup

​Start Backend

​Desktop App

​Build Release (DMG)

​Prerequisites

​Backend Setup

​Start Backend

​Desktop App

​Prerequisites

​Environment Setup

​Backend Setup

​Start Backend

​Desktop App

​Environment Configuration

​Essential Variables

​Security Settings

​Optional Integrations

​Multi-User Authentication

​Enable Multi-User Mode

​User Roles

Admin

User

​Optional: Ollama Setup

​Install Ollama

​Setup for RAG

​Control Script Reference

​What asta.sh start Does

​Pre-Built Releases

macOS (Apple Silicon)

macOS (Intel)

Windows

​Troubleshooting

​Next Steps

Configuration

Desktop App

Telegram Bot

Skills

Build docs developers (and LLMs) love

Requirements

Quick Install (Linux / macOS)

Platform-Specific Installation

Prerequisites

Backend Setup

Start Backend

Desktop App

Build Release (DMG)

Prerequisites

Backend Setup

Start Backend

Desktop App

Prerequisites

Environment Setup

Backend Setup

Start Backend

Desktop App

Environment Configuration

Essential Variables

Security Settings

Optional Integrations

Multi-User Authentication

Enable Multi-User Mode

User Roles

Optional: Ollama Setup

Install Ollama

Setup for RAG

Control Script Reference

What `asta.sh start` Does

Pre-Built Releases

Troubleshooting

Next Steps