Browse docs

Session Environments

SSH sessions

SSH sessions run filesystem and command operations on a remote host using a saved SSH connection profile.

What SSH sessions are

When execution target is set to SSH, runtime FS/exec operations are routed through an SSH-backed driver instead of local host execution.

  • Useful for operating directly on remote development or staging machines.
  • Good when remote-only files, services, or environment parity matter.
  • Session requests are blocked if no valid SSH connection is selected.

Setup requirements

  • Create a connection with name, host, port, username, and default working directory.
  • Choose authentication method: password or private key (path or inline key content).
  • Optionally provide passphrase and known-hosts path metadata in the saved connection profile.
  • Select the saved SSH connection from session execution target controls before sending requests.

Safety model and boundaries

  • SSH credentials are persisted with encrypted secret storage when the platform supports secure storage.
  • Commands execute on the remote host account you configure, not inside local container sandbox isolation.
  • Use least-privilege remote accounts and explicit working directories for safer operation.
  • Treat SSH sessions as direct remote execution and validate high-impact commands before approval.

When to use SSH vs other environments

  • Use SSH when remote host state is the source of truth for your task.
  • Use local sessions for fastest local iteration and desktop-centric workflows.
  • Use local container sessions when you want local runtime isolation but keep local filesystem control.
  • Use cloud sessions when you need server-managed continuity and reconnect-friendly long runs.