---
title: "Connect an authenticated SSH stream to the current workspace session"
method: GET
path: "/v1/research-workspaces/{id}/ssh-stream"
tags: ["Research workspaces"]
---

# Connect an authenticated SSH stream to the current workspace session

`GET /v1/research-workspaces/{id}/ssh-stream`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/research-workspaces/{id}/ssh-stream`
- Auth: HTTP bearer

Upgrades an authenticated request to a WebSocket using nodus-workspace-ssh-v1. Binary messages carry the SSH byte stream. Use the session and generation from a fresh SSH connection response. Query strings, Origin and Cookie headers are rejected. Authorization must contain one current Bearer credential. Nodus checks workspace ownership and the pinned session before connecting and while forwarding. The guest still authenticates the customer's SSH public key. Either side closing or authorization expiry closes the stream. The CLI proxy opens this endpoint without a browser or credential in its command line.

## Path parameters

- `id` string, required

## Headers

- `X-Nodus-Workspace-Session` string, required
- `X-Nodus-Workspace-Generation` string, required
- `Sec-WebSocket-Protocol` 'nodus-workspace-ssh-v1', required

## Response `default`

400 invalid_ssh_connection for an invalid handshake identity. 409 workspace_not_ready for a stale or unavailable session. 503 ssh_unavailable when the stream or guest is unavailable. Authentication and rate limits also apply.

- SandboxError
  - `code` string, required
  - `message` string, required
  - `fix` string, required
  - `url` string, uri, required

## Other responses

- `101`: Authenticated binary SSH stream. The standard WebSocket handshake headers apply.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)