Skip to content

Commit 2019b42

Browse files
beran-tberan-t
authored
Add SSH access template documentation (#100)
* Add SSH access template documentation Adds a new template example showing how to enable SSH access to E2B sandboxes using websocat as a WebSocket-to-SSH proxy. This is a manual workaround while native SSH support is in development. Includes: - Template definition for SSH-ready sandbox - Quick start guide for CLI users - Connection methods (websocat and curl) - SSH config shortcut for easier access - SSH key authentication setup - SCP file transfer examples * Simplify template: inline start command instead of separate script * Split SSH docs into template example and sandbox guide * Remove curl alternative to simplify docs * Add quickstart section to SSH access docs * Add prose and comments to SSH template example * Clarify SSH credentials format * Add macOS and Linux tabs to quickstart * Switch from wget to curl for websocat download (handles GitHub redirects) * Fix SSH template: add sudo, root user for runCmd, and ssh-keygen at start time Tested and verified working: - Template builds successfully - SSH connection works with websocat proxy - Password authentication with user:sandbox credentials * Simplify SSH template: use Ubuntu 25.04 with built-in SSH support * Fix usage example: use same SSH command format as quickstart * Fix Python: use Sandbox.create() instead of Sandbox() * Simplify SSH docs: remove advanced sections, add user@ to examples * Consolidate SSH docs: merge template into main page, use Steps component - Remove separate ssh-ready template example page - Move template code into Quickstart using Mintlify Steps component - Add sandbox creation step with SDK examples - Fix title casing: "SSH Access" → "SSH access" - Remove warning callout and PTY note - Fix diagram alignment in E2B Sandbox section - Use CodeGroup instead of Tabs for OS-specific commands - Move overview text to page intro * Remove manual setup section from SSH docs
1 parent c1df0cc commit 2019b42

2 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@
9090
"docs/sandbox/connect",
9191
"docs/sandbox/internet-access",
9292
"docs/sandbox/pty",
93+
"docs/sandbox/ssh-access",
9394
"docs/sandbox/connect-bucket",
9495
"docs/sandbox/rate-limits",
9596
"docs/sandbox/secured-access",

‎docs/sandbox/ssh-access.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: "SSH access"
3+
description: "Connect to your sandbox via SSH using a WebSocket proxy"
4+
---
5+
6+
SSH access enables remote terminal sessions, SCP/SFTP file transfers, and integration with tools that expect SSH connectivity.
7+
8+
## Quickstart
9+
10+
<Steps>
11+
<Step title="Build the SSH template">
12+
13+
Define a template with OpenSSH server and [websocat](https://github.com/vi/websocat):
14+
15+
<CodeGroup>
16+
17+
```typescript JavaScript & TypeScript
18+
// template.ts
19+
import { Template, waitForPort } from 'e2b'
20+
21+
export const template = Template()
22+
.fromUbuntuImage('25.04')
23+
.aptInstall(['openssh-server'])
24+
.runCmd([
25+
'curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl',
26+
'chmod a+x /usr/local/bin/websocat',
27+
], { user: 'root' })
28+
.setStartCmd('sudo websocat -b --exit-on-eof ws-l:0.0.0.0:8081 tcp:127.0.0.1:22', waitForPort(8081))
29+
```
30+
31+
```python Python
32+
# template.py
33+
from e2b import Template, wait_for_port
34+
35+
template = (
36+
Template()
37+
.from_ubuntu_image("25.04")
38+
.apt_install(["openssh-server"])
39+
.run_cmd([
40+
"curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl",
41+
"chmod a+x /usr/local/bin/websocat",
42+
], user="root")
43+
.set_start_cmd("sudo websocat -b --exit-on-eof ws-l:0.0.0.0:8081 tcp:127.0.0.1:22", wait_for_port(8081))
44+
)
45+
```
46+
47+
</CodeGroup>
48+
49+
Build the template:
50+
51+
<CodeGroup>
52+
53+
```typescript JavaScript & TypeScript
54+
// build.ts
55+
import { Template, defaultBuildLogger } from 'e2b'
56+
import { template as sshTemplate } from './template'
57+
58+
await Template.build(sshTemplate, 'ssh-ready', {
59+
cpuCount: 2,
60+
memoryMB: 2048,
61+
onBuildLogs: defaultBuildLogger(),
62+
})
63+
```
64+
65+
```python Python
66+
# build.py
67+
from e2b import Template, default_build_logger
68+
from template import template as ssh_template
69+
70+
Template.build(ssh_template, "ssh-ready",
71+
cpu_count=2,
72+
memory_mb=2048,
73+
on_build_logs=default_build_logger(),
74+
)
75+
```
76+
77+
</CodeGroup>
78+
79+
</Step>
80+
<Step title="Create a sandbox from the template">
81+
82+
<CodeGroup>
83+
84+
```typescript JavaScript & TypeScript
85+
import { Sandbox } from 'e2b'
86+
87+
const sbx = await Sandbox.create('ssh-ready')
88+
console.log(sbx.sandboxId)
89+
```
90+
91+
```python Python
92+
from e2b import Sandbox
93+
94+
sbx = Sandbox.create("ssh-ready")
95+
print(sbx.sandbox_id)
96+
```
97+
98+
</CodeGroup>
99+
100+
</Step>
101+
<Step title="Connect from your machine">
102+
103+
<CodeGroup>
104+
105+
```bash macOS
106+
# Install websocat
107+
brew install websocat
108+
109+
# Connect to your sandbox
110+
ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.e2b.app' user@<sandbox-id>
111+
```
112+
113+
```bash Linux
114+
# Install websocat
115+
sudo curl -fsSL -o /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl
116+
sudo chmod a+x /usr/local/bin/websocat
117+
118+
# Connect to your sandbox
119+
ssh -o 'ProxyCommand=websocat --binary -B 65536 - wss://8081-%h.e2b.app' user@<sandbox-id>
120+
```
121+
122+
</CodeGroup>
123+
124+
</Step>
125+
</Steps>
126+
127+
---
128+
129+
## How it works
130+
131+
This method uses [websocat](https://github.com/vi/websocat) to proxy SSH connections over WebSocket through the sandbox's exposed ports.
132+
133+
```
134+
┌───────────────────────────────────────────────────────────┐
135+
│ Your Machine │
136+
│ ┌──────────┐ ProxyCommand ┌──────────────────┐ │
137+
│ │ SSH │ ────────────────── │ websocat │ │
138+
│ │ Client │ │ (WebSocket) │ │
139+
│ └──────────┘ └─────────┬────────┘ │
140+
└────────────────────────────────────────────┼──────────────┘
141+
│
142+
wss://8081-<sandbox-id>.e2b.app
143+
│
144+
┌────────────────────────────────────────────┼──────────────┐
145+
│ E2B Sandbox ▼ │
146+
│ ┌──────────────────┐ │
147+
│ │ websocat │ │
148+
│ │ (WS → TCP:22) │ │
149+
│ └─────────┬────────┘ │
150+
│ │ │
151+
│ ┌─────────▼────────┐ │
152+
│ │ SSH Server │ │
153+
│ │ (OpenSSH) │ │
154+
│ └──────────────────┘ │
155+
└───────────────────────────────────────────────────────────┘
156+
```

0 commit comments

Comments
 (0)