vscode

VS Code Remote-SSH onto a Sandbox

Operator-side workflow for connecting desktop VS Code into a sandbox over SSM + ssh. km generates a per-sandbox ed25519 keypair on the operator workstation, ships the public key via userdata, and writes an ~/.ssh/config Host entry that tunnels through aws ssm start-session.

Audience: the operator running km on their workstation. The sandbox just needs runtime.vscode.enabled: true in its profile (the default).

Cross-references

• klanker:init — must run km init --sidecars once before VS Code support works for new sandboxes
• klanker:user — km create, km list, km destroy lifecycle

Profile field

Field (under spec.runtime.vscode)	Type	Default	Purpose
enabled	bool*	true	Provision sshd + authorized_keys at sandbox boot. Set false to skip.

Phase 92 moved this field from spec.cli.vscodeEnabled to spec.runtime.vscode.enabled; the old path is rejected by km validate.

bool* = pointer-bool with profile-inheritance semantics; omit to use parent/default.

Operator state

Path	Purpose
~/.km/keys/<sandbox-id>	Private key (mode 0600) generated by km create
~/.km/keys/<sandbox-id>.pub	Public key (mode 0644) shipped via userdata
~/.ssh/config (managed block)	Host entries between # BEGIN km vscode hosts and # END km vscode hosts markers

One-time setup

1. Install the Remote - SSH extension in VS Code (Microsoft, free).
2. Make sure the platform's management Lambda has the latest km binary (which understands the VSCodeSSHPubKey userdata field):

make build
km init --sidecars

Without km init --sidecars, km create --remote against a runtime.vscode.enabled profile produces a sandbox with broken authorized_keys (silent SSH failure).

Per-sandbox workflow

# 1. Create — keypair is generated locally
km create profiles/<your-profile>.yaml --alias my-poc

# 2. Resolve the sandbox ID
SB=$(km list | awk '/my-poc/ {print $1}')

# 3. Open the SSM tunnel (blocks until Ctrl-C)
km vscode start $SB

# 4. In VS Code: F1 → "Remote-SSH: Connect to Host..." → km-$SB

# 5. (Optional) check sshd + authorized_keys state on the sandbox
km vscode status $SB

# 6. Teardown also cleans the local keypair + ssh-config block
km destroy $SB --remote --yes

km vscode start and km vscode status accept the same identifier formats as other km subcommands: full sandbox ID (lrn2-ee9499b5), alias (my-poc), or the row number from km list.

--local-port <N> overrides the default 2222 if it's already in use.

Rotating a sandbox key

km vscode rekey <sandbox-id> --yes

Generates a fresh ed25519 pair on the operator workstation, pushes the new public key to the sandbox's ~/.ssh/authorized_keys, and rewrites the local ~/.ssh/config block. Active VS Code sessions stay on the old key until reconnect.

Solves:

1. Baked-AMI relaunch carries stale authorized_keys from the bake-time sandbox.
2. Cross-laptop portability — km vscode rekey on a second laptop bootstraps a fresh key without manual file copy.
3. Post-incident rotation if a private key is suspected compromised.

Pre-flight gates (any failure = no key changes):

• EC2 instance must be running (not stopped / pending)
• km lock must not block (override with --force)
• Sandbox must have been created with runtime.vscode.enabled: true — sandboxes created without it get a clear hard error pointing at km destroy && km create

Operator notes

• Existing sandboxes provisioned without runtime.vscode.enabled: true do NOT get sshd retroactively. km destroy && km create to provision.
• Cross-machine portability: keys live on the creation machine only. Operators who want to km vscode start from a different laptop must run km vscode rekey there, OR manually copy ~/.km/keys/<sandbox-id>* from the original laptop.
• One operator per sandbox (single authorized_keys entry in v1).
• km destroy cleans up the local keypair files AND the ssh-config Host block. Manual cleanup is only needed when a sandbox is wiped out-of-band (region deleted, DynamoDB row removed, etc.).

See docs/vscode.md for the full operator guide and troubleshooting matrix.