nauyaca 0.11.0

Modern Gemini protocol server and client implementation using asyncio

Nauyaca - Gemini Protocol Server & Client

A modern, high-performance implementation of the Gemini protocol in Python. Nauyaca (pronounced "now-YAH-kah", meaning "serpent" in Nahuatl) uses asyncio's low-level Protocol/Transport pattern for efficient, non-blocking network I/O with both server and client capabilities.

Key Features

• High Performance - asyncio Protocol/Transport pattern for maximum efficiency
• Security First - Mandatory TLS 1.2+, TOFU certificate validation, rate limiting, and access control
• Production Ready - TOML configuration, middleware system, and systemd integration
• Developer Friendly - Full type hints, comprehensive tests, and modern tooling with uv

Read the full documentation

Quick Start

Installation

# As a CLI tool (recommended)
uv tool install nauyaca

# As a library
uv add nauyaca

# From source (for development)
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca && uv sync

Run a Server

# Serve content from a directory
nauyaca serve ./capsule

# With configuration file
nauyaca serve --config config.toml

# With hot-reload for development
nauyaca serve ./capsule --reload

Fetch Content

# Get a Gemini resource
nauyaca get gemini://geminiprotocol.net/

# With verbose output
nauyaca get gemini://geminiprotocol.net/ --verbose

Use as a Library

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(response.body)
        elif response.is_redirect():
            print(f"Redirect to: {response.redirect_url}")
        else:
            print(f"Error {response.status}: {response.meta}")

asyncio.run(main())

Advanced Features

Location-Based Routing

Nauyaca supports flexible routing with multiple handlers per server. Configure different URL paths to use different handlers (static files, proxy, etc.):

# Proxy API requests to backend server
[[locations]]
prefix = "/api/"
handler = "proxy"
upstream = "gemini://backend.example.com:1965"
strip_prefix = true  # /api/resource → /resource on backend
timeout = 30

# Serve static content for everything else
[[locations]]
prefix = "/"
handler = "static"
document_root = "./capsule"

Reverse Proxy

Use Nauyaca as a reverse proxy to aggregate multiple Gemini capsules:

# Forward blog requests to blog server
[[locations]]
prefix = "/blog/"
handler = "proxy"
upstream = "gemini://blog.example.com"
strip_prefix = true

# Forward wiki requests to wiki server
[[locations]]
prefix = "/wiki/"
handler = "proxy"
upstream = "gemini://wiki.example.com"
strip_prefix = true

# Serve homepage from local files
[[locations]]
prefix = "/"
handler = "static"
document_root = "./homepage"

See config.example.toml for more configuration examples.

Documentation

nauyaca.readthedocs.io

Section	Description
Installation	Setup and requirements
Quick Start	Get running in 5 minutes
Tutorials	Step-by-step guides
How-to Guides	Task-oriented recipes
Reference	CLI, configuration, API
Explanation	Architecture and concepts

Contributing

# Setup
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca && uv sync

# Test
uv run pytest

# Lint & Type Check
uv run ruff check src/ tests/
uv run mypy src/

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Resources

• Gemini Protocol - Official protocol website
• SECURITY.md - Security documentation and vulnerability reporting
• GitHub Issues - Bug reports
• GitHub Discussions - Questions and ideas

Acknowledgments

• Solderpunk for creating the Gemini protocol
• The Gemini community for feedback and inspiration

---

Status: Active development (pre-1.0). Core protocol and security features are stable.