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.