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. A command is run by a fresh shell — cmd /c on Windows, /bin/sh -c elsewhere — and its output is captured through pipes; nothing here allocates a terminal.

Features

• Cross-platform: One API over the platform’s shell
• 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 std::sync::Arc;
use shell_tunnel::{Command, CommandExecutor, SessionStore};

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

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

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

    // Run a command in it — a fresh shell per call, nothing kept between
    let executor = CommandExecutor::new(store);
    let result = executor
        .execute_in_session(&session_id, &Command::new("echo hello"))
        .await?;

    println!("Session {} exited with {:?}", session_id, result.exit_code);

    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 fs::FsError;

pub use fs::FsRoot;

pub use output::OutputSanitizer;

pub use output::VirtualScreen;

pub use session::Session;

pub use session::SessionContext;

pub use session::SessionId;

pub use session::SessionState;

pub use session::SessionStore;

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.

fs

Filesystem access, confined to a configured root.

logging

Logging initialization and configuration.

output

Output processing and sanitization.

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.