Holodeck

A simple HTTP file server with built-in reverse SSH tunneling

Features

• 🚀 Fast HTTP file server built with Hyper and Tokio
• 📤 File uploads via POST requests
• 📥 File downloads via GET requests
• 🌐 Reverse SSH tunneling for external access
• 🔒 Security - Path traversal protection
• 🔑 Smart SSH key management - Automatic key detection with priority
• 🎨 Clean output - Beautiful tunnel URL display

Quick Start

Installation

cargo install holo-deck

Local Server Only

# Start the server locally
holo-deck

# Or with cargo
cargo run

The server will automatically bind to a random available port (displayed on startup)

With External Tunnel

# Start with automatic external tunnel via localhost.run
SSH_SERVER=ssh.localhost.run holo-deck

The tunnel URL will be automatically displayed:

╔════════════════════════════════════════════════════════════════╗
║                    TUNNEL ACTIVE                               ║
╠════════════════════════════════════════════════════════════════╣
║  External URL: https://abc123.lhr.life                         ║
╚════════════════════════════════════════════════════════════════╝

Usage Examples

List Files

# Local (use the port displayed on startup, e.g., 59830)
curl http://localhost:59830/

# External (via tunnel)
curl https://abc123.lhr.life/

Upload a File

# Local (use your server's port)
curl -X POST --data-binary @myfile.txt http://localhost:59830/myfile.txt

# External
curl -X POST --data-binary @myfile.txt https://abc123.lhr.life/myfile.txt

Download a File

# Local (use your server's port)
curl http://localhost:59830/myfile.txt

# External
curl https://abc123.lhr.life/myfile.txt

Configuration

Environment Variables

Custom Configuration

# Use a specific SSH key
SSH_SERVER=ssh.localhost.run SSH_KEY_PATH=~/.ssh/id_ed25519 holo-deck

# Use password authentication instead of key
SSH_SERVER=ssh.localhost.run SSH_PASSWORD=mypassword holo-deck

# Custom remote port
SSH_SERVER=ssh.localhost.run SSH_KEY_PATH=~/.ssh/id_ed25519 REMOTE_PORT=8080 holo-deck

# Enable debug logging
RUST_LOG=debug SSH_SERVER=ssh.localhost.run SSH_KEY_PATH=~/.ssh/id_ed25519 holo-deck

Architecture

Holo-Deck is built with:

• Hyper - Fast HTTP implementation
• Tokio - Async runtime
• russh - Pure Rust SSH implementation
• Rust 2024 edition - Latest language features

How It Works

1. HTTP Server: Binds to a random available port on localhost, handles GET/POST requests
2. Reverse SSH Tunnel: Connects to SSH server (e.g., localhost.run)
3. Bidirectional Proxy: Routes external traffic through SSH to local server
4. File Storage: Files stored in current working directory

Security Considerations

• ✅ Path traversal protection (blocks .. and / in filenames)
• ✅ Local-only HTTP server (binds to 127.0.0.1)
• ✅ SSH key authentication for tunneling
• ⚠️ No authentication on file access - suitable for temporary sharing
• ⚠️ Tunnel URLs are public - anyone with the URL can access files

Recommendation: Use Holo-Deck for temporary file sharing in trusted environments. For production use, add authentication and HTTPS.

Development

Building from Source

git clone https://github.com/enzolombardi/holo-deck.git
cd holo-deck
cargo build --release

Running Tests

cargo test

Project Structure

holo-deck/
├── src/
│   └── main.rs           # HTTP server and CLI
├── Cargo.toml
├── README.md
└── logo.png

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is dual-licensed under:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

You may choose either license for your use.

Acknowledgments

• Built with ❤️ using Rust
• Inspired by Python's http.server and ngrok
• SSH tunneling powered by russh
• Tunnel hosting via localhost.run

Changelog

See CHANGELOG.md for release history.

Made with Rust 🦀