--- title: SSH description: Rust SDK - SSH API reference --- Reach a running sandbox over SSH: open a native in-process SSH client, run exec requests, attach an interactive shell, transfer files over SFTP, or stand up a reusable SSH server endpoint. Requires the `ssh` feature. See [SSH](/sandboxes/ssh) for usage flows. ```toml microsandbox = { version = "0.5.8", features = ["ssh"] } ```

Sandbox1

sb.ssh()SSH namespace for this sandbox

SandboxSsh8

ssh.connect()open a client ssh.open_client()alias of connect() ssh.connect_with()open a client with options ssh.open_client_with()alias of connect_with() ssh.server()prepare a server endpoint ssh.prepare_server()alias of server() ssh.server_with()server endpoint with options ssh.prepare_server_with()alias of server_with()

SshClient6

client.exec()run a command client.exec_with()run with options client.attach()interactive shell client.attach_with()attach with options client.sftp()open an SFTP session client.close()close the session

SshServer ยท SshStdioStream3

server.serve()serve one connection server.serve_connection()alias of serve() SshStdioStream::new()stdin/stdout transport

Option builders16

client.user() client.term() client.sftp() exec.tty() attach.term() attach.detach_keys() srv.host_key_path() srv.host_key() srv.authorized_keys_path() srv.authorized_key() srv.user() srv.sftp() + build() on each builder

Constants2

DEFAULT_SSH_HOSTdefault listener host DEFAULT_SSH_PORTdefault listener port

Types

SandboxSsh SshClient SshServer SshOutput SftpClient SshStdioStream SshClientOptionsBuilder SshExecOptionsBuilder SshAttachOptionsBuilder SshServerOptionsBuilder

Typical flow

```rust use microsandbox::Sandbox; let sb = Sandbox::builder("api") .image("python") .create() .await?; let client = sb.ssh().connect().await?; // 1. open an SSH client let out = client.exec("python -V").await?; // 2. run a command println!("{}", String::from_utf8_lossy(&out.stdout)); client.close().await?; // 3. close the session ``` ## Sandbox --- #### sb.ssh()
instance
```rust fn ssh(&self) -> SandboxSsh ``` Return the SSH namespace for this sandbox. The namespace holds the SSH client and server helpers; nothing connects until you call [`connect`](#ssh-connect) or [`server`](#ssh-server).

Returns

SandboxSsh
SSH namespace for this sandbox.
```rust let client = sb.ssh().connect().await?; ``` ## SandboxSsh SSH namespace for a sandbox, obtained from [`sb.ssh()`](#sb-ssh). SSH is only supported on local sandboxes; calls error with `Unsupported` against a cloud backend. --- #### ssh.connect()
instanceasync
```rust async fn connect(&self) -> MicrosandboxResult ``` Connect a native in-process SSH client to this sandbox. Generates an ephemeral Ed25519 client and host key pair, stands up an internal server bound to a duplex stream, and authenticates over public key. Uses default client options (user `root`, terminal from `$TERM`, SFTP enabled).

Returns

SshClient
Connected SSH client session.
```rust let client = sb.ssh().connect().await?; let out = client.exec("uname -a").await?; ``` --- #### ssh.open_client()
instanceasync
```rust async fn open_client(&self) -> MicrosandboxResult ``` Alias for [`connect`](#ssh-connect).

Returns

SshClient
Connected SSH client session.
--- #### ssh.connect_with()
instanceasync
```rust async fn connect_with( &self, f: impl FnOnce(SshClientOptionsBuilder) -> SshClientOptionsBuilder, ) -> MicrosandboxResult ``` Connect a native in-process SSH client with custom options. The closure configures the login user, terminal name, and whether SFTP is enabled on the internal server.

Parameters

Configure user, terminal, and SFTP support.

Returns

Connected SSH client session.
```rust let client = sb.ssh().connect_with(|opts| opts .user("app") .term("xterm-256color")).await?; ``` --- #### ssh.open_client_with()
instanceasync
```rust async fn open_client_with( &self, f: impl FnOnce(SshClientOptionsBuilder) -> SshClientOptionsBuilder, ) -> MicrosandboxResult ``` Alias for [`connect_with`](#ssh-connect_with).

Parameters

Configure user, terminal, and SFTP support.

Returns

Connected SSH client session.
--- #### ssh.server()
instanceasync
```rust async fn server(&self) -> MicrosandboxResult ``` Prepare a reusable SSH server endpoint for this sandbox. Loads or creates the host key and resolves authorized keys from the default authorized-keys file. The returned [`SshServer`](#sshserver) is cloneable and can serve many connections.

Returns

Reusable SSH server endpoint.
```rust let server = sb.ssh().server().await?; let (client_io, server_io) = tokio::io::duplex(64 * 1024); server.serve(server_io).await?; ``` --- #### ssh.prepare_server()
instanceasync
```rust async fn prepare_server(&self) -> MicrosandboxResult ``` Alias for [`server`](#ssh-server).

Returns

Reusable SSH server endpoint.
--- #### ssh.server_with()
instanceasync
```rust async fn server_with( &self, f: impl FnOnce(SshServerOptionsBuilder) -> SshServerOptionsBuilder, ) -> MicrosandboxResult ``` Prepare a server endpoint with custom host-key, authorization, guest-user, or SFTP options. If no authorized keys are configured, the default authorized-keys file is loaded; an empty key set is an error.

Parameters

Configure host key, authorized keys, guest user, and SFTP.

Returns

Reusable SSH server endpoint.
```rust let server = sb.ssh().server_with(|opts| opts .authorized_key("ssh-ed25519 AAAAC3Nza...") .user("app") .sftp(false)).await?; ``` --- #### ssh.prepare_server_with()
instanceasync
```rust async fn prepare_server_with( &self, f: impl FnOnce(SshServerOptionsBuilder) -> SshServerOptionsBuilder, ) -> MicrosandboxResult ``` Alias for [`server_with`](#ssh-server_with).

Parameters

Configure host key, authorized keys, guest user, and SFTP.

Returns

Reusable SSH server endpoint.
## SshClient A connected, native in-process SSH client session, obtained from [`connect`](#ssh-connect) or [`connect_with`](#ssh-connect_with). Aborts its internal server task on drop. --- #### client.exec()
instanceasync
```rust async fn exec(&self, command: impl Into) -> MicrosandboxResult ``` Run an SSH exec request and collect stdout, stderr, and the exit status. The command is run through the sandbox's configured shell (default `/bin/sh -c`). No PTY is requested.

Parameters

commandimpl Into<String>
Command string sent through SSH.

Returns

Captured output and exit status.
```rust let out = client.exec("echo hello").await?; println!("exit {}: {}", out.status, String::from_utf8_lossy(&out.stdout)); ``` --- #### client.exec_with()
instanceasync
```rust async fn exec_with( &self, command: impl Into, f: impl FnOnce(SshExecOptionsBuilder) -> SshExecOptionsBuilder, ) -> MicrosandboxResult ``` Run an SSH exec request with options. The closure can request a PTY via [`tty`](#sshexecoptionsbuilder); when a PTY is allocated, stderr is folded into stdout.

Parameters

commandimpl Into<String>
Command string sent through SSH.
Configure exec options.

Returns

Captured output and exit status.
```rust let out = client.exec_with("top -bn1", |opts| opts.tty(true)).await?; ``` --- #### client.attach()
instanceasync
```rust async fn attach(&self) -> MicrosandboxResult ``` Attach the local terminal to an interactive SSH shell. Requests a PTY sized to the current terminal, puts the terminal into raw mode, forwards keystrokes, relays window-resize events, and returns when the shell exits or the default detach key sequence is typed.

Returns

i32
Shell exit code (128 if terminated by signal).
```rust let code = client.attach().await?; println!("shell exited with {code}"); ``` --- #### client.attach_with()
instanceasync
```rust async fn attach_with( &self, f: impl FnOnce(SshAttachOptionsBuilder) -> SshAttachOptionsBuilder, ) -> MicrosandboxResult ``` Attach an interactive shell with custom terminal and detach-key options.

Parameters

Configure terminal name and detach keys.

Returns

i32
Shell exit code (128 if terminated by signal).
```rust let code = client.attach_with(|opts| opts .term("xterm-256color") .detach_keys("ctrl-p,ctrl-q")).await?; ``` --- #### client.sftp()
instanceasync
```rust async fn sftp(&self) -> MicrosandboxResult ``` Open an SFTP client session over this SSH connection. Requests the `sftp` subsystem and returns a high-level SFTP session for reading, writing, and listing files inside the guest.

Returns

SFTP client session.
```rust let sftp = client.sftp().await?; let mut file = sftp.create("/tmp/hello.txt").await?; ``` --- #### client.close()
instanceasync
```rust async fn close(self) -> MicrosandboxResult<()> ``` Close this native SSH client session. Sends a disconnect and aborts the internal server task. Consumes the client. ```rust client.close().await?; ``` ## SshServer A reusable SSH server endpoint for a sandbox, obtained from [`server`](#ssh-server) or [`server_with`](#ssh-server_with). Cloneable; each call to [`serve`](#server-serve) handles one connection. --- #### server.serve()
instanceasync
```rust async fn serve(&self, stream: S) -> MicrosandboxResult<()> where S: AsyncRead + AsyncWrite + Unpin + Send + 'static, ``` Serve one SSH connection over an ordered duplex stream. Runs the SSH handshake and session loop to completion. Returns when the connection closes.

Parameters

streamS: AsyncRead + AsyncWrite
Ordered duplex SSH transport.
```rust let server = sb.ssh().server().await?; let (client_io, server_io) = tokio::io::duplex(64 * 1024); tokio::spawn(async move { server.serve(server_io).await }); ``` --- #### server.serve_connection()
instanceasync
```rust async fn serve_connection(&self, stream: S) -> MicrosandboxResult<()> where S: AsyncRead + AsyncWrite + Unpin + Send + 'static, ``` Alias for [`serve`](#server-serve).

Parameters

streamS: AsyncRead + AsyncWrite
Ordered duplex SSH transport.
## SshStdioStream --- #### SshStdioStream::new()
static
```rust fn new() -> Self ``` Create a stdio SSH transport stream backed by this process's stdin and stdout. Implements [`AsyncRead`](#sshstdiostream) and `AsyncWrite`, so it can be passed straight to [`serve`](#server-serve) to bridge an SSH connection over the parent process's standard streams. Also available via `Default`.

Returns

Duplex stream over stdin/stdout.
```rust use microsandbox::SshStdioStream; let server = sb.ssh().server().await?; server.serve(SshStdioStream::new()).await?; ``` ## Constants --- #### DEFAULT_SSH_HOST
const
```rust pub const DEFAULT_SSH_HOST: &str = "127.0.0.1"; ``` Default SSH listener host used by the CLI adapter when binding a sandbox SSH endpoint. --- #### DEFAULT_SSH_PORT
const
```rust pub const DEFAULT_SSH_PORT: u16 = 2222; ``` Default SSH listener port used by the CLI adapter when binding a sandbox SSH endpoint. ## Types ### SshOutput
struct

Returned by client.exec(), client.exec_with()

Output from an SSH exec request. | Field | Type | Description | |-------|------|-------------| | `status` | `i32` | Exit status code. | | `stdout` | `Bytes` | Captured stdout bytes. | | `stderr` | `Bytes` | Captured stderr bytes (folded into stdout when a PTY is allocated). | ### SandboxSsh
struct

Returned by sb.ssh()

SSH namespace for a sandbox. Cheap to clone; holds a clone of the sandbox. | Method | Returns | Description | |--------|---------|-------------| | [`connect()`](#ssh-connect) | `SshClient` | Open a client with defaults. | | [`open_client()`](#ssh-open_client) | `SshClient` | Alias of `connect()`. | | [`connect_with()`](#ssh-connect_with) | `SshClient` | Open a client with options. | | [`open_client_with()`](#ssh-open_client_with) | `SshClient` | Alias of `connect_with()`. | | [`server()`](#ssh-server) | `SshServer` | Prepare a server endpoint. | | [`prepare_server()`](#ssh-prepare_server) | `SshServer` | Alias of `server()`. | | [`server_with()`](#ssh-server_with) | `SshServer` | Server endpoint with options. | | [`prepare_server_with()`](#ssh-prepare_server_with) | `SshServer` | Alias of `server_with()`. | ### SshClient
struct

Returned by ssh.connect(), ssh.connect_with()

Native in-process SSH client session. Aborts its internal server task on drop. | Method | Returns | Description | |--------|---------|-------------| | [`exec()`](#client-exec) | `SshOutput` | Run a command. | | [`exec_with()`](#client-exec_with) | `SshOutput` | Run with options. | | [`attach()`](#client-attach) | `i32` | Interactive shell. | | [`attach_with()`](#client-attach_with) | `i32` | Attach with options. | | [`sftp()`](#client-sftp) | `SftpClient` | Open an SFTP session. | | [`close()`](#client-close) | `()` | Close the session. | ### SshServer
struct

Returned by ssh.server(), ssh.server_with()

Reusable SSH server endpoint for a sandbox. Cloneable. | Method | Returns | Description | |--------|---------|-------------| | [`serve()`](#server-serve) | `()` | Serve one connection. | | [`serve_connection()`](#server-serve_connection) | `()` | Alias of `serve()`. | ### SftpClient
alias

Returned by client.sftp()

High-level SFTP client session. ```rust pub type SftpClient = russh_sftp::client::SftpSession; ``` ### SshStdioStream
struct

Used by server.serve()

Ordered duplex stream backed by this process's stdin and stdout. Implements `AsyncRead` and `AsyncWrite`. | Method | Returns | Description | |--------|---------|-------------| | [`new()`](#sshstdiostreamnew) | `SshStdioStream` | Create a stdio transport stream. | ### SshClientOptionsBuilder
builder

Used by ssh.connect_with()

Builder for SSH client options. Defaults: user `root`, terminal from `$TERM` (falling back to `xterm`), SFTP enabled. | Method | Parameters | Description | |--------|------------|-------------| | `user()` | `impl Into` | SSH login user. Default `root`. | | `term()` | `impl Into` | Terminal name for interactive sessions. | | `sftp()` | `bool` | Enable or disable SFTP on the internal server. Default `true`. | | `build()` | | Finalize the options. | ### SshExecOptionsBuilder
builder

Used by client.exec_with()

Builder for SSH exec options. | Method | Parameters | Description | |--------|------------|-------------| | `tty()` | `bool` | Request a PTY for the exec channel. Default `false`. | | `build()` | | Finalize the options. | ### SshAttachOptionsBuilder
builder

Used by client.attach_with()

Builder for interactive SSH attach options. Default terminal comes from `$TERM` (falling back to `xterm`); detach keys default to the standard sequence. | Method | Parameters | Description | |--------|------------|-------------| | `term()` | `impl Into` | Terminal name for the shell. | | `detach_keys()` | `impl Into` | Detach key sequence. | | `build()` | | Finalize the options. | ### SshServerOptionsBuilder
builder

Used by ssh.server_with()

Builder for SSH server options. SFTP is enabled by default; when no authorized keys are provided, the default authorized-keys file is loaded. | Method | Parameters | Description | |--------|------------|-------------| | `host_key_path()` | `impl Into` | Override the host private key path. | | `host_key()` | `PrivateKey` | Use an in-memory host private key. | | `authorized_keys_path()` | `impl Into` | Override the authorized-keys path. | | `authorized_key()` | `impl Into` | Add one in-memory authorized public key. | | `user()` | `impl Into` | Override the guest user used for exec requests. | | `sftp()` | `bool` | Enable or disable SFTP. Default `true`. | | `build()` | | Finalize the options. |