---
title: SSH
description: Rust SDK - SSH API reference
---

See [SSH](/sandboxes/ssh) for usage flows.

```toml
microsandbox = { version = "0.4.6", features = ["ssh"] }
```

## Sandbox

---

#### ssh()

```rust
fn ssh(&self) -> SandboxSsh
```

Return the SSH namespace for this sandbox.

**Returns**

| Type | Description |
|------|-------------|
| [`SandboxSsh`](#sandboxssh) | SSH client and server helpers |

## SandboxSsh

---

#### connect()

```rust
async fn connect(&self) -> MicrosandboxResult<SshClient>
```

Connect a native in-process SSH client to the sandbox.

**Returns**

| Type | Description |
|------|-------------|
| [`SshClient`](#sshclient) | Native SSH client session |

---

#### connect_with()

```rust
async fn connect_with(
    &self,
    f: impl FnOnce(SshClientOptionsBuilder) -> SshClientOptionsBuilder,
) -> MicrosandboxResult<SshClient>
```

Connect a native SSH client with custom client options.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| f | `FnOnce(SshClientOptionsBuilder) -> SshClientOptionsBuilder` | Configure user, terminal, and SFTP support |

**Returns**

| Type | Description |
|------|-------------|
| [`SshClient`](#sshclient) | Native SSH client session |

---

#### server()

```rust
async fn server(&self) -> MicrosandboxResult<SshServer>
```

Prepare a reusable SSH server endpoint for this sandbox.

**Returns**

| Type | Description |
|------|-------------|
| [`SshServer`](#sshserver) | Reusable SSH server endpoint |

---

#### server_with()

```rust
async fn server_with(
    &self,
    f: impl FnOnce(SshServerOptionsBuilder) -> SshServerOptionsBuilder,
) -> MicrosandboxResult<SshServer>
```

Prepare a server endpoint with custom host-key, authorization, user, or SFTP options.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| f | `FnOnce(SshServerOptionsBuilder) -> SshServerOptionsBuilder` | Configure server options |

**Returns**

| Type | Description |
|------|-------------|
| [`SshServer`](#sshserver) | Reusable SSH server endpoint |

## SshClient

---

#### exec()

```rust
async fn exec(&self, command: impl Into<String>) -> MicrosandboxResult<SshOutput>
```

Run an SSH exec request and collect stdout, stderr, and exit status.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| command | `impl Into<String>` | Command string sent through SSH |

**Returns**

| Type | Description |
|------|-------------|
| [`SshOutput`](#sshoutput) | Captured output and status |

---

#### exec_with()

```rust
async fn exec_with(
    &self,
    command: impl Into<String>,
    f: impl FnOnce(SshExecOptionsBuilder) -> SshExecOptionsBuilder,
) -> MicrosandboxResult<SshOutput>
```

Run an SSH exec request with options.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| command | `impl Into<String>` | Command string sent through SSH |
| f | `FnOnce(SshExecOptionsBuilder) -> SshExecOptionsBuilder` | Configure exec options |

**Returns**

| Type | Description |
|------|-------------|
| [`SshOutput`](#sshoutput) | Captured output and status |

---

#### attach()

```rust
async fn attach(&self) -> MicrosandboxResult<i32>
```

Attach the local terminal to an interactive SSH shell.

**Returns**

| Type | Description |
|------|-------------|
| `i32` | Exit code |

---

#### attach_with()

```rust
async fn attach_with(
    &self,
    f: impl FnOnce(SshAttachOptionsBuilder) -> SshAttachOptionsBuilder,
) -> MicrosandboxResult<i32>
```

Attach with terminal options.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| f | `FnOnce(SshAttachOptionsBuilder) -> SshAttachOptionsBuilder` | Configure terminal and detach keys |

**Returns**

| Type | Description |
|------|-------------|
| `i32` | Exit code |

---

#### sftp()

```rust
async fn sftp(&self) -> MicrosandboxResult<SftpClient>
```

Open an SFTP session over this SSH connection.

**Returns**

| Type | Description |
|------|-------------|
| [`SftpClient`](#sftpclient) | SFTP client session |

---

#### close()

```rust
async fn close(self) -> MicrosandboxResult<()>
```

Close the native SSH client session.

## SshServer

---

#### serve()

```rust
async fn serve<S>(&self, stream: S) -> MicrosandboxResult<()>
where
    S: AsyncRead + AsyncWrite + Unpin + Send + 'static
```

Serve one SSH connection over an ordered duplex stream.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| stream | `S` | Ordered duplex SSH transport |

## Types

### SshOutput

| Field | Type | Description |
|-------|------|-------------|
| status | `i32` | Exit status code |
| stdout | `Bytes` | Captured stdout bytes |
| stderr | `Bytes` | Captured stderr bytes |

### SftpClient

Alias for `russh_sftp::client::SftpSession`.

### SshClientOptionsBuilder

| Method | Parameters | Description |
|--------|------------|-------------|
| user() | `impl Into<String>` | SSH login user. Defaults to `root` |
| term() | `impl Into<String>` | Terminal name for interactive sessions |
| sftp() | `bool` | Enable or disable SFTP on the internal server |

### SshExecOptionsBuilder

| Method | Parameters | Description |
|--------|------------|-------------|
| tty() | `bool` | Request a PTY for the exec channel |

### SshAttachOptionsBuilder

| Method | Parameters | Description |
|--------|------------|-------------|
| term() | `impl Into<String>` | Terminal name for the shell |
| detach_keys() | `impl Into<String>` | Detach key sequence |

### SshServerOptionsBuilder

| Method | Parameters | Description |
|--------|------------|-------------|
| host_key_path() | `impl Into<PathBuf>` | Override the host private key path |
| host_key() | `PrivateKey` | Use an in-memory host private key |
| authorized_keys_path() | `impl Into<PathBuf>` | Override the authorized-keys path |
| authorized_key() | `impl Into<String>` | Add one in-memory authorized public key |
| user() | `impl Into<String>` | Override the guest user used for exec requests |
| sftp() | `bool` | Enable or disable SFTP |
