Installation & Quickstart

Creating an Astris application takes less than 30 seconds.

Prerequisites

Before creating your first Astris project, ensure you have the following installed:

1. Python 3.11+ (Python 3.14 recommended, or install via uv python install 3.14)
2. uv (recommended for ultra-fast Python package management):

   # Windows (PowerShell)
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # macOS & Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Node.js version ^22.18.0 or >=24.12.0 (Node 24 LTS recommended) & npm.

Creating a New Project

Method 1: Zero-Install with uvx (Recommended)

Run astris new directly without pre-installing anything globally:

uvx --from astris-python astris new my_app

Method 2: Global CLI Installation

Install the astris CLI globally on your system:

# Install with uv tool
uv tool install astris-python

# Or with pipx
pipx install astris-python

Once installed globally, you can create new projects anytime:

astris new my_app

Full-Stack Auth Included

Every Astris project comes pre-configured with a full-stack authentication system (Login, Registration, Argon2id Password Hashing, Session Guards, and Dashboard UI). If you want to scaffold a minimal project without authentication, pass --no-auth:

uvx --from astris-python astris new my_app --no-auth

Running the Application

Navigate into your newly created project directory:

cd my_app

1. Install Frontend Dependencies

npm install

2. Start Full-Stack Development Server

uv run orbit serve

Astris launches your FastAPI backend on http://localhost:8000 and concurrently starts the Vite Hot Module Replacement (HMR) server for Vue 3 and Tailwind CSS.

Open http://localhost:8000 in your browser!

Interactive API Documentation

Every Astris application automatically provides interactive OpenAPI documentation out of the box:

• Swagger UI: http://localhost:8000/docs
• ReDoc Schema: http://localhost:8000/redoc

Next Steps

• Explore your project layout: Directory Structure.
• Learn about settings & .env: Configuration.