molecule-core/docs/tutorials/ec2-instance-connect-ssh/index.md

SSH into Cloud Agent Workspaces via EC2 Instance Connect

EC2 Instance Connect Endpoint lets you open a shell in a CP-provisioned workspace — no SSH keys, no IP hunting, no security group configuration. The platform handles the EIC call under the hood; you just click Terminal.

SSH access to a cloud agent workspace sounds like it should be simple. The instance exists in your AWS account, you have the instance_id — surely there's a direct path. There isn't, by default. Instance IPs change on restart, security groups need per-account rules, and long-lived SSH keys are a provenance problem the moment more than one person needs access.

AWS EC2 Instance Connect (EIC) Endpoint solves all of this. Instead of managing keys yourself, you delegate to AWS — the platform calls aws ec2-instance-connect ssh on your behalf, AWS pushes a short-lived key through the EIC Endpoint, and a PTY bridges straight into the Canvas Terminal tab. The access is attributable (EIC logs which principal opened the tunnel), temporary (key expires automatically), and requires no inbound security group rules (the tunnel opens outbound from the instance).

Prerequisites: CP-managed workspace in your AWS account (provisioned with controlplane backend and MOLECULE_ORG_ID set). Your IAM role must have ec2-instance-connect:SendSSHPublicKey + ec2-instance-connect:OpenTunnel (condition Role=workspace). An EIC Endpoint must exist in the workspace VPC. See docs/infra/workspace-terminal.md for the one-time infra setup.

How it works

Canvas (browser) ──WebSocket──► Platform (Go)
                                 │
                                 ▼ spawns
                     aws ec2-instance-connect ssh \
                       --connection-type eice \
                       --instance-id <instance_id> \
                       --os-user ec2-user \
                       -- docker exec -it <container_id> /bin/bash
                                 │
                                 ▼
                  EIC Endpoint ──► EC2 Instance (PTY bridge)

The platform stores the instance_id returned by AWS during provisioning (PR #1531). When you click Terminal, the Go handler looks up the instance, calls aws ec2-instance-connect ssh, and bridges the PTY to the Canvas WebSocket.

Run it

# 1. Create a CP-managed workspace (requires controlplane backend + MOLECULE_ORG_ID)
WS=$(curl -s -X POST https://acme.moleculesai.app/workspaces \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-agent", "runtime": "hermes", "tier": 2}' \
  | jq -r '.id')

# 2. Wait for it to be running (~20-40s)
until curl -s https://acme.moleculesai.app/workspaces/$WS \
  | jq -r '.status' | grep -q ready; do sleep 5; done
echo "Workspace $WS is ready"

# 3. In Canvas: open the workspace → Terminal tab
#    The platform calls EIC on your behalf and opens a shell.
#    No SSH keys, no IP lookup — it just works.

# 4. Verify the PTY works by running a command
whoami          # should return: root (inside the container)
df -h /         # disk usage inside the workspace container
echo $MOLECULE_WS_ID  # confirm you're in the right workspace

# 5. Inspect the EIC tunnel via CloudWatch (AWS console)
#    Filter: eventName=OpenTunnel, eventSource=ec2-instance-connect
#    Principal: your IAM role ARN
#    Target: the instance_id of the workspace

What you need on the AWS side

Requirement	Details
IAM policy	ec2-instance-connect:SendSSHPublicKey + ec2-instance-connect:OpenTunnel on * with condition aws:ResourceTag/Role=workspace
EIC Endpoint	One per workspace VPC, reachable from the platform
AWS CLI	aws-cli + openssh-client installed in the tenant image (alpine: apk add openssh-client aws-cli)
Instance	Must be Nitro-based (T3, M5, C5, etc. — virtually all modern instance types)

Design notes

• The EIC call is a subprocess (aws ec2-instance-connect ssh) rather than a native SDK call. EIC Endpoint uses a signed WebSocket with specific framing that aws-cli v2 implements correctly. Reimplementing it in Go is ~500 lines of crypto + protocol work.
• sshCommandFactory is a var (injectable) so tests can stub the command without spawning real aws-cli processes.
• Context cancellation is bidirectional: WS close kills the SSH process; SSH exit closes the WebSocket cleanly.
• If Terminal shows "EIC wiring incomplete," the EIC Endpoint or IAM policy isn't set up yet — see docs/infra/workspace-terminal.md.

Teardown

Close the Terminal tab in Canvas, or the process exits automatically when the browser disconnects. No manual teardown needed.

EC2 Instance Connect SSH shipped in PRs #1531 + #1533. For the social launch copy, see docs/marketing/social/2026-04-22-ec2-instance-connect-ssh/.