Skip to content

Nauyaca

A modern, high-performance implementation of the Gemini protocol in Python

Nauyaca (pronounced "now-YAH-kah", meaning "serpent" in Nahuatl) brings modern Python async capabilities to the Gemini protocol, providing both server and client implementations with a focus on performance, security, and developer experience.

Why Nauyaca?

  • 🚀 High Performance

    Built on asyncio's low-level Protocol/Transport pattern for maximum efficiency and fine-grained control over network I/O

  • 🔒 Security First

    TOFU certificate validation, rate limiting, access control, and TLS 1.2+ enforcement built-in from the ground up

  • âš™ Production Ready

    Comprehensive TOML configuration, middleware system, systemd integration, and deployment-ready architecture

  • 🛠 Developer Friendly

    Full type hints, extensive test coverage, clean APIs, and powered by uv for fast dependency management

Quick Example

Get started in seconds with both client and server:

import asyncio
from nauyaca.client import GeminiClient

async def main():
    async with GeminiClient() as client:
        response = await client.get("gemini://geminiprotocol.net/")

        if response.is_success():
            print(f"Content-Type: {response.meta}")
            print(response.body)

asyncio.run(main())

import asyncio
from nauyaca.server import GeminiServer
from nauyaca.server.config import ServerConfig

async def main():
    config = ServerConfig(
        host="localhost",
        port=1965,
        document_root="./capsule"
    )

    server = GeminiServer(config)
    await server.start()

asyncio.run(main())

# Start a server
nauyaca serve ./capsule --host localhost --port 1965

# Fetch a resource
nauyaca get gemini://geminiprotocol.net/

# Manage trusted certificates
nauyaca tofu list
nauyaca tofu trust example.com

Installation

Choose the installation method that fits your use case:

Recommended: Install with uv

# As a standalone CLI tool
uv tool install nauyaca

# Or add to your project
uv add nauyaca

Alternative: Install with pip

pip install nauyaca

Requirements: Python 3.10 or higher

Key Features

Server Capabilities

  • Complete Protocol Support - TLS 1.2+, all status codes (1x-6x), client certificates
  • Security Hardened - Rate limiting, IP-based access control, path traversal protection
  • TOML Configuration - Flexible configuration with sensible defaults and CLI overrides
  • Middleware Architecture - Composable middleware for logging, rate limiting, and access control
  • Production Ready - Systemd integration, graceful shutdown, comprehensive error handling

Client Capabilities

  • TOFU Validation - Trust-On-First-Use certificate validation with SQLite-backed database
  • Async/Await API - Clean, modern Python API built on asyncio
  • Certificate Management - Import/export known hosts, revoke trust, manual certificate trusting
  • CLI Interface - Full-featured command-line client for browsing Geminispace
  • Redirect Handling - Automatic redirect following with loop detection

Documentation Sections

What is Gemini?

The Gemini protocol is a modern, privacy-focused alternative to HTTP and the web. It aims to be:

  • Simple - Easier to implement than HTTP, harder to extend (by design)
  • Privacy-focused - No cookies, no tracking, no JavaScript
  • Secure - TLS is mandatory, not optional
  • Lightweight - Text-focused content with minimal formatting
  • User-centric - Readers control how content is displayed

Think of it as a modern take on Gopher, sitting comfortably between the complexity of the web and the simplicity of plain text.

Project Status

Version 0.2.0 - Core Features Complete

Current phase: Security Hardening & Integration Testing

Feature Status
Core Protocol Implementation ✅ Complete
TLS 1.2+ Support ✅ Complete
Server Configuration (TOML) ✅ Complete
TOFU Certificate Validation ✅ Complete
Rate Limiting & DoS Protection ✅ Complete
IP-based Access Control ✅ Complete
Client Session Management ✅ Complete
Security Documentation ✅ Complete
Integration Testing 🚧 In Progress
CLI Interface 🚧 In Progress
Static File Serving 📆 Planned
Content Type Detection 📆 Planned

Community & Support

  • GitHub Repository

    Source code, issue tracker, and project development

  • Bug Reports

    Report bugs and request features

  • Discussions

    Ask questions and share ideas with the community

  • Security

    Responsible disclosure for security vulnerabilities

License

Nauyaca is released under the MIT License. See the LICENSE file for details.

Next Steps

Ready to get started? Here's what to do next:

  1. Install Nauyaca - Get up and running in minutes
  2. Quick Start Guide - Build your first Gemini server
  3. Explore Tutorials - Learn by building real projects
  4. Read the Security Guide - Understand TOFU, rate limiting, and best practices

Development Status

This project is in active development (pre-1.0). Core protocol and security features are stable, but the high-level API may change based on community feedback.