Codespaces runtime

Active contributors: Jose Garcia, David Gardiner, Alan Donovan, Caleb Brose

Purpose

internal/codespaces/ is the system layer behind the gh codespace command. It contains the GitHub Codespaces API client, the Dev Tunnels connection manager, the local port-forwarding loop, and Live Share RPC clients for codespace control, filesystem operations, and Jupyter.

Directory layout

internal/codespaces/
  codespaces.go            # High-level orchestration: start, prep, ssh
  ssh.go                   # SSH session setup over a forwarded port
  states.go                # Codespace lifecycle states
  api/api.go               # ~38 KB: REST + GraphQL client targeting the codespaces service
  connection/              # Dev Tunnels connection management
  portforwarder/           # Local TCP listeners forwarding to the tunnel
  rpc/                     # Live Share RPC clients
    codespace/             # Codespace host service (start, stop, etc.)
    fs/                    # Filesystem ops (cp, mkdir, ...)
    jupyter/               # Jupyter session control
    ssh/                   # SSH server control inside the codespace

Key abstractions

Symbol	File	Role
API	api/api.go	REST + GraphQL client (codespaces, machines, secrets, repositories).
Codespace, Machine, RepositoryContents	api/api.go	Domain types.
connection.Manager	connection/	Establishes a Dev Tunnels connection.
portforwarder.Forwarder	portforwarder/	Manages local listeners that forward to the codespace.
rpc.Invoker and the per-service clients	rpc/	Live Share RPC for fine-grained control.
States	states.go	Codespace lifecycle constants and helpers.
Top-level helpers (Start, WaitUntilCodespaceConnection, MakeSSHSession)	codespaces.go	Orchestration used by gh cs ssh and gh cs ports.

How it works

graph TD
    A[gh cs ssh] --> B[App selects codespace]
    B --> C[api.GetCodespace]
    C -->|state=Available| D[connection.Manager creates Dev Tunnel]
    C -->|state=Shutdown| E[api.StartCodespace + poll]
    E --> D
    D --> F[portforwarder forwards 2222]
    F --> G[ssh client to localhost:2222]
    G --> H[user inside codespace]

The SSH path keeps the Dev Tunnel open for the duration of the session. Port forwarding is implemented as a net.Listener per port that copies bytes between the local socket and the tunnel.

The RPC layer is a generated stub plus a thin client. The codespace runs a Live Share host that exposes named services (codespace, fs, jupyter, ssh); the CLI invokes them after authenticating the connection.

Integration points

• Owned by @cli/codespaces per .github/CODEOWNERS.
• Pulls in microsoft/dev-tunnels, gorilla/websocket, creack/pty, kballard/go-shellquote, opentracing/opentracing-go. See reference/dependencies.md.
• Tests in pkg/cmd/codespace/ use the generated mock_api.go; tests in internal/codespaces/api/ mock at the HTTP layer using httpmock.

Entry points for modification

• New API call: add a method to api/api.go and a unit test using httpmock.
• New RPC method: extend the corresponding service in rpc/<service>/. Regenerate the generated message types if the proto changes.
• New port forwarding behaviour: portforwarder/portforwarder.go is the single hot spot; be careful with concurrency since it serves multiple goroutines per port.

Key source files

File	Purpose
internal/codespaces/codespaces.go	Orchestration.
internal/codespaces/api/api.go	API client (~38 KB).
internal/codespaces/connection/connection.go	Dev Tunnel client wrapper.
internal/codespaces/portforwarder/portforwarder.go	Listener loop.
internal/codespaces/rpc/codespace/codespace_host_service.v1.go	Codespace control RPC.
internal/codespaces/states.go	State enum.

Related pages

• Codespace command.