pw sessions create

Create a new session on a remote resource

Synopsis

The pw session create command creates a new session on a remote resource.

Supported session types:

desktop - VNC desktop session
vscode - VS Code server session
tunnel - TCP port tunnel (requires --remote-port)

By default, the command returns immediately after creating the session. Use --wait to wait for the session to be running before exiting. --open and --connect imply --wait.

Resource names can be specified in the following formats:

workspace or user-workspace - your user workspace
pw://username/name - full format with explicit username
pw://name - managed cluster by name in your organization
name - short format where username defaults to your username

By default a session runs on the cluster's login node. To run it on a compute node instead, either schedule a new worker with --environment, or reuse a worker you already have with --worker:

--environment submits a scheduler job for a dedicated worker and starts the session on it once the job runs. Pass --param to set the environment's scheduling parameters, and run pw environments get to see which parameters it accepts. Scheduling is queued, so pair this with --wait.
--worker starts the session on an existing connected worker, as listed by pw workers ls. This skips the queue.

pw sessions create --type TYPE <resource> [flags]

Examples

  pw session create --type desktop workspace
  
  # Create a desktop session on a resource
  pw session create --type desktop my-cluster
  
  # Create a VS Code session
  pw session create --type vscode my-cluster
  
  # Create a VS Code session opening a specific directory
  pw session create --type vscode --directory '~/projects' my-cluster
  
  # Create a tunnel session forwarding a remote port
  pw session create --type tunnel --remote-port 8080 my-cluster
  
  # Create and immediately open in the browser
  pw session create --type desktop --open my-cluster
  
  # Create a session with a custom name
  pw session create --type tunnel --name my-tunnel --remote-port 8080 my-cluster
  
  # Create and immediately connect (port forward)
  pw session create --type tunnel --connect --port 8080 --remote-port 3000 my-cluster
  
  # Create a public session anyone can open without logging in
  pw session create --type desktop --public my-cluster
  
  # Schedule a desktop session onto a compute environment
  pw session create --type desktop --environment gpu-large --wait my-hpc
  
  # Schedule with environment parameters
  pw session create --type desktop --environment gpu-large --param numNodes=2 --wait my-hpc
  
  # Start a session on a worker that is already running
  pw session create --type desktop --worker 60c72b2f9b1e8d001c8e4f3a my-hpc

Options

      --connect              Connect (port forward) after creation (desktop and tunnel only, implies --wait)
      --directory string     Directory to open in VS Code
      --environment string   Schedule the session onto a compute environment, by name or ID
  -h, --help                 help for create
      --name string          Custom session name (default: <type>_<timestamp>)
      --open                 Open the session in the browser after creation (implies --wait)
      --param stringArray    Scheduling parameter for --environment as key=value (repeatable)
      --port int             Local port for --connect (0 = auto-select)
      --public               Make the session publicly accessible: anyone with the link can open it without logging in. Requires your organization to allow public sessions.
      --remote-host string   Remote host for tunnel type (default "localhost")
      --remote-port int      Remote port (required for tunnel type)
      --type string          Session type: desktop, vscode, tunnel (required)
      --wait                 Wait for the session to be running before exiting
      --worker string        Run the session on an existing compute worker, by ID

Options inherited from parent commands

      --context string         The context to use. Overrides PW_CONTEXT environment variable and current context from config.
      --platform-host string   The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
  -v, --verbose                Enable verbose logging

pw sessions create