---
title: SSH
description: Python 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 server endpoint that serves connections over stdin/stdout. See [SSH](/sandboxes/ssh) for usage flows.
Typical flow
```python
from microsandbox import Sandbox
async with await Sandbox.create("api", image="python") as sb:
client = await sb.ssh().open_client() # 1. open an SSH client
out = await client.exec("python -V") # 2. run a command
print(out.stdout_text)
await client.close() # 3. close the session
```
## Sandbox
---
#### sb.ssh()
instance
```python
def ssh() -> SandboxSshOps
```
Return the SSH namespace for this sandbox. The namespace holds the SSH client and server helpers; nothing connects until you call [`open_client()`](#ssh-open_client) or [`prepare_server()`](#ssh-prepare_server). This method is synchronous; the helpers it returns are async.
Returns
SSH namespace for this sandbox.
```python
client = await sb.ssh().open_client()
```
## SandboxSshOps
SSH namespace for a sandbox, obtained from [`sb.ssh()`](#sb-ssh). SSH is only supported on local sandboxes.
---
#### ssh.open_client()
instanceasync
```python
async def open_client(
*,
user: str = "root",
term: str | None = None,
sftp: bool = True,
) -> SshClient
```
Connect a native in-process SSH client to this sandbox. Generates an ephemeral client and host key pair, stands up an internal server bound to an in-memory stream, and authenticates over public key.
Parameters
userstr
SSH login user. Default "root".
termstr | None
Terminal name for interactive sessions. Defaults to $TERM.
sftpbool
Enable or disable SFTP on the internal server. Default True.
Returns
Connected SSH client session.
```python
client = await sb.ssh().open_client(user="app", term="xterm-256color")
out = await client.exec("uname -a")
```
---
#### ssh.prepare_server()
instanceasync
```python
async def prepare_server(
*,
host_key_path: str | os.PathLike[str] | None = None,
authorized_keys_path: str | os.PathLike[str] | None = None,
user: str | None = None,
sftp: bool = True,
) -> SshServer
```
Prepare a reusable SSH server endpoint for this sandbox. Loads or creates the host key and resolves authorized keys, falling back to the default authorized-keys file when no path is given. The returned [`SshServer`](#sshserver) serves one connection over this process's stdin/stdout.
Parameters
host_key_pathstr | os.PathLike[str] | None
Override the host private key path.
authorized_keys_pathstr | os.PathLike[str] | None
Override the authorized-keys path.
userstr | None
Override the guest user used for exec requests.
sftpbool
Enable or disable SFTP. Default True.
Returns
Reusable SSH server endpoint.
```python
server = await sb.ssh().prepare_server(
authorized_keys_path="/home/me/.ssh/authorized_keys",
user="app",
sftp=False,
)
await server.serve_connection()
```
## SshClient
A connected, native in-process SSH client session, obtained from [`ssh.open_client()`](#ssh-open_client).
---
#### client.exec()
instanceasync
```python
async def exec(command: str, *, tty: bool = False) -> SshOutput
```
Run an SSH exec request and collect stdout, stderr, and the exit status. The command runs through the sandbox's configured shell. When `tty=True` a PTY is allocated and stderr is folded into stdout.
Parameters
commandstr
Command string sent through SSH.
ttybool
Request a PTY for the exec channel. Default False.
Returns
Captured output and exit status.
```python
out = await client.exec("echo hello")
print(f"exit {out.status}: {out.stdout_text}")
```
---
#### client.attach()
instanceasync
```python
async def attach(
*,
term: str | None = None,
detach_keys: str | None = None,
) -> int
```
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, and returns when the shell exits or the detach key sequence is typed.
Parameters
termstr | None
Terminal name for the shell. Defaults to $TERM.
detach_keysstr | None
Detach key sequence, e.g. "ctrl-p,ctrl-q".
Returns
int
Shell exit code (128 if terminated by signal).
```python
code = await client.attach(term="xterm-256color", detach_keys="ctrl-p,ctrl-q")
print(f"shell exited with {code}")
```
---
#### client.sftp()
instanceasync
```python
async def sftp() -> SftpClient
```
Open an SFTP client session over this SSH connection. Requests the `sftp` subsystem and returns a high-level session for reading, writing, and listing files inside the guest.
Returns
```python
sftp = await client.sftp()
await sftp.write("/tmp/hello.txt", b"hi")
data = await sftp.read("/tmp/hello.txt")
```
---
#### client.close()
instanceasync
```python
async def close() -> None
```
Close this native SSH client session. Sends a disconnect and aborts the internal server task.
```python
await client.close()
```
## SshServer
A reusable SSH server endpoint for a sandbox, obtained from [`ssh.prepare_server()`](#ssh-prepare_server).
---
#### server.serve_connection()
instanceasync
```python
async def serve_connection() -> None
```
Serve one SSH transport over this process's stdin/stdout. Runs the SSH handshake and session loop to completion, returning when the connection closes. Use this to bridge an SSH connection over the parent process's standard streams.
```python
server = await sb.ssh().prepare_server()
await server.serve_connection()
```
---
#### server.close()
instance
```python
def close() -> None
```
Release this prepared server endpoint. This method is synchronous.
```python
server.close()
```
## Types
### SandboxSshOps
class
Returned by sb.ssh()
SSH namespace for a sandbox.
| Method | Returns | Description |
|--------|---------|-------------|
| [`open_client()`](#ssh-open_client) | [`SshClient`](#sshclient) | *(async)* Open a client. |
| [`prepare_server()`](#ssh-prepare_server) | [`SshServer`](#sshserver) | *(async)* Prepare a server endpoint. |
### SshClient
class
Returned by ssh.open_client()
Native in-process SSH client session.
| Method | Returns | Description |
|--------|---------|-------------|
| [`exec(command, *, tty=False)`](#client-exec) | [`SshOutput`](#sshoutput) | *(async)* Run a command. |
| [`attach(*, term=None, detach_keys=None)`](#client-attach) | `int` | *(async)* Interactive shell. |
| [`sftp()`](#client-sftp) | [`SftpClient`](#sftpclient) | *(async)* Open an SFTP session. |
| [`close()`](#client-close) | `None` | *(async)* Close the session. |
### SshServer
class
Returned by ssh.prepare_server()
Reusable SSH server endpoint for a sandbox.
| Method | Returns | Description |
|--------|---------|-------------|
| [`serve_connection()`](#server-serve_connection) | `None` | *(async)* Serve one connection over stdin/stdout. |
| [`close()`](#server-close) | `None` | Release the prepared endpoint. |
### SftpClient
class
Returned by client.sftp()
High-level SFTP client session over an SSH connection. All methods are async.
| Method | Returns | Description |
|--------|---------|-------------|
| read(path) | `bytes` | Read a file into memory. |
| write(path, data) | `None` | Write a file, creating or truncating it. |
| mkdir(path) | `None` | Create a directory. |
| remove_file(path) | `None` | Remove a file. |
| remove_dir(path) | `None` | Remove an empty directory. |
| rename(old_path, new_path) | `None` | Rename a file or directory. |
| real_path(path) | `str` | Resolve a path to its canonical absolute form. |
| read_link(path) | `str` | Read a symlink target. |
| symlink(target, link_path) | `None` | Create a symlink. |
| close() | `None` | Close the SFTP session. |
### SshOutput
class
Returned by client.exec()
Output from an SSH exec request.
| Property | Type | Description |
|----------|------|-------------|
| status | `int` | Exit status code. |
| success | `bool` | Whether the command exited successfully. |
| stdout_text | `str` | Stdout as UTF-8 text. |
| stderr_text | `str` | Stderr as UTF-8 text. |
| stdout_bytes | `bytes` | Stdout as raw bytes. |
| stderr_bytes | `bytes` | Stderr as raw bytes. |