SSH

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 SSH server endpoint. See SSH for usage flows.

Sandbox

sb.SSH()

func (s *Sandbox) SSH() *SandboxSSHOps

Example

ssh := sb.SSH()
client, err := ssh.OpenClient(ctx)

Return the SSH operations namespace for this sandbox. The namespace groups the client and server helpers; it holds no resources of its own.

Returns

*SandboxSSHOps

SSH client and server helpers for this sandbox.

SandboxSSHOps

Returned by SSH()

SSH operations namespace for a sandbox. Obtained via sb.SSH(). Holds no resources; it groups the client and server entry points.

ssh.OpenClient()

func (ssh *SandboxSSHOps) OpenClient(ctx context.Context, opts ...SSHClientOption) (*SSHClient, error)

Example

client, err := sb.SSH().OpenClient(ctx,
    m.WithSSHUser("app"),
    m.WithSSHTerm("xterm-256color"),
)
if err != nil {
    return err
}
defer client.Close(ctx)

Open a native in-process SSH client to this sandbox. Generates an ephemeral Ed25519 client and host key pair, stands up an internal server bound to a duplex stream, and authenticates over public key. With no options it uses login user root, terminal from $TERM (falling back to xterm), and SFTP enabled.

Parameters

ctxcontext.Context

Cancels the connection attempt.

opts…SSHClientOption

Returns

*SSHClient

Native SSH client session.

error

Typed microsandbox error.

ssh.PrepareServer()

func (ssh *SandboxSSHOps) PrepareServer(ctx context.Context, opts ...SSHServerOption) (*SSHServer, error)

Example

srv, err := sb.SSH().PrepareServer(ctx,
    m.WithSSHAuthorizedKeysPath("/etc/msb/authorized_keys"),
)
if err != nil {
    return err
}
defer srv.Close(ctx)

Prepare a reusable SSH server endpoint for this sandbox. Loads or creates the host key and resolves authorized keys from the default authorized-keys file unless overridden. The returned SSHServer can serve connections one at a time over the process’s standard streams.

Parameters

ctxcontext.Context

Cancels server preparation.

opts…SSHServerOption

Host key, authorized keys, guest user, SFTP toggle, and inactivity timeout.

Returns

*SSHServer

Prepared server endpoint.

error

Typed microsandbox error.

SSHClient

Returned by OpenClient()

A native in-process SSH client session. Obtained via OpenClient().

c.Exec()

func (c *SSHClient) Exec(ctx context.Context, command string, opts ...SSHExecOption) (*SSHOutput, error)

Example

out, err := client.Exec(ctx, "python -V")
if err != nil {
    return err
}
if !out.Success() {
    return fmt.Errorf("exit %d: %s", out.Status, out.Stderr)
}
fmt.Printf("%s", out.Stdout)

Run an SSH exec request and collect stdout, stderr, and the exit status. The command is run through the sandbox’s configured shell. No PTY is requested unless WithSSHTTY is passed.

Parameters

ctxcontext.Context

Cancels the exec request.

commandstring

Command string sent through SSH.

opts…SSHExecOption

PTY toggle for the exec channel.

Returns

*SSHOutput

Captured stdout, stderr, and exit status.

error

Typed microsandbox error.

c.Attach()

func (c *SSHClient) Attach(ctx context.Context, opts ...SSHAttachOption) (int, error)

Example

code, err := client.Attach(ctx,
    m.WithSSHAttachTerm("xterm-256color"),
    m.WithSSHDetachKeys("ctrl-p,ctrl-q"),
)
if err != nil {
    return err
}
fmt.Printf("shell exited with %d\n", code)

Bridge the local terminal to an interactive SSH shell. Requests a PTY sized to the current terminal, puts the terminal into raw mode, forwards keystrokes, relays window-resize events, and returns when the shell exits or the detach key sequence is typed.

Parameters

ctxcontext.Context

Cancels the attach session.

opts…SSHAttachOption

Terminal name and detach key sequence.

Returns

int

Shell exit code (128 if terminated by signal).

error

Typed microsandbox error.

c.SFTP()

func (c *SSHClient) SFTP(ctx context.Context) (*SFTPClient, error)

Example

sftp, err := client.SFTP(ctx)
if err != nil {
    return err
}
defer sftp.Close(ctx)

if err := sftp.Write(ctx, "/tmp/hello.txt", []byte("hi")); err != nil {
    return err
}

Open an SFTP session over this SSH connection. Returns a high-level SFTP client for reading, writing, and managing files inside the guest. Requires SFTP enabled on the client (the default).

Parameters

ctxcontext.Context

Cancels opening the SFTP session.

Returns

*SFTPClient

SFTP client session.

error

Typed microsandbox error.

c.Close()

func (c *SSHClient) Close(ctx context.Context) error

Example

defer client.Close(ctx)

Close this SSH client session. The handle is consumed; do not use it after closing.

Parameters

ctxcontext.Context

Cancels the close.

Returns

error

Typed microsandbox error.

SSHServer

Returned by PrepareServer()

A prepared SSH server endpoint for a sandbox. Obtained via PrepareServer().

srv.ServeConnection()

func (srv *SSHServer) ServeConnection(ctx context.Context) error

Example

srv, err := sb.SSH().PrepareServer(ctx)
if err != nil {
    return err
}
defer srv.Close(ctx)

if err := srv.ServeConnection(ctx); err != nil {
    return err
}

Serve one SSH transport over this process’s stdin and stdout. Returns when the connection ends. Call again on the same SSHServer to serve another connection.

Parameters

ctxcontext.Context

Cancels serving the connection.

Returns

error

Typed microsandbox error.

srv.Close()

func (srv *SSHServer) Close(ctx context.Context) error

Example

defer srv.Close(ctx)

Release this prepared server endpoint. The handle is consumed; do not use it after closing.

Parameters

ctxcontext.Context

Cancels the close.

Returns

error

Typed microsandbox error.

SSHOutput

Returned by Exec()

The output from an SSH exec request.

o.Status

int Exit status code

o.Stdout

[]byte Captured stdout bytes

o.Stderr

[]byte Captured stderr bytes

o.Success()

func (o SSHOutput) Success() bool

Example

out, err := client.Exec(ctx, "test -f /etc/passwd")
if err != nil {
    return err
}
fmt.Println("present:", out.Success())

Report whether the command exited with status 0.

Returns

bool

true when Status is 0.

SFTPClient

Returned by SFTP()

A high-level SFTP client session over an SSH connection. Obtained via SFTP().

sftp.Read()

Read(ctx, path)

Read a file into memory

Returns

([]byte, error)

sftp.Write()

Write(ctx, path, data)

Write a file, creating or truncating it

Returns

error

sftp.Mkdir()

Mkdir(ctx, path)

Create a directory

Returns

error

sftp.RemoveFile()

RemoveFile(ctx, path)

Remove a file

Returns

error

sftp.RemoveDir()

RemoveDir(ctx, path)

Remove an empty directory

Returns

error

sftp.Rename()

Rename(ctx, oldPath, newPath)

Rename a file or directory

Returns

error

sftp.RealPath()

RealPath(ctx, path)

Resolve a path to its canonical absolute form

Returns

(string, error)

sftp.ReadLink()

ReadLink(ctx, path)

Read a symlink target

Returns

(string, error)

sftp.Symlink()

Symlink(ctx, target, linkPath)

Create a symlink

Returns

error

sftp.Close()

Close(ctx)

Close the session (consumes the handle)

Returns

error

Types

SSHClientOption

Used by OpenClient()

Functional option for OpenClient(). Defaults: user root, terminal from $TERM (falling back to xterm), SFTP enabled, and the global SSH inactivity timeout.

Option	Description
WithSSHUser(user)	SSH login user. Default `root`
WithSSHTerm(term)	Terminal name for interactive sessions
WithSSHClientSFTP(enabled)	Enable or disable SFTP on the internal server. Default `true`
WithSSHClientInactivityTimeout(timeout)	Override the internal server inactivity timeout. A zero duration disables it

SSHExecOption

Used by Exec()

Functional option for Exec().

Option	Description
WithSSHTTY(enabled)	Request a PTY for the exec channel

SSHAttachOption

Used by Attach()

Functional option for Attach(). The default terminal comes from $TERM (falling back to xterm); detach keys default to the standard sequence.

Option	Description
WithSSHAttachTerm(term)	Terminal name for the interactive shell
WithSSHDetachKeys(keys)	Detach key sequence

SSHServerOption

Used by PrepareServer()

Functional option for PrepareServer(). SFTP is enabled by default, the inactivity timeout inherits the global SSH setting, and the default authorized-keys file is loaded when no path is provided.

Option	Description
WithSSHHostKeyPath(path)	Override the host private key path
WithSSHAuthorizedKeysPath(path)	Override the authorized-keys path
WithSSHServerUser(user)	Override the guest user used for SSH exec requests
WithSSHServerSFTP(enabled)	Enable or disable SFTP on the server endpoint. Default `true`
WithSSHServerInactivityTimeout(timeout)	Override the SSH inactivity timeout. A zero duration disables it

Getting Started

SDKs

CLI

Sandbox

sb.SSH()

SandboxSSHOps

ssh.OpenClient()

ssh.PrepareServer()

SSHClient

c.Exec()

c.Attach()

c.SFTP()

c.Close()

SSHServer

srv.ServeConnection()

srv.Close()

SSHOutput

o.Status

o.Stdout

o.Stderr

o.Success()

SFTPClient

sftp.Read()

sftp.Write()

sftp.Mkdir()

sftp.RemoveFile()

sftp.RemoveDir()

sftp.Rename()

sftp.RealPath()

sftp.ReadLink()

sftp.Symlink()

sftp.Close()

Types

SSHClientOption

SSHExecOption

SSHAttachOption

SSHServerOption

​Sandbox

​sb.SSH()

​SandboxSSHOps

​ssh.OpenClient()

​ssh.PrepareServer()

​SSHClient

​c.Exec()

​c.Attach()

​c.SFTP()

​c.Close()

​SSHServer

​srv.ServeConnection()

​srv.Close()

​SSHOutput

​o.Status

​o.Stdout

​o.Stderr

​o.Success()

​SFTPClient

​sftp.Read()

​sftp.Write()

​sftp.Mkdir()

​sftp.RemoveFile()

​sftp.RemoveDir()

​sftp.Rename()

​sftp.RealPath()

​sftp.ReadLink()

​sftp.Symlink()

​sftp.Close()

​Types

​SSHClientOption

​SSHExecOption

​SSHAttachOption

​SSHServerOption

Sandbox

sb.SSH()

SandboxSSHOps

ssh.OpenClient()

ssh.PrepareServer()

SSHClient

c.Exec()

c.Attach()

c.SFTP()

c.Close()

SSHServer

srv.ServeConnection()

srv.Close()

SSHOutput

o.Status

o.Stdout

o.Stderr

o.Success()

SFTPClient

sftp.Read()

sftp.Write()

sftp.Mkdir()

sftp.RemoveFile()

sftp.RemoveDir()

sftp.Rename()

sftp.RealPath()

sftp.ReadLink()

sftp.Symlink()

sftp.Close()

Types

SSHClientOption

SSHExecOption

SSHAttachOption

SSHServerOption