SSH access

AgentBox does not provide a separate SSH method. If you need an interactive SSH client, create a reusable template that runs OpenSSH behind a WebSocket bridge.

Prepare an Ed25519 key pair. JavaScript and Python use the system ssh client and websocat, reading ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub by default. Go uses golang.org/x/crypto/ssh and github.com/coder/websocket; pass the key paths to runSSH.

mjs

import { readFile as readSshPublicKey } from "node:fs/promises";
import { homedir as homeDirectory } from "node:os";
import pathForSsh from "node:path";
import { spawnSync as runSsh } from "node:child_process";

import { Sandbox, Template, waitForPort } from "@abox-dev/sdk";

const templateName = process.env.TEMPLATE_NAME ?? "ssh-ready";
const sshTemplate = Template()
  .fromTemplate("base")
  .aptInstall(["openssh-server", "curl"])
  .runCmd(
    "case $(uname -m) in " +
      "x86_64) asset=websocat.x86_64-unknown-linux-musl ;; " +
      "aarch64|arm64) asset=websocat.aarch64-unknown-linux-musl ;; " +
      "*) exit 1 ;; esac && " +
      "curl -fsSL -o /usr/local/bin/websocat " +
      '"https://github.com/vi/websocat/releases/download/v1.14.1/$asset" && ' +
      "chmod 755 /usr/local/bin/websocat",
    { user: "root" },
  )
  .setStartCmd(
    "sudo mkdir -p /run/sshd && " +
      "sudo ssh-keygen -A && " +
      "sudo /usr/sbin/sshd -E /tmp/sshd.log && " +
      "sudo /usr/local/bin/websocat -b --exit-on-eof " +
      "ws-l:0.0.0.0:8081 tcp:127.0.0.1:22",
    waitForPort(8081),
  );

await Template.build(sshTemplate, templateName);

const publicKeyPath =
  process.env.AGENTBOX_SSH_PUBLIC_KEY ??
  pathForSsh.join(homeDirectory(), ".ssh/id_ed25519.pub");
const privateKeyPath =
  process.env.AGENTBOX_SSH_PRIVATE_KEY ??
  pathForSsh.join(homeDirectory(), ".ssh/id_ed25519");
const publicKey = (await readSshPublicKey(publicKeyPath, "utf8")).trim();

const sandbox = await Sandbox.create(templateName, {
  network: { allowPublicTraffic: false },
});

try {
  await sandbox.commands.run(
    "sudo install -d -m 700 -o user -g user /home/user/.ssh && " +
      "printf '%s\\n' \"$SSH_PUBLIC_KEY\" | " +
      "sudo tee /home/user/.ssh/authorized_keys >/dev/null && " +
      "sudo chown user:user /home/user/.ssh/authorized_keys && " +
      "sudo chmod 600 /home/user/.ssh/authorized_keys",
    { envs: { SSH_PUBLIC_KEY: publicKey } },
  );

  const proxyCommand = process.env.AGENTBOX_SSH_PROXY_COMMAND?.replaceAll(
    "__SANDBOX_ID__",
    sandbox.sandboxId,
  ).replaceAll("__TRAFFIC_TOKEN__", sandbox.trafficAccessToken ?? "");
  const connection = runSsh(
    "ssh",
    [
      "-i",
      privateKeyPath,
      "-o",
      "IdentitiesOnly=yes",
      "-o",
      "StrictHostKeyChecking=accept-new",
      "-o",
      `ProxyCommand=${
        proxyCommand ??
        `websocat --binary -B 65536 ` +
          `-H="Agentbox-Traffic-Access-Token: ${sandbox.trafficAccessToken}" ` +
          `wss://8081-${sandbox.sandboxId}.agentbox-runtime.ru`
      }`,
      `user@${sandbox.sandboxId}`,
      "printf 'SSH connection works'",
    ],
    {
      encoding: "utf8",
      env: process.env,
    },
  );
  if (connection.status !== 0) throw new Error(connection.stderr);
  console.log(connection.stdout);
} finally {
  await sandbox.kill();
}

import os
import subprocess
from pathlib import Path

from agentbox import Sandbox, Template, wait_for_port


template_name = os.getenv("TEMPLATE_NAME", "ssh-ready")
ssh_template = (
    Template()
    .from_template("base")
    .apt_install(["openssh-server", "curl"])
    .run_cmd(
        "case $(uname -m) in "
        "x86_64) asset=websocat.x86_64-unknown-linux-musl ;; "
        "aarch64|arm64) asset=websocat.aarch64-unknown-linux-musl ;; "
        "*) exit 1 ;; esac && "
        "curl -fsSL -o /usr/local/bin/websocat "
        '"https://github.com/vi/websocat/releases/download/v1.14.1/$asset" && '
        "chmod 755 /usr/local/bin/websocat",
        user="root",
    )
    .set_start_cmd(
        "sudo mkdir -p /run/sshd && "
        "sudo ssh-keygen -A && "
        "sudo /usr/sbin/sshd -E /tmp/sshd.log && "
        "sudo /usr/local/bin/websocat -b --exit-on-eof "
        "ws-l:0.0.0.0:8081 tcp:127.0.0.1:22",
        wait_for_port(8081),
    )
)

Template.build(ssh_template, template_name)

public_key_path = Path(
    os.getenv("AGENTBOX_SSH_PUBLIC_KEY", Path.home() / ".ssh/id_ed25519.pub")
)
private_key_path = Path(
    os.getenv("AGENTBOX_SSH_PRIVATE_KEY", Path.home() / ".ssh/id_ed25519")
)
public_key = public_key_path.read_text().strip()

sandbox = Sandbox.create(
    template_name,
    network={"allow_public_traffic": False},
)

try:
    sandbox.commands.run(
        "sudo install -d -m 700 -o user -g user /home/user/.ssh && "
        "printf '%s\\n' \"$SSH_PUBLIC_KEY\" | "
        "sudo tee /home/user/.ssh/authorized_keys >/dev/null && "
        "sudo chown user:user /home/user/.ssh/authorized_keys && "
        "sudo chmod 600 /home/user/.ssh/authorized_keys",
        envs={"SSH_PUBLIC_KEY": public_key},
    )

    proxy_command = os.getenv("AGENTBOX_SSH_PROXY_COMMAND", "")
    if proxy_command:
        proxy_command = proxy_command.replace("__SANDBOX_ID__", sandbox.sandbox_id)
        proxy_command = proxy_command.replace(
            "__TRAFFIC_TOKEN__", sandbox.traffic_access_token or ""
        )
    if not proxy_command:
        proxy_command = (
            "websocat --binary -B 65536 "
            f'-H="Agentbox-Traffic-Access-Token: {sandbox.traffic_access_token}" '
            f"wss://8081-{sandbox.sandbox_id}.agentbox-runtime.ru"
        )

    connection = subprocess.run(
        [
            "ssh",
            "-i",
            private_key_path,
            "-o",
            "IdentitiesOnly=yes",
            "-o",
            "StrictHostKeyChecking=accept-new",
            "-o",
            f"ProxyCommand={proxy_command}",
            f"user@{sandbox.sandbox_id}",
            "printf 'SSH connection works'",
        ],
        check=True,
        capture_output=True,
        text=True,
        env=os.environ,
    )
    print(connection.stdout)
finally:
    sandbox.kill()

// The SDK authenticates the WebSocket upgrade without exposing access tokens.
type sandboxHTTPTransport struct{ sandbox *agentbox.Sandbox }

func (transport sandboxHTTPTransport) RoundTrip(request *http.Request) (*http.Response, error) {
	return transport.sandbox.RequestWithOptions(request.Context(), 8081,
		request.Method, request.URL.RequestURI(), request.Body,
		&agentbox.SandboxRequestOptions{Headers: request.Header})
}

func runSSH(ctx context.Context, templateName, privateKeyPath, publicKeyPath string) error {
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	builder := agentbox.NewTemplate("").
		FromTemplate("base").
		AptInstall(agentbox.AptInstallOptions{}, "openssh-server", "curl").
		RunAs("root", "case $(uname -m) in "+
			"x86_64) asset=websocat.x86_64-unknown-linux-musl ;; "+
			"aarch64|arm64) asset=websocat.aarch64-unknown-linux-musl ;; "+
			"*) exit 1 ;; esac && "+
			"curl -fsSL -o /usr/local/bin/websocat "+
			"\"https://github.com/vi/websocat/releases/download/v1.14.1/$asset\" && "+
			"chmod 755 /usr/local/bin/websocat").
		Start("sudo mkdir -p /run/sshd && sudo ssh-keygen -A && "+
			"sudo /usr/sbin/sshd -E /tmp/sshd.log && "+
			"sudo /usr/local/bin/websocat -b --exit-on-eof "+
			"ws-l:0.0.0.0:8081 tcp:127.0.0.1:22", agentbox.WaitForPort(8081))
	if _, err := client.Templates.Build(ctx, builder, templateName, nil); err != nil {
		return err
	}
	publicKey, err := os.ReadFile(publicKeyPath)
	if err != nil {
		return err
	}
	privateKey, err := os.ReadFile(privateKeyPath)
	if err != nil {
		return err
	}
	signer, err := ssh.ParsePrivateKey(privateKey)
	if err != nil {
		return err
	}
	allowPublic := false
	secure := true
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{
		Template: templateName,
		Secure:   &secure,
		Network:  &agentbox.SandboxNetworkConfig{AllowPublicTraffic: &allowPublic},
	})
	if err != nil {
		return err
	}
	defer sandbox.Kill(context.Background())
	if _, err := sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{
		Args: []string{
			"-lc",
			"sudo install -d -m 700 -o user -g user /home/user/.ssh && " +
				"printf '%s\\n' \"$SSH_PUBLIC_KEY\" | sudo tee /home/user/.ssh/authorized_keys >/dev/null && " +
				"sudo chown user:user /home/user/.ssh/authorized_keys && sudo chmod 600 /home/user/.ssh/authorized_keys",
		},
		Env: map[string]string{"SSH_PUBLIC_KEY": strings.TrimSpace(string(publicKey))},
	}); err != nil {
		return err
	}

	// Pin the server key obtained through the authenticated SDK connection.
	hostKeyText, err := sandbox.Files.ReadText(ctx, "/etc/ssh/ssh_host_ed25519_key.pub", nil)
	if err != nil {
		return err
	}
	hostKey, _, _, _, err := ssh.ParseAuthorizedKey([]byte(hostKeyText))
	if err != nil {
		return err
	}
	webSocket, _, err := websocket.Dial(ctx, "wss://"+sandbox.Host(8081), &websocket.DialOptions{
		HTTPClient: &http.Client{Transport: sandboxHTTPTransport{sandbox: sandbox}},
	})
	if err != nil {
		return err
	}
	defer webSocket.CloseNow()
	connection := websocket.NetConn(ctx, webSocket, websocket.MessageBinary)
	sshConnection, channels, requests, err := ssh.NewClientConn(connection, sandbox.Host(8081), &ssh.ClientConfig{
		User:              "user",
		Auth:              []ssh.AuthMethod{ssh.PublicKeys(signer)},
		HostKeyCallback:   ssh.FixedHostKey(hostKey),
		HostKeyAlgorithms: []string{hostKey.Type()},
	})
	if err != nil {
		return err
	}
	sshClient := ssh.NewClient(sshConnection, channels, requests)
	defer sshClient.Close()
	session, err := sshClient.NewSession()
	if err != nil {
		return err
	}
	defer session.Close()
	output, err := session.CombinedOutput("printf 'SSH connection works'")
	if err != nil {
		return err
	}
	fmt.Print(string(output))
	return nil
}

The template is built once and can be reused by later sandboxes. Each sandbox receives only the public key. Its WebSocket port is private. JavaScript/Python pass the traffic token to websocat without printing it; Go authenticates the WebSocket upgrade through Sandbox.RequestWithOptions and pins the SSH host key obtained through the authenticated SDK connection. For an interactive shell, connect the SSH session's input and output to your terminal instead of executing the final remote command.

Treat the private key and traffic token as secrets. Do not add them to a template, repository, sandbox metadata, or command output.

SSH access ​

SSH access