spindlex 0.6.4

A modern, high-performance SSHv2 and SFTP client/server library

SpindleX

Modern SSH library for secure automation, recursive SFTP, and high-performance deployments.

Quick Start • Docs • Security • Contributing

---

SpindleX is a modern SSH protocol implementation engineered for speed, security, and a seamless developer experience. It provides a clean, performant alternative to legacy Python SSH libraries.

[!WARNING] Beta software. The 0.6.x line is stabilising the core protocol, transport, and SFTP layers. Review meta/SECURITY.md before deploying in production-facing workflows, pin exact versions, and audit your host key policy.

✨ Key Features

• 🚀 High Performance: Optimized protocol implementation with internal buffering designed for high-throughput SFTP and command execution.
• 📦 Modern Architecture: Clean, modular codebase built from the ground up for maintainability. Leverages the industry-standard cryptography library for robust, hardware-accelerated security.
• 🔄 Native Async: First-class support for asyncio with AsyncSSHClient and AsyncSFTPClient.
• 🛡️ Secure by Default: Modern algorithms like Ed25519, ECDSA, and AES-256-CTR with HMAC-SHA2 are prioritized. Legacy SHA-1 and weak ciphers are disabled in the default configuration.
• 🏷️ Fully Typed: Comprehensive type hints across the codebase for robust IDE integration and static analysis.

---

🚀 Quick Start

Installation

# Using pip
pip install spindlex

# Using uv (recommended)
uv pip install spindlex

Basic Usage

Synchronous Example

from spindlex import SSHClient

# The default policy is RejectPolicy, which requires the server's
# host key to be present in the client's known-hosts store.
with SSHClient() as client:
    client.get_host_keys().load()  # loads ~/.ssh/known_hosts by default
    client.connect('example.com', username='admin')

    stdin, stdout, stderr = client.exec_command('uptime')
    print(f"Status: {stdout.read().decode().strip()}")

[!CAUTION] AutoAddPolicy is available for throw-away test environments only — it silently trusts first-seen server keys and therefore offers no MITM protection. In production, use the default RejectPolicy with a managed known_hosts file.

Asynchronous Example

import asyncio
from spindlex import AsyncSSHClient

async def run():
    async with AsyncSSHClient() as client:
        await client.connect('example.com', username='admin')
        stdin, stdout, stderr = await client.exec_command('uptime')
        print(await stdout.read())

asyncio.run(run())

---

📺 Demos

[!TIP] View Live Execution Results: See the Verified Demo Outputs from the latest run.

See SpindleX in action across various high-performance scenarios:

🏗️ Full Cycle Automation

complex_setup_demo.py: Watch SpindleX generate Ed25519 keys, deploy them via SFTP, and execute privileged sudo commands—all in under 6 seconds.

---

🚀 Performance & Multi-Tasking

Command Execution	SFTP Operations
Blazing fast command processing	High-throughput recursive transfers

Async Concurrency	Benchmark vs Paramiko
Native asyncio integration	Up to ~2.6x faster (results vary by environment)

---

⚡ Performance

SpindleX is designed for high-throughput, low-latency environments. It utilizes internal read buffering (32KB chunks) and optimized packet handling to reduce system call overhead and improve protocol efficiency. Actual performance gains are environment-dependent.

📊 Benchmark vs Paramiko

In testing, SpindleX has been observed to outperform legacy libraries in connection establishment and bulk SFTP transfers. Results are environment-dependent — run the included benchmark to verify on your setup.

Library	Connection Time (Avg)*	Overhead
SpindleX	0.32s	Low
Paramiko	0.85s	High

*Results from a sample run. Your numbers will vary based on network, server, and hardware.

[!TIP] Run the included benchmark script to compare performance in your environment:

python demo/benchmark.py

---

🛡️ Security

• Hardened Defaults: Modern cryptographic primitives are used by default. Legacy algorithms are disabled unless explicitly configured.
• Mandatory Verification: Host key verification is enforced unless explicitly overridden.
• Privacy Aware: Built-in log sanitizers ensure credentials never reach telemetry.
• Vulnerability Reporting: See meta/SECURITY.md.

---

🤝 Contributing

Contributions are welcome! See meta/CONTRIBUTING.md to get started.

---

📄 License

SpindleX is released under the MIT License. See LICENSE for the full text.

---

_{Developed with precision by Di3Z1E.
© 2026 SpindleX Project}