---
title: "Open a ready browser tool or get desktop SSH configuration"
method: POST
path: "/v1/research-workspaces/{id}/connections"
tags: ["Research workspaces"]
---

# Open a ready browser tool or get desktop SSH configuration

`POST /v1/research-workspaces/{id}/connections`

## Request

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

Requires a current authorized compute session with reachable, healthy tools. editor and notebook return a one-time HTTPS URL. ssh requires a saved SSH public key and returns OpenSSH configuration, using either the authenticated HTTPS proxy command or a direct gateway with a known_hosts entry. Browser tools use isolated per-tool origins, not the API or console origin. Account credentials never reach the guest. Revocation, session replacement or expired authorization closes access, including active browser streams. Closing a client does not stop compute.

## Path parameters

- `id` string, required

## Request body

- ResearchWorkspaceConnectionRequest
  - `tool` 'editor' | 'notebook' | 'ssh', required

## Response `200`

One-time browser connection URL or desktop SSH configuration, depending on tool

- union
  - ResearchWorkspaceBrowserConnection
    - `url` string, uri, required: HTTPS tool URL containing a one-time grant in its fragment. Open within one minute. Redemption creates a host-only secure browser session lasting at most one hour, subject to ongoing authorization. Treat this URL as a secret. Request another connection if it expires or has already been used.
  - ResearchWorkspaceSSHConnection
    - `host` string, required: SSH configuration alias to open in a local SSH client or VS Code Remote SSH.
    - `alias` string, required: Same as host. Derived from the workspace name, or nodus- followed by the workspace id.
    - `user` 'nodus', required
    - `command` string, required: One-line ssh command that works without the configuration block. It names the workspace and contains no credential.
    - `ssh_config` string, required: OpenSSH configuration using the workspace gateway as ProxyJump. Requires the private key corresponding to the saved public key. Do not disable host-key checking.
    - `gateway_fingerprint` string, required: SHA256 fingerprint of the deployment's stable SSH gateway host key.
    - `gateway_known_hosts` string, required: OpenSSH known_hosts entry for the gateway, to install before connecting. The guest has a separate project-persisted host key and first-use confirmation.
  - WorkspaceWebSocketSSHConnection
    - `host` string, required: OpenSSH configuration alias to open from a terminal or VS Code Remote SSH.
    - `alias` string, required: Same as host. Derived from the workspace name, or nodus- followed by the workspace id.
    - `user` 'nodus', required
    - `command` string, required: One-line ssh command using nodus workspaces ssh-proxy. It names the workspace and contains no credential.
    - `requires` 'nodus-cli', required: Local tool the command runs.
    - `ssh_config` string, required: OpenSSH configuration using nodus workspaces ssh-proxy as ProxyCommand. The command reads the existing Nodus sign-in and contains no credential. The matching SSH private key is still required. Confirm the project host key on first use.
    - `transport` 'websocket', required
    - `workspace_id` string, required
    - `session_id` string, required
    - `generation` integer, required

## Other responses

- `default`: 400 for an invalid tool. 404 for a workspace not owned by this account. 409 workspace_not_ready until the session and tools are ready. 503 if browser access or SSH configuration is unavailable. Authentication, rate limits and transient failures also apply.

## Changes

- **2026-10-01** `ba84c74aeec8`: 7 info
  - added the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/alias` to the response with the `200` status
  - added the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/command` to the response with the `200` status
  - added the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/user` to the response with the `200` status
  - added the required property `oneOf[#/components/schemas/WorkspaceWebSocketSSHConnection]/alias` to the response with the `200` status
  - …3 more
- **2026-10-01** `544fef290a54`: 7 breaking
  - removed the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/alias` from the response with the `200` status
  - removed the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/command` from the response with the `200` status
  - removed the required property `oneOf[#/components/schemas/ResearchWorkspaceSSHConnection]/user` from the response with the `200` status
  - removed the required property `oneOf[#/components/schemas/WorkspaceWebSocketSSHConnection]/alias` from the response with the `200` status
  - …3 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/research-workspaces/:id/connections/post.md)

---

[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)