SSH - Microsandbox — ContextQMD

See SSH for usage flows.

Sandbox

ssh()

python

def ssh() -> SandboxSsh

Return the SSH namespace for this sandbox.

Returns

Type	Description
`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`	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`	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`	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`	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