box-ssh-bridge lets a normal SSH client use a
Simular Box cloud computer even though Box exposes
the official box rsh command API rather than a public SSH daemon.
It is a local SSH gateway written in Go. ShellRS, OpenSSH, SFTP clients, IDEs,
and automation tools can connect to a normal host:port while the bridge runs
@simular-ai/box rsh underneath.
This project is also useful if you are looking for:
- Simular Box SSH access
box rshSSH bridge or adapterbox rshProxyCommand alternative- ShellRS connection to Simular Box
- Simular Box SFTP or
/workspacefile access - InstaBox to Simular Box SSH tunnel
- SSH gateway for an AI cloud desktop
This is for box by Simular, not Box.com file storage.
中文简介:把 Simular Box 的
box rsh封装成标准 SSH/SFTP 入口, 支持 ShellRS,也可以部署在本机或 InstaBox 云主机上。适用于寻找 “Simular Box SSH”“box rsh 转 SSH”“ShellRS 连接 Simular Box”、 “Simular Box 文件传输”和“InstaBox SSH 隧道”的场景。
Cloud-first deployment: the bridge can run entirely on InstaBox, leaving the client with only ShellRS and the official
instabox port-forwardprocess. Read Deployment Field Notes for the tested topology, multi-account setup, SFTP path, auto-pause behavior, and recovery steps.
SSH / SFTP client
|
v
box-ssh-bridge
|
+-- terminal / exec --> box rsh --> Simular Box
|
+-- SFTP subsystem --> loopback-only SFTP --> /workspace
- Standard SSH password or public-key authentication.
- Interactive PTY sessions with terminal resizing.
- Non-interactive
ssh host command, with the remote exit code preserved. - Optional SSH
sftpsubsystem for the same SSH host. - Dedicated, loopback-only host key and client key.
- No fixed dependency on a control-plane vendor.
- Small Go binary; the only runtime dependency is the official
@simular-ai/boxCLI. - macOS
launchd, Linuxsystemd, and InstaBox deployment examples.
-
Go 1.24+ to build, or use a prebuilt release.
-
Node.js 18.17+ and the official Box CLI:
npx @simular-ai/box login npx @simular-ai/box rsh --box main -- uname -a
If the second command does not work, the bridge cannot work. Fix the Box login or Box network path first.
git clone https://github.com/zengjunzhe/box-ssh-bridge.git
cd box-ssh-bridge
go build -o box-ssh-bridge ./cmd/box-ssh-bridgeGenerate a dedicated client key:
mkdir -p "$HOME/Library/Application Support/box-ssh-bridge"
ssh-keygen -q -t ed25519 -N '' -C box-ssh-bridge \
-f "$HOME/Library/Application Support/box-ssh-bridge/client_ed25519"
cp "$HOME/Library/Application Support/box-ssh-bridge/client_ed25519.pub" \
"$HOME/Library/Application Support/box-ssh-bridge/authorized_keys"Start the bridge:
./box-ssh-bridge \
--listen 127.0.0.1:22220 \
--box main \
--authorized-key "$HOME/Library/Application Support/box-ssh-bridge/authorized_keys"Connect:
ssh -i "$HOME/Library/Application Support/box-ssh-bridge/client_ed25519" \
-p 22220 user@127.0.0.1Without --authorized-key, the bridge generates a random password and prints
it once:
./box-ssh-bridge --password "$(openssl rand -base64 24)"The included launchd installer creates a dedicated key and keeps the bridge running across logins:
./scripts/install-launchd.shTest:
ssh -i "$HOME/Library/Application Support/box-ssh-bridge/client_ed25519" \
-p 22220 user@127.0.0.1 'whoami; pwd; hostname'Stop:
launchctl bootout "gui/$(id -u)/com.zengjunzhe.box-ssh-bridge"Create a normal SSH host:
| Field | Value |
|---|---|
| Name | Simular Box main |
| Address | 127.0.0.1 |
| Port | 22220 |
| User | user |
| Authentication | Private key client_ed25519 |
Open the host. For SFTP, enable the Files sidebar after the host is connected.
The SFTP path is the path in the Simular Box, normally /workspace or
/home/user.
One bridge process can route several Simular Boxes. Create a users.json
map from SSH usernames to Box names or IDs:
{
"work": "box-work",
"personal": "box-personal",
"main": "main"
}If the Boxes belong to different Simular accounts, use an object per user and give each account its own Box CLI home:
{
"work": {
"box": "main",
"boxHome": "/Users/me/.simular-box-work"
},
"personal": {
"box": "main",
"boxHome": "/Users/me/.simular-box-personal"
}
}The bridge sets BOX_HOME for that session only. Log in once with the same
value:
BOX_HOME="$HOME/.simular-box-work" npx @simular-ai/box loginStart with:
./box-ssh-bridge \
--listen 127.0.0.1:22220 \
--users-file "$HOME/Library/Application Support/box-ssh-bridge/users.json" \
--authorized-key "$HOME/Library/Application Support/box-ssh-bridge/authorized_keys"Each SSH username selects its own Box:
ssh -i box-bridge-key -p 22220 work@127.0.0.1
ssh -i box-bridge-key -p 22220 personal@127.0.0.1In ShellRS, create one host per Box, using the same address and port but a
different username. For SFTP, include {box} in --sftp-command; it is
replaced per SSH session:
--sftp-command "/path/to/box-sftp.sh {box}"
Without --users-file, the original single-Box --box and --user behavior
is unchanged.
The bridge can run on an InstaBox cloud machine and reach Simular Box from there. The tested topology is:
ShellRS / OpenSSH / SFTP
|
| InstaBox port-forward (official CLI)
v
InstaBox: box-ssh-bridge
|
| box rsh
v
Simular Box /workspace
Build a Linux binary and copy it to the machine:
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
go build -trimpath -o /tmp/box-ssh-bridge ./cmd/box-ssh-bridge
scp /tmp/box-ssh-bridge ins:/tmp/box-ssh-bridge
ssh ins 'mkdir -p ~/box-ssh-bridge && \
install -m 0755 /tmp/box-ssh-bridge ~/box-ssh-bridge/box-ssh-bridge'Log the Box CLI in on InstaBox. Its credential is separate from the credential on your laptop:
ssh -t ins 'npx --yes @simular-ai/box login'
ssh ins 'npx --yes @simular-ai/box rsh --box main -- uname -a'Create a client key on InstaBox:
ssh ins '
cd ~/box-ssh-bridge
test -f user_ed25519 || ssh-keygen -q -t ed25519 -N "" -C box-ssh-bridge -f user_ed25519
cp user_ed25519.pub authorized_keys
chmod 600 user_ed25519
'Run as a systemd service:
[Unit]
Description=box-ssh-bridge
After=network-online.target
Wants=network-online.target
[Service]
User=user
Group=user
Environment=HOME=/data/home
Environment=PATH=/usr/local/bin:/usr/bin:/bin
WorkingDirectory=/data/home/box-ssh-bridge
ExecStart=/data/home/box-ssh-bridge/box-ssh-bridge \
--listen 127.0.0.1:22221 \
--box main \
--user user \
--state-dir /data/home/box-ssh-bridge/state \
--authorized-key /data/home/box-ssh-bridge/authorized_keys \
--box-cli /usr/local/bin/npx \
--box-package @simular-ai/box \
--sftp-command /data/home/box-ssh-bridge/sftp-command.sh
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetKeep the bridge on 127.0.0.1; do not expose it directly to the internet.
InstaBox's server currently does not enable raw public TCP ports. Use its official private forwarding:
instabox port-forward <machine-id> 22223:22221Then the SSH endpoint on your laptop is:
127.0.0.1:22223
Test:
ssh -i instabox-client_ed25519 -p 22223 \
user@127.0.0.1 'whoami; pwd; hostname'scripts/install-instabox-forward.sh
turns this into a macOS launchd service.
InstaBox can pause itself when idle:
- On the free plan, idle pause is fixed at 30 minutes.
- The current machine has a 240-minute maximum run.
- A self-paused machine wakes when SSH traffic or
port-forwardreconnects. - Memory and processes are preserved while paused.
- A maximum-run pause has a cooldown; free-plan cooldowns can become long after repeated max-run pauses.
- While paused, open SSH and SFTP sessions disconnect. Reconnect after the machine wakes.
The launchd wrapper retries instabox port-forward every five seconds. The
reconnect itself wakes an idle-paused InstaBox. Paid plans can set
instabox auto-suspend <machine> 0 to disable idle pause. For a long silent
task, hold an InstaBox activity lease rather than polling in the background.
Cloud Box needs a loopback-only OpenSSH server because the bridge only has the
box rsh command channel, not arbitrary TCP. This is the one case where the
project installs a package inside the Box:
# Run inside Simular Box, as the normal user
sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-serverUse a dedicated host key and a dedicated client key, and bind only to
127.0.0.1. A minimal sshd_config is:
Port 22222
ListenAddress 127.0.0.1
HostKey /home/user/.ssh/box_bridge_host_ed25519
AuthorizedKeysFile /home/user/.ssh/box_bridge_authorized_keys
PasswordAuthentication no
PubkeyAuthentication yes
UsePAM no
StrictModes no
Subsystem sftp internal-sftp
PidFile /home/user/.ssh/box_bridge_sshd.pid
Start it as a user service, not a public service:
systemctl --user enable --now box-bridge-sftpVerify from inside the Box:
printf 'pwd\nls /workspace\n' | sftp -b - \
-i ~/.ssh/box_bridge_client_ed25519 \
-P 22222 -o StrictHostKeyChecking=no user@127.0.0.1On InstaBox, create the SFTP wrapper:
#!/bin/sh
exec /usr/local/bin/npx --yes @simular-ai/box rsh --box main -- \
ssh -T -s -p 22222 \
-i /home/user/.ssh/box_bridge_client_ed25519 \
-o StrictHostKeyChecking=no -o BatchMode=yes \
user@127.0.0.1 sftpThen pass it with --sftp-command. The same SSH host used for the terminal
now also serves the SFTP subsystem. The file tree belongs to Simular Box, not
InstaBox.
box-ssh-bridge [flags]
--listen string local SSH listen address (default "127.0.0.1:22220")
--box string Simular Box name or ID (default "main")
--user string SSH username (default "user")
--users-file string JSON map of SSH usernames to Box names or IDs
--password string SSH password
--authorized-key string authorized_keys file
--host-key string SSH host key path
--box-cli string path to the simular-box CLI entrypoint
--box-package string package used when --box-cli is npx
--sftp-command string local command that serves the SFTP subsystem
--state-dir string state directory
--version print version
State defaults to the OS user configuration directory under box-ssh-bridge;
override it with --state-dir or BOX_SSH_BRIDGE_HOME.
- Keep the bridge listener on loopback.
- Use public-key authentication for unattended deployments.
- Keep Box credentials on the machine that runs
box rsh; never commit them. - Keep the Cloud Box SFTP daemon on
127.0.0.1. - Do not publish the bridge as a raw TCP port without an additional access layer.
- The bridge is an SSH gateway to
box rsh; it is not a full hidden SSH daemon inside Box. - X11 forwarding, agent forwarding, and TCP port forwarding are not implemented.
- SFTP requires the optional loopback-only SFTP backend described above.
- Multiple Boxes can share one listener; each needs its own SSH username and
users.jsonentry. - A shell session starts
bash -liinside/workspace.
go test ./...
go vet ./...
go build ./cmd/box-ssh-bridgeThe integration boundary is tested with an SSH client against a fake Box CLI in
internal/bridge.
MIT