| name | vscode |
| description | Connect local desktop VS Code to a sandbox via SSM port-forward + per-sandbox ed25519 keypair; rotate keys without destroying the sandbox |
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 vscodeEnabled: 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.cli) | Type | Default | Purpose |
|---|
vscodeEnabled | bool* | true | Provision sshd + authorized_keys at sandbox boot. Set false to skip. |
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
- Install the Remote - SSH extension in VS Code (Microsoft, free).
- 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 vscodeEnabled profile produces a sandbox with broken authorized_keys (silent SSH failure).
Per-sandbox workflow
km create profiles/<your-profile>.yaml --alias my-poc
SB=$(km list | awk '/my-poc/ {print $1}')
km vscode start $SB
km vscode status $SB
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:
- Baked-AMI relaunch carries stale
authorized_keys from the bake-time sandbox.
- Cross-laptop portability —
km vscode rekey on a second laptop bootstraps a fresh key without manual file copy.
- 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
vscodeEnabled: true — pre-vscodeEnabled sandboxes get a clear hard error pointing at km destroy && km create
Operator notes
- Existing sandboxes provisioned without
vscodeEnabled: 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.