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

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

## Sandbox

---

#### ssh()

```python
def ssh() -> SandboxSsh
```

Return the SSH namespace for this sandbox.

**Returns**

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

## SandboxSsh

---

#### connect()

```python
async def connect(
    *,
    user: str = "root",
    term: str | None = None,
    sftp: bool = True,
) -> SshClient
```

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

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| user | `str` | SSH login user |
| term | `str \| None` | Terminal name for interactive sessions |
| sftp | `bool` | Enable or disable SFTP on the internal server |

**Returns**

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

---

#### server()

```python
async def 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.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| host_key_path | `str \| os.PathLike[str] \| None` | Override the host private key path |
| authorized_keys_path | `str \| os.PathLike[str] \| None` | Override the authorized-keys path |
| user | `str \| None` | Override the guest user used for exec requests |
| sftp | `bool` | Enable or disable SFTP |

**Returns**

| Type | Description |
|------|-------------|
| [`SshServer`](#sshserver) | Server endpoint |

## SshClient

---

#### exec()

```python
async def exec(command: str, *, tty: bool = False) -> SshOutput
```

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

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| command | `str` | Command string sent through SSH |
| tty | `bool` | Request a PTY for the exec channel |

**Returns**

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

---

#### attach()

```python
async def attach(
    *,
    term: str | None = None,
    detach_keys: str | None = None,
) -> int
```

Attach the local terminal to an interactive SSH shell.

**Parameters**

| Name | Type | Description |
|------|------|-------------|
| term | `str \| None` | Terminal name for the shell |
| detach_keys | `str \| None` | Detach key sequence |

**Returns**

| Type | Description |
|------|-------------|
| `int` | Exit code |

---

#### sftp()

```python
async def sftp() -> SftpClient
```

Open an SFTP session over this SSH connection.

**Returns**

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

---

#### close()

```python
async def close() -> None
```

Close the native SSH client session.

## SftpClient

| Method | Returns | Description |
|--------|---------|-------------|
| read(path) | `bytes` | Read a file into memory |
| write(path, data) | `None` | Create or truncate a file |
| 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 canonical path |
| read_link(path) | `str` | Read a symlink target |
| symlink(target, link_path) | `None` | Create a symlink |
| close() | `None` | Close the SFTP session |

## SshServer

---

#### serve_stdio()

```python
async def serve_stdio() -> None
```

Serve one SSH transport over stdin/stdout.

---

#### close()

```python
def close() -> None
```

Release the prepared server endpoint.

## Types

### SshOutput

| Property | Type | Description |
|----------|------|-------------|
| status | `int` | Exit status code |
| success | `bool` | `True` if status is `0` |
| stdout_text | `str` | Captured stdout decoded as UTF-8 |
| stderr_text | `str` | Captured stderr decoded as UTF-8 |
| stdout_bytes | `bytes` | Captured stdout bytes |
| stderr_bytes | `bytes` | Captured stderr bytes |
