Skip to main content

​
Connect a remote workspace

A remote workspace runs the agent, file operations, and terminals on an SSH host, in a WSL distribution, or in a Docker container. The desktop interface stays on your computer. WSL and Docker environments can run on that same computer. The repository and development tools must already be available in that environment; connecting does not copy your local checkout. Prepare the environment before connecting: Then attach the workspace:
  1. In a new Code session, open the folder menu and choose Remote workspace… under Run on.
  2. Choose the connection type, enter the connection details, and select an existing project folder on the target.
  3. If the task needs local tools, select them under Tools and credentials. Including their credentials requires a separate selection.
  4. Choose Connect. The dialog shows setup progress or the error that prevented the connection.
Selected tools and configuration are copied once, at connection time. Later local changes are not continuously synchronized to the target. Connector OAuth authorizations are not copied; configure authentication in the target environment for connectors that need it. The session’s execution location is fixed once it starts, so working on another machine requires a new session. Disconnecting detaches the desktop interface without canceling an active remote task. Use the session’s stop control to cancel the work. Transferred tools and persistent credentials remain on the remote machine after disconnection.

​
Enter connection details

For SSH, enter the host and remote folder. If your SSH configuration does not supply them, also enter the username, port, and private-key path. Establish trust for the host through your normal SSH setup first; the app expects the host in known_hosts and authentication that does not stop for an interactive prompt. For WSL, choose the installed distribution. For Docker, enter the name or ID of an existing running container and, if needed, a Docker context. In each case, use an existing Remote folder, such as ~/project or /home/user/project. That folder becomes the session’s working directory. Before beginning an edit, ask the agent to read the remote README and report the project location and available test command. This checks that you selected the intended checkout before doing work in it.

An SSH connection needs a host and an existing remote folder. These are example values.

​
Reconnect to existing work

Use Saved connections to reuse a destination. Disconnect closes the desktop connection; Forget removes the saved connection entry. Neither changes an existing session’s destination. To stop an active remote task, use its stop control before disconnecting. If you update a skill or connector locally after connecting, do not assume the remote copy has changed. Tools are transferred once, and remote authentication must still be valid. Check the remote setup when a tool works locally but is missing or unauthorized in a remote session.

​
Use a cloud environment when available

If your account offers Cloud… in the workspace selector, use a saved cloud environment instead of an SSH, WSL, or Docker connection. A cloud environment defines the repositories and startup configuration for a new session. Availability depends on your account and organization. In Settings → Cloud environments, create or open an environment. Adding a repository requires a GitHub connection on the account. Choose each repository and branch, or leave the branch empty to use its displayed default. The environment can also define a setup script, environment variables, and network access: Put only non-secret configuration in the environment variables; those values are visible to environment users. The optional Bash setup script runs at the start of each new session, before the agent, using the selected network access. Select the environment before the first message. That message creates the cloud session and prepares its repositories. Open the environment chip to inspect repository status. If preparation fails, use Retry when offered; if the setup script fails, the dialog may offer Run setup again. Inspect the reported error before retrying. Changes to the saved network level apply to new sessions. Existing sessions keep their original access, and changing environments requires a new session. Continue with Scheduled tasks.