Quick Start • Documentation • Security • Contributing

---

⚡ Overview

SpindleX is a modern SSH and SFTP implementation for Python 3.9 - 3.14 - client and server, sync and async. It is designed for high-performance automation and secure file transfers, providing a clean alternative to legacy SSH libraries.

Note

Stable 1.x. The public API is frozen under semantic versioning since 1.0.0. The 1.0.x releases have hardened interoperability with OpenSSH and Dropbear, the SpindleX SSH and SFTP servers, and the sync and async transports - see the changelog. Upgrading from 0.x? Read the migration guide. See also SECURITY.md and the compatibility & API stability policy.

🔥 Key Features

• 🚀 High Performance: Pipelined SFTP transfers with read/write sizes negotiated via limits@openssh.com (up to 255 KB), and the fastest handshake and command execution in our benchmarks.
• 🔒 Modern Cryptography: ChaCha20-Poly1305 (preferred) and AES-CTR, Curve25519/ECDH/DH-group14 key exchange, Ed25519, ECDSA and RSA (SHA-2) keys, Terrapin-defense strict KEX.
• 🔄 Native Async: First-class asyncio support via AsyncSSHClient and AsyncSFTPClient.
• 🖥️ SSH & SFTP Server: Build servers with SSHServer, SSHServerManager and SFTPServer - they work with the OpenSSH ssh and sftp clients.
• 🔑 Authentication: Password, public key, keyboard-interactive, GSSAPI/Kerberos and multi-factor (partial success).
• 🔗 Tunneling: Local and remote port forwarding, and ProxyJump (bastion hosts) via direct-tcpip channels.
• 📂 Recursive SFTP: get_recursive() / put_recursive() for whole directory trees.
• 🏷️ Fully Typed: Comprehensive type hints for IDE integration and static analysis.

---

💎 Why SpindleX?

• 💼 Business Friendly: MIT Licensed. Permissive use for commercial and proprietary projects.
• 📖 Maintainable Code: Modular architecture designed for clarity and easier security auditing.
• 🛠️ Modern API: Clean, intuitive interface with consistent error handling and minimal dependencies.
• 🧊 Focused Scope: No support for insecure legacy protocols, resulting in a leaner and more secure codebase.

---

🛠️ Tech Stack

Core Logic

Protocol

Concurrency

---

🚀 Quick Start

Installation

# Using pip
pip install spindlex

# Using uv
uv pip install spindlex

💻 Usage Preview

Synchronous Example

from spindlex import SSHClient

with SSHClient() as client:
    client.get_host_keys().load()
    client.connect('example.com', username='admin')

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

Asynchronous Example

import asyncio
from spindlex import AsyncSSHClient

async def main():
    async with AsyncSSHClient() as client:
        client.get_host_keys().load()
        await client.connect('example.com', username='admin')
        stdin, stdout, stderr = await client.exec_command('df -h')
        print(await stdout.read())

asyncio.run(main())

SFTP Example

from spindlex import SSHClient

with SSHClient() as client:
    client.get_host_keys().load()
    client.connect('example.com', username='admin')

    with client.open_sftp() as sftp:
        sftp.put('report.csv', '/srv/data/report.csv')
        sftp.get_recursive('/var/log/app', './app-logs')
        print(sftp.listdir('/srv/data'))

More examples - servers, port forwarding, ProxyJump, multi-factor login - are in the documentation and the cookbook.

---

📊 Performance Benchmarks

Median of 5 runs against a live OpenSSH 9.2 server on a local network (SpindleX 1.0.4, AsyncSSH 2.24, Paramiko 5.0, Python 3.12). Lower is better.

Operation	SpindleX	AsyncSSH	Paramiko
Handshake (connect + auth + close)	41 ms	50 ms	84 ms
Command (echo hello, warm connection)	5.5 ms	5.7 ms	49 ms
Command with 1.4 MB output	20 ms	21 ms	67 ms
SFTP upload (1 MiB)	14 ms	20 ms	45 ms
SFTP download (1 MiB)	16 ms	14 ms	360 ms

Network latency dominates in practice, so measure in your own environment. See the comparison page for methodology and feature differences.

Tip

Run the benchmark suite on your own hardware:

python scripts/benchmark_compare.py     # SpindleX vs AsyncSSH vs Paramiko
python scripts/benchmark_ciphers.py     # per cipher / key exchange / host key
python scripts/benchmark_production.py  # protocol correctness + stability

---

🛡️ Security

• Verification Enforced: Host key verification is mandatory by default.
• Log Sanitization: Credentials and sensitive data are automatically filtered from logs.
• AEAD Preferred: chacha20-poly1305@openssh.com is the default cipher - authentication is integral, no separate MAC.
• Terrapin Defense: Strict-KEX (kex-strict-c-v00@openssh.com) enabled, sequence numbers reset after NEWKEYS.
• Modern Defaults: Ed25519, ECDSA, RSA with SHA-2 signatures, ChaCha20-Poly1305 and AES-CTR. CBC mode and SHA-1 (key exchange, MACs, ssh-rsa signatures) are off by default.
• known_hosts Aware: Hashed entries, non-standard ports and @revoked markers are honoured; private keys are written owner-only (0600).
• Hardened Server: Authentication only after key exchange, a login grace deadline, failed-attempt limits, and an SFTP server confined to its root.
• Full Policy: See SECURITY.md for vulnerability reporting and Security Guide for operational security guidance.

---

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the GitHub entry point and docs/contributing.md for the maintained guide.

Distributed under the MIT License. See LICENSE for more information.

---

SpindleX Project © 2026 Stratza Labs