--- title: SSH description: TypeScript SDK - SSH API reference --- Reach a running sandbox over SSH: open an in-process client, run commands or attach an interactive shell, transfer files over SFTP, or expose the sandbox as a server endpoint. See [SSH](/sandboxes/ssh) for usage flows.

Sandbox ยท SandboxSshOps3

sb.ssh()SSH namespace for the sandbox ssh.openClient()open an in-process SSH client ssh.prepareServer()prepare a server endpoint

SshClient4

client.exec()run a command, collect output client.attach()attach an interactive shell client.sftp()open an SFTP session client.close()close the client

SftpClient10

.read() .write() .mkdir() .removeFile() .removeDir() .rename() .realPath() .readLink() .symlink() .close()

SshServer2

server.serveConnection()serve one transport over stdio server.close()release the endpoint

Types

SshOutput SshClientOptions SshExecOptions SshAttachOptions SshServerOptions

Typical flow

```typescript import { Sandbox } from "microsandbox"; await using sandbox = await Sandbox.builder("api") // 1. boot the sandbox .image("python") .create(); const client = await sandbox.ssh().openClient(); // 2. open an SSH client const out = await client.exec("python -V"); // 3. run a command console.log(out.stdout.toString()); await client.close(); // 4. close the client ``` ## SandboxSshOps The SSH namespace for a sandbox, returned by [`sb.ssh()`](#sb-ssh). It opens in-process SSH clients and prepares server endpoints against the running sandbox. --- #### sb.ssh()
instance
```typescript ssh(): SandboxSshOps ``` Return the SSH namespace for this sandbox. The returned object exposes [`openClient()`](#ssh-openclient) and [`prepareServer()`](#ssh-prepareserver).

Returns

SandboxSshOps
SSH client and server helpers.
```typescript const ssh = sandbox.ssh(); const client = await ssh.openClient(); ``` --- #### ssh.openClient()
instanceasync
```typescript openClient(opts?: SshClientOptions): Promise ``` Open a native in-process SSH client connected to the sandbox.

Parameters

optsSshClientOptions
Optional client options: login user, terminal name, SFTP toggle.

Returns

Promise<SshClient>
Connected SSH client session.
```typescript const client = await sandbox.ssh().openClient({ user: "root" }); ``` --- #### ssh.prepareServer()
instanceasync
```typescript prepareServer(opts?: SshServerOptions): Promise ``` Prepare a reusable SSH server endpoint backed by the sandbox.

Parameters

optsSshServerOptions
Optional server options: host key path, authorized-keys path, guest user, SFTP toggle.

Returns

Promise<SshServer>
Prepared server endpoint.
```typescript const server = await sandbox.ssh().prepareServer({ user: "root" }); await server.serveConnection(); ``` ## SshClient A native in-process SSH client session, returned by [`openClient()`](#ssh-openclient). Run commands, attach an interactive shell, or open an SFTP session over the same connection. Close it with [`close()`](#client-close) when done. --- #### client.exec()
instanceasync
```typescript exec(command: string, opts?: SshExecOptions): Promise ``` Run an SSH exec request and collect stdout, stderr, and the exit status.

Parameters

commandstring
Command string sent through SSH.
Optional exec options: request a PTY for the channel.

Returns

Captured output and exit status.
```typescript const out = await client.exec("uname -a"); console.log(out.status, out.stdout.toString()); ``` --- #### client.attach()
instanceasync
```typescript attach(opts?: SshAttachOptions): Promise ``` Attach the local terminal to an interactive SSH shell. Resolves with the shell's exit code once the session ends.

Parameters

Optional attach options: terminal name and detach key sequence.

Returns

Promise<number>
Exit code of the interactive shell.
```typescript const code = await client.attach({ detachKeys: "ctrl-p,ctrl-q" }); console.log(`shell exited with ${code}`); ``` --- #### client.sftp()
instanceasync
```typescript sftp(): Promise ``` Open an SFTP session over this SSH connection for file transfer and remote filesystem operations.

Returns

SFTP client session.
```typescript const sftp = await client.sftp(); await sftp.write("/tmp/data.bin", Buffer.from([1, 2, 3])); await sftp.close(); ``` --- #### client.close()
instanceasync
```typescript close(): Promise ``` Close the native SSH client session. ```typescript await client.close(); ``` ## SftpClient An SFTP session over an [`SshClient`](#sshclient) connection, returned by [`sftp()`](#client-sftp). Read and write files, manage directories, and resolve symlinks on the remote sandbox. Close it with [`close()`](#sftp-close) when done. --- #### sftp.read()
instanceasync
```typescript read(path: string): Promise ``` Read a remote file into memory.

Parameters

pathstring
Remote file path.

Returns

Promise<Buffer>
File contents.
```typescript const data = await sftp.read("/etc/hostname"); console.log(data.toString().trim()); ``` --- #### sftp.write()
instanceasync
```typescript write(path: string, data: Buffer): Promise ``` Create or truncate a remote file and write the given bytes.

Parameters

pathstring
Remote file path.
dataBuffer
Bytes to write.
```typescript await sftp.write("/tmp/config.json", Buffer.from(JSON.stringify({ ok: true }))); ``` --- #### sftp.mkdir()
instanceasync
```typescript mkdir(path: string): Promise ``` Create a remote directory.

Parameters

pathstring
Remote directory path.
```typescript await sftp.mkdir("/tmp/uploads"); ``` --- #### sftp.removeFile()
instanceasync
```typescript removeFile(path: string): Promise ``` Remove a remote file.

Parameters

pathstring
Remote file path.
```typescript await sftp.removeFile("/tmp/config.json"); ``` --- #### sftp.removeDir()
instanceasync
```typescript removeDir(path: string): Promise ``` Remove an empty remote directory.

Parameters

pathstring
Remote directory path.
```typescript await sftp.removeDir("/tmp/uploads"); ``` --- #### sftp.rename()
instanceasync
```typescript rename(oldPath: string, newPath: string): Promise ``` Rename or move a remote file or directory.

Parameters

oldPathstring
Existing remote path.
newPathstring
New remote path.
```typescript await sftp.rename("/tmp/data.bin", "/tmp/data.old"); ``` --- #### sftp.realPath()
instanceasync
```typescript realPath(path: string): Promise ``` Resolve a remote path to its canonical, absolute form.

Parameters

pathstring
Remote path to resolve.

Returns

Promise<string>
Canonical absolute path.
```typescript const abs = await sftp.realPath("./logs"); console.log(abs); ``` --- #### sftp.readLink()
instanceasync
```typescript readLink(path: string): Promise ``` Read the target of a remote symlink.

Parameters

pathstring
Remote symlink path.

Returns

Promise<string>
The symlink target.
```typescript const target = await sftp.readLink("/etc/localtime"); console.log(target); ``` --- #### sftp.symlink()
instanceasync
```typescript symlink(target: string, linkPath: string): Promise ``` Create a remote symlink at `linkPath` pointing to `target`.

Parameters

targetstring
What the symlink points to.
linkPathstring
Path of the symlink itself.
```typescript await sftp.symlink("/tmp/data.bin", "/tmp/latest"); ``` --- #### sftp.close()
instanceasync
```typescript close(): Promise ``` Close the SFTP session. ```typescript await sftp.close(); ``` ## SshServer A prepared SSH server endpoint, returned by [`prepareServer()`](#ssh-prepareserver). Serves SSH transports over standard streams and is released with [`close()`](#server-close). --- #### server.serveConnection()
instanceasync
```typescript serveConnection(): Promise ``` Serve one SSH transport over stdin/stdout. Resolves when the connection ends. ```typescript const server = await sandbox.ssh().prepareServer(); await server.serveConnection(); await server.close(); ``` --- #### server.close()
instanceasync
```typescript close(): Promise ``` Release the prepared server endpoint. ```typescript await server.close(); ``` ## Types --- ### SshOutput
interface

Returned by exec()

Captured result of an SSH exec request. | Property | Type | Description | |----------|------|-------------| | status | `number` | Exit status code | | stdout | `Buffer` | Captured stdout bytes | | stderr | `Buffer` | Captured stderr bytes | --- ### SshClientOptions
interface

Used by openClient()

Options for opening an SSH client. All fields are optional. | Property | Type | Description | |----------|------|-------------| | user | `string` | SSH login user | | term | `string` | Terminal name for interactive sessions | | sftp | `boolean` | Enable or disable SFTP on the internal server | --- ### SshExecOptions
interface

Used by exec()

Options for an SSH exec request. All fields are optional. | Property | Type | Description | |----------|------|-------------| | tty | `boolean` | Request a PTY for the exec channel | --- ### SshAttachOptions
interface

Used by attach()

Options for attaching an interactive SSH shell. All fields are optional. | Property | Type | Description | |----------|------|-------------| | term | `string` | Terminal name for the shell | | detachKeys | `string` | Detach key sequence | --- ### SshServerOptions
interface

Used by prepareServer()

Options for preparing an SSH server endpoint. All fields are optional. | Property | Type | Description | |----------|------|-------------| | hostKeyPath | `string` | Override the host private key path | | authorizedKeysPath | `string` | Override the authorized-keys path | | user | `string` | Override the guest user used for exec requests | | sftp | `boolean` | Enable or disable SFTP |