Crate shell_tunnel 

shell-tunnel

Ultra-lightweight remote shell gateway with a REST/WebSocket API.

This crate provides a cross-platform API for programmatic interaction with system shells. It supports both Windows (ConPTY) and Unix (PTY) terminals through a unified interface.

Features

• Cross-platform PTY: Unified interface for Windows ConPTY and Unix PTY
• Async I/O: Non-blocking operations using tokio
• Session Management: Stateful shell sessions with lifecycle tracking
• REST API: HTTP endpoints for command execution
• WebSocket: Real-time streaming of command output
• Lightweight: Minimal dependencies, small binary size

Quick Start

use shell_tunnel::{NativePty, PtySize, SessionStore, SessionConfig};

#[tokio::main]
async fn main() -> shell_tunnel::Result<()> {
    // Initialize logging
    shell_tunnel::logging::try_init().ok();

    // Create a session store
    let store = SessionStore::new();

    // Create a new session
    let session_id = store.create(SessionConfig::default())?;

    // Spawn a PTY
    let pty = NativePty::new();
    let handle = pty.spawn_default(PtySize::default())?;

    println!("Session {} created with PID {}", session_id, handle.pid);

    Ok(())
}

API Server

use shell_tunnel::api::{ServerConfig, serve};

#[tokio::main]
async fn main() -> shell_tunnel::Result<()> {
    shell_tunnel::logging::try_init().ok();
    let config = ServerConfig::new("127.0.0.1", 3000);
    serve(config).await
}

Re-exports

pub use error::Result;

pub use error::ShellTunnelError;

pub use execution::Command;

pub use execution::CommandExecutor;

pub use execution::ExecutionResult;

pub use output::OutputSanitizer;

pub use output::VirtualScreen;

pub use pty::AsyncPtyReader;

pub use pty::AsyncPtyWriter;

pub use pty::NativePty;

pub use pty::PtyHandle;

pub use pty::PtySize;

pub use session::Session;

pub use session::SessionConfig;

pub use session::SessionContext;

pub use session::SessionId;

pub use session::SessionState;

pub use session::SessionStore;

pub use session::StateProbe;

pub use api::AppState;

pub use api::ServerConfig;

pub use security::ApiKeyStore;

pub use security::AuthConfig;

pub use security::CapabilitySet;

pub use security::CommandValidator;

pub use security::RateLimiter;

pub use security::TokenRecord;

pub use security::ValidationConfig;

pub use relay::RelayConfig;

pub use relay::RelayState;

pub use tunnel::TunnelHandle;

pub use tunnel::TunnelProvider;

pub use cli::parse_args;

pub use cli::print_help;

pub use cli::print_version;

pub use cli::Args;

pub use config::Config;

pub use config::ConfigError;

Modules

api

API layer for shell-tunnel.

audit

Append-only audit trail.

cli

Command-line interface for shell-tunnel.

config

Configuration management for shell-tunnel.

error

Error types for shell-tunnel.

execution

Command execution engine.

logging

Logging initialization and configuration.

output

Output processing and sanitization.

pty

PTY (Pseudo-Terminal) abstraction layer.

relay

Self-hosted relay: reaching a device that dialled out to you.

security

Security module for shell-tunnel.

session

Session management module.

tunnel

Reachability: making a local server reachable from the internet.