Skip to main content

Crate shell_tunnel

Crate shell_tunnel 

Source
Expand description

§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§

actions
Named actions: commands a device’s owner has defined, which a token can be allowed to run without being allowed to run anything else.
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.
expose
Exposed services: HTTP services on this machine’s loopback that the device’s owner names at startup, reachable through this server under the same authorization, audit trail and relay path as everything else it serves.
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.