SSH - microsandbox

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 for usage flows.

Typical flow

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(). It opens in-process SSH clients and prepares server endpoints against the running sandbox.

sb.ssh()

ssh(): SandboxSshOps

Example

const ssh = sandbox.ssh();
const client = await ssh.openClient();

Return the SSH namespace for this sandbox. The returned object exposes openClient() and prepareServer().

Returns

SandboxSshOps

SSH client and server helpers.

ssh.openClient()

openClient(opts?: SshClientOptions): Promise<SshClient>

Example

const client = await sandbox.ssh().openClient({ user: "root" });

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.

ssh.prepareServer()

prepareServer(opts?: SshServerOptions): Promise<SshServer>

Example

const server = await sandbox.ssh().prepareServer({ user: "root" });
await server.serveConnection();

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.

SshClient

A native in-process SSH client session, returned by openClient(). Run commands, attach an interactive shell, or open an SFTP session over the same connection. Close it with close() when done.

client.exec()

exec(command: string, opts?: SshExecOptions): Promise<SshOutput>

Example

const out = await client.exec("uname -a");
console.log(out.status, out.stdout.toString());

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

Parameters

commandstring

Command string sent through SSH.

optsSshExecOptions

Optional exec options: request a PTY for the channel.

Returns

Promise<SshOutput>

Captured output and exit status.

client.attach()

attach(opts?: SshAttachOptions): Promise<number>

Example

const code = await client.attach({ detachKeys: "ctrl-p,ctrl-q" });
console.log(`shell exited with ${code}`);

Attach the local terminal to an interactive SSH shell. Resolves with the shell’s exit code once the session ends.

Parameters

optsSshAttachOptions

Optional attach options: terminal name and detach key sequence.

Returns

Promise<number>

Exit code of the interactive shell.

client.sftp()

sftp(): Promise<SftpClient>

Example

const sftp = await client.sftp();
await sftp.write("/tmp/data.bin", Buffer.from([1, 2, 3]));
await sftp.close();

Open an SFTP session over this SSH connection for file transfer and remote filesystem operations.

Returns

Promise<SftpClient>

SFTP client session.

client.close()

close(): Promise<void>

Example

await client.close();

Close the native SSH client session.

SftpClient

An SFTP session over an SshClient connection, returned by sftp(). Read and write files, manage directories, and resolve symlinks on the remote sandbox. Close it with close() when done.

sftp.read()

read(path: string): Promise<Buffer>

Example

const data = await sftp.read("/etc/hostname");
console.log(data.toString().trim());

Read a remote file into memory.

Parameters

pathstring

Remote file path.

Returns

Promise<Buffer>

File contents.

sftp.write()

write(path: string, data: Buffer): Promise<void>

Example

await sftp.write("/tmp/config.json", Buffer.from(JSON.stringify({ ok: true })));

Create or truncate a remote file and write the given bytes.

Parameters

pathstring

Remote file path.

dataBuffer

Bytes to write.

sftp.mkdir()

mkdir(path: string): Promise<void>

Example

await sftp.mkdir("/tmp/uploads");

Create a remote directory.

Parameters

pathstring

Remote directory path.

sftp.removeFile()

removeFile(path: string): Promise<void>

Example

await sftp.removeFile("/tmp/config.json");

Remove a remote file.

Parameters

pathstring

Remote file path.

sftp.removeDir()

removeDir(path: string): Promise<void>

Example

await sftp.removeDir("/tmp/uploads");

Remove an empty remote directory.

Parameters

pathstring

Remote directory path.

sftp.rename()

rename(oldPath: string, newPath: string): Promise<void>

Example

await sftp.rename("/tmp/data.bin", "/tmp/data.old");

Rename or move a remote file or directory.

Parameters

oldPathstring

Existing remote path.

newPathstring

New remote path.

sftp.realPath()

realPath(path: string): Promise<string>

Example

const abs = await sftp.realPath("./logs");
console.log(abs);

Resolve a remote path to its canonical, absolute form.

Parameters

pathstring

Remote path to resolve.

Returns

Promise<string>

Canonical absolute path.

sftp.readLink()

readLink(path: string): Promise<string>

Example

const target = await sftp.readLink("/etc/localtime");
console.log(target);

Read the target of a remote symlink.

Parameters

pathstring

Remote symlink path.

Returns

Promise<string>

The symlink target.

sftp.symlink()

symlink(target: string, linkPath: string): Promise<void>

Example

await sftp.symlink("/tmp/data.bin", "/tmp/latest");

Create a remote symlink at linkPath pointing to target.

Parameters

targetstring

What the symlink points to.

linkPathstring

Path of the symlink itself.

sftp.close()

close(): Promise<void>

Example

await sftp.close();

Close the SFTP session.

SshServer

A prepared SSH server endpoint, returned by prepareServer(). Serves SSH transports over standard streams and is released with close().

server.serveConnection()

serveConnection(): Promise<void>

Example

const server = await sandbox.ssh().prepareServer();
await server.serveConnection();
await server.close();

Serve one SSH transport over stdin/stdout. Resolves when the connection ends.

server.close()

close(): Promise<void>

Example

await server.close();

Release the prepared server endpoint.

Types

SshOutput

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

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

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

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

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

​SandboxSshOps

​sb.ssh()

​ssh.openClient()

​ssh.prepareServer()

​SshClient

​client.exec()

​client.attach()

​client.sftp()

​client.close()

​SftpClient

​sftp.read()

​sftp.write()

​sftp.mkdir()

​sftp.removeFile()

​sftp.removeDir()

​sftp.rename()

​sftp.realPath()

​sftp.readLink()

​sftp.symlink()

​sftp.close()

​SshServer

​server.serveConnection()

​server.close()

​Types

​SshOutput

​SshClientOptions

​SshExecOptions

​SshAttachOptions

​SshServerOptions

SandboxSshOps

sb.ssh()

ssh.openClient()

ssh.prepareServer()

SshClient

client.exec()

client.attach()

client.sftp()

client.close()

SftpClient

sftp.read()

sftp.write()

sftp.mkdir()

sftp.removeFile()

sftp.removeDir()

sftp.rename()

sftp.realPath()

sftp.readLink()

sftp.symlink()

sftp.close()

SshServer

server.serveConnection()

server.close()

Types

SshOutput

SshClientOptions

SshExecOptions

SshAttachOptions

SshServerOptions