docs(tutorial): connect your local IDE to a Development Container

[ekline]

Context

This how-to guide addresses a gap identified through a tutorial/how-to coverage review that combined competitor analysis, persona-needs assessment, and a feature-coverage audit of the Okteto docs.

Top 3 gaps found

Rank	Priority	Gap	Source	Personas served	Proposed guide type
1	High	Connecting a local IDE (VS Code Remote-SSH / JetBrains Gateway) to a Development Container	Competitor pattern — Coder, Ona (ex-Gitpod), and Telepresence all teach IDE connection; Okteto documents it only as reference material (SSH Server), with no how-to	Developer	How-to guide
2	Medium	Running Okteto Test in CI with GitHub Actions	Competitor CI/CD pattern (Signadot, Ona, Coder, Qovery); Preview Environments have CI guides but Okteto Test has only a getting-started guide, no CI how-to	Developer, Administrator	How-to guide
3	Medium	Running a preferred AI coding agent (Cursor, Codex) in an Okteto environment beyond the Claude Code plugin	Dominant competitor pattern — 6 of 8 competitors document AI agents; Okteto's Agentic Workflows currently cover only the Claude Code plugin	Developer	How-to guide / Tutorial

What this PR adds

A how-to guide, Connect your local IDE to a Development Container, placed under Development Environments → Development Containers. It teaches developers to open a running Development Container in VS Code (Remote - SSH) or a JetBrains IDE (Gateway) over the SSH connection that okteto up already creates. The guide covers starting the container, the auto-generated ~/.ssh/config host entry and key pair, connecting each IDE, verifying the connection, and troubleshooting. It serves the developer persona (intermediate, working context).

The guide is grounded entirely in existing product behavior documented in the SSH Server reference — the SSH server injected by okteto up, the forwarded local port, the <name>.okteto host entry, the $HOME/.okteto/id_rsa_okteto key pair, and the dev.<svc>.remote manifest field for pinning the port.

Research sources

• Competitor analysis: Coder, Ona (ex-Gitpod), Qovery, Orca, Paseo, herdr, Signadot, Telepresence. "Connect to a local IDE / editor" recurs across Coder, Ona, and Telepresence — a pattern Okteto lacked a guide for.
• Persona needs: Developers integrating Okteto into their daily coding workflow expect to use their own IDE against the remote environment.
• Feature audit: IDE remote development was documented only in the SSH Server reference page, never as a task-oriented guide.

Remaining gaps (follow-up)

• Sample for working with npm link #2 — Running Okteto Test in CI with GitHub Actions. A how-to that mirrors the existing Preview Environments CI guides but for okteto test.
• document how to use a custom pipeline image #3 — Running a preferred AI coding agent (Cursor, Codex) in an Okteto environment. Broaden Agentic Workflows beyond the Claude Code plugin. Needs product grounding before writing.

How to verify

1. Run yarn build from docs/ to confirm no broken links or anchors.
2. Run yarn start and open the new page under Development Environments → Development Containers → Connect your IDE.
3. Optionally follow the guide against a live Okteto instance: run okteto up, confirm the ~/.ssh/config entry, and connect VS Code via Remote - SSH.

---

📝 Created with EkLine · View session

ekline[bot] <202747777+ekline[bot]@users.noreply.github.com>

[netlify]

✅ Deploy Preview for okteto-docs ready!

Name	Link
🔨 Latest commit	682baf3
🔍 Latest deploy log	https://app.netlify.com/projects/okteto-docs/deploys/6a6096ff0fcc43000811f040
😎 Deploy Preview	https://deploy-preview-1311--okteto-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rberrelleza]

interesting! we have an old blog post that covers something like this. do you think this is an scenario we want to showcase more @codyjlandstrom ?