cloudx-proxy 0.4.2__tar.gz → 0.4.3__tar.gz

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.4.3](https://github.com/easytocloud/cloudX-proxy/compare/v0.4.2...v0.4.3) (2025-03-06)
+
+
+### Bug Fixes
+
+* improved documentation and simplified ssh config output ([5b5d9a4](https://github.com/easytocloud/cloudX-proxy/commit/5b5d9a496bcba440e4863e8285673e8f97d3c684))
+
 ## [0.4.2](https://github.com/easytocloud/cloudX-proxy/compare/v0.4.1...v0.4.2) (2025-03-06)
 
 

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.4.2
+Version: 0.4.3
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -112,6 +112,15 @@ uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
 # Setup with AWS environment
 uvx cloudx-proxy setup --aws-env prod
+
+# Setup with custom SSH config location
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
+
+# Setup with 1Password integration
+uvx cloudx-proxy setup --1password
+
+# Combine options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 The setup command will:
@@ -123,13 +132,16 @@ The setup command will:
 
 2. Manage SSH Keys:
    - Creates new SSH key pair if needed
-   - Offers 1Password integration options:
-     * Using 1Password SSH agent
-     * Storing private key as 1Password document
+   - Fully supports 1Password integration:
+     * Using 1Password SSH agent via `--1password` flag
+     * Creates keys directly in 1Password's secure vault
+     * Only public keys are exported to the filesystem
+     * Follows SSH best practices using public keys to limit authentication attempts
 
 3. Configure SSH:
-   - Creates ~/.ssh/vscode/config with proper settings
-   - Sets up environment-specific configurations
+   - Creates SSH configs with proper settings (default: ~/.ssh/vscode/config)
+   - Custom config location can be specified with `--ssh-config`
+   - Sets up optimized environment-specific configurations
    - Configures ProxyCommand with all necessary parameters
    - Ensures main ~/.ssh/config includes the configuration
 
@@ -150,12 +162,18 @@ Will create a configuration like this:
 
 ```
 # Base environment config (created once per environment)
+# Environment-wide configuration
 Host cloudx-dev-*
     User ec2-user
     IdentityFile ~/.ssh/vscode/mykey
+    IdentitiesOnly yes
     ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+    TCPKeepAlive yes
+    ControlMaster auto
+    ControlPath ~/.ssh/control/%r@%h:%p
+    ControlPersist 4h
 
-# Host entry (added for specific instance)
+# Minimal host entry (inherits all settings from environment config)
 Host cloudx-dev-myserver
     HostName i-0123456789abcdef0
 ```
@@ -173,17 +191,19 @@ In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofi
 VSCode will be able to connect to the instance using the same SSH configuration.
 
 ### SSH Configuration Details
-The setup command creates:
+The setup command creates an optimized SSH configuration structure:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
-   - 1Password integration if selected
+   - 1Password SSH agent integration if selected
    - ProxyCommand with appropriate parameters
+   - SSH multiplexing for better performance
+   - TCP keepalive for connection stability
 
-2. Individual host entries for each instance:
+2. Minimal host entries for each instance:
    - Uses consistent naming (cloudx-{env}-hostname)
-   - Maps to instance IDs automatically
-   - Inherits environment-level settings
+   - Only contains the HostName directive for the instance ID
+   - Inherits all environment-level settings automatically
 
 When adding new instances to an existing environment, you can choose to:
 - Override the environment configuration with new settings
@@ -211,7 +231,9 @@ uvx cloudx-proxy setup [OPTIONS]
 
 Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
-- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in ~/.ssh/vscode/{name}. This same name can be used in the connect command.
+- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
+- `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
+- `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 
 Example usage:
@@ -222,8 +244,11 @@ uvx cloudx-proxy setup
 # Setup with custom profile and key
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
-# Setup with AWS environment
-uvx cloudx-proxy setup --profile myprofile --aws-env prod
+# Setup with custom SSH config and 1Password integration
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config --1password
+
+# Complete setup with all options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 #### Connect Command
@@ -238,6 +263,7 @@ Arguments:
 Options:
 - `--profile` (default: vscode): AWS profile to use. Should match the profile used in setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to use. Should match the key name used in setup.
+- `--ssh-config` (optional): Path to the SSH config file to use. If provided during setup, should match here.
 - `--region` (optional): AWS region to use. If not specified, uses the region from the AWS profile.
 - `--aws-env` (optional): AWS environment directory to use. Should match the environment used in setup.
 
@@ -303,12 +329,17 @@ These permissions are required to bootstrap the instance, so that after creation
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
+   - Check if the instance is starting up (can take several minutes)
 
 3. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
-   - For stored keys in 1Password, ensure you can access them via the CLI
+   - For 1Password-managed keys, make sure:
+     * 1Password CLI is installed and authenticated (`op account list` works)
+     * SSH agent is enabled in 1Password settings
+     * Keys are added to the SSH agent in 1Password
+     * The key is visible with `op item list --categories "SSH Key"`
 
 4. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/README.md

@@ -62,6 +62,15 @@ uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
 # Setup with AWS environment
 uvx cloudx-proxy setup --aws-env prod
+
+# Setup with custom SSH config location
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
+
+# Setup with 1Password integration
+uvx cloudx-proxy setup --1password
+
+# Combine options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 The setup command will:
@@ -73,13 +82,16 @@ The setup command will:
 
 2. Manage SSH Keys:
    - Creates new SSH key pair if needed
-   - Offers 1Password integration options:
-     * Using 1Password SSH agent
-     * Storing private key as 1Password document
+   - Fully supports 1Password integration:
+     * Using 1Password SSH agent via `--1password` flag
+     * Creates keys directly in 1Password's secure vault
+     * Only public keys are exported to the filesystem
+     * Follows SSH best practices using public keys to limit authentication attempts
 
 3. Configure SSH:
-   - Creates ~/.ssh/vscode/config with proper settings
-   - Sets up environment-specific configurations
+   - Creates SSH configs with proper settings (default: ~/.ssh/vscode/config)
+   - Custom config location can be specified with `--ssh-config`
+   - Sets up optimized environment-specific configurations
    - Configures ProxyCommand with all necessary parameters
    - Ensures main ~/.ssh/config includes the configuration
 
@@ -100,12 +112,18 @@ Will create a configuration like this:
 
 ```
 # Base environment config (created once per environment)
+# Environment-wide configuration
 Host cloudx-dev-*
     User ec2-user
     IdentityFile ~/.ssh/vscode/mykey
+    IdentitiesOnly yes
     ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+    TCPKeepAlive yes
+    ControlMaster auto
+    ControlPath ~/.ssh/control/%r@%h:%p
+    ControlPersist 4h
 
-# Host entry (added for specific instance)
+# Minimal host entry (inherits all settings from environment config)
 Host cloudx-dev-myserver
     HostName i-0123456789abcdef0
 ```
@@ -123,17 +141,19 @@ In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofi
 VSCode will be able to connect to the instance using the same SSH configuration.
 
 ### SSH Configuration Details
-The setup command creates:
+The setup command creates an optimized SSH configuration structure:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
-   - 1Password integration if selected
+   - 1Password SSH agent integration if selected
    - ProxyCommand with appropriate parameters
+   - SSH multiplexing for better performance
+   - TCP keepalive for connection stability
 
-2. Individual host entries for each instance:
+2. Minimal host entries for each instance:
    - Uses consistent naming (cloudx-{env}-hostname)
-   - Maps to instance IDs automatically
-   - Inherits environment-level settings
+   - Only contains the HostName directive for the instance ID
+   - Inherits all environment-level settings automatically
 
 When adding new instances to an existing environment, you can choose to:
 - Override the environment configuration with new settings
@@ -161,7 +181,9 @@ uvx cloudx-proxy setup [OPTIONS]
 
 Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
-- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in ~/.ssh/vscode/{name}. This same name can be used in the connect command.
+- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
+- `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
+- `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 
 Example usage:
@@ -172,8 +194,11 @@ uvx cloudx-proxy setup
 # Setup with custom profile and key
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
-# Setup with AWS environment
-uvx cloudx-proxy setup --profile myprofile --aws-env prod
+# Setup with custom SSH config and 1Password integration
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config --1password
+
+# Complete setup with all options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 #### Connect Command
@@ -188,6 +213,7 @@ Arguments:
 Options:
 - `--profile` (default: vscode): AWS profile to use. Should match the profile used in setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to use. Should match the key name used in setup.
+- `--ssh-config` (optional): Path to the SSH config file to use. If provided during setup, should match here.
 - `--region` (optional): AWS region to use. If not specified, uses the region from the AWS profile.
 - `--aws-env` (optional): AWS environment directory to use. Should match the environment used in setup.
 
@@ -253,12 +279,17 @@ These permissions are required to bootstrap the instance, so that after creation
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
+   - Check if the instance is starting up (can take several minutes)
 
 3. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
-   - For stored keys in 1Password, ensure you can access them via the CLI
+   - For 1Password-managed keys, make sure:
+     * 1Password CLI is installed and authenticated (`op account list` works)
+     * SSH agent is enabled in 1Password settings
+     * Keys are added to the SSH agent in 1Password
+     * The key is visible with `op item list --categories "SSH Key"`
 
 4. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/cloudx_proxy/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.4.2'
-__version_tuple__ = version_tuple = (0, 4, 2)
+__version__ = version = '0.4.3'
+__version_tuple__ = version_tuple = (0, 4, 3)

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/cloudx_proxy/setup.py

@@ -383,38 +383,56 @@ class CloudXSetup:
     IdentitiesOnly yes
 """
 
-    def _build_host_config(self, cloudx_env: str, hostname: str, instance_id: str, include_proxy: bool = True) -> str:
-        """Build a host configuration block.
+    def _build_environment_config(self, cloudx_env: str) -> str:
+        """Build an environment-wide configuration block with all common settings.
         
         Args:
             cloudx_env: CloudX environment
-            hostname: Hostname for the instance
-            instance_id: EC2 instance ID (None for wildcard entries)
-            include_proxy: Whether to include the ProxyCommand (default: True)
             
         Returns:
-            str: Complete host configuration block
+            str: Complete environment configuration block
         """
-        host_pattern = hostname if hostname else "*"
         host_entry = f"""
-Host cloudx-{cloudx_env}-{host_pattern}
-"""
-        # Add HostName only for specific hosts, not for wildcard entries
-        if instance_id:
-            host_entry += f"""    HostName {instance_id}
-"""
-        host_entry += """    User ec2-user
+Host cloudx-{cloudx_env}-*
+    User ec2-user
 """
         # Add authentication configuration
         host_entry += self._build_auth_config()
         
-        # Add proxy command if requested
-        if include_proxy:
-            host_entry += f"""    ProxyCommand {self._build_proxy_command()}
+        # Add ProxyCommand
+        host_entry += f"""    ProxyCommand {self._build_proxy_command()}
+"""
+        
+        # Add SSH multiplexing configuration
+        control_path = "~/.ssh/control/%r@%h:%p"
+        if platform.system() == 'Windows':
+            # Use forward slashes for Windows as well, SSH client will handle conversion
+            control_path = "~/.ssh/control/%r@%h:%p"
+            
+        host_entry += f"""    TCPKeepAlive yes
+    ControlMaster auto
+    ControlPath {control_path}
+    ControlPersist 4h
 """
         
         return host_entry
         
+    def _build_host_config(self, cloudx_env: str, hostname: str, instance_id: str) -> str:
+        """Build a minimal host configuration block that inherits from the environment.
+        
+        Args:
+            cloudx_env: CloudX environment
+            hostname: Hostname for the instance
+            instance_id: EC2 instance ID
+            
+        Returns:
+            str: Minimal host configuration block with only hostname
+        """
+        return f"""
+Host cloudx-{cloudx_env}-{hostname}
+    HostName {instance_id}
+"""
+        
     def _add_host_entry(self, cloudx_env: str, instance_id: str, hostname: str, current_config: str) -> bool:
         """Add settings to a specific host entry.
         
@@ -566,24 +584,13 @@ Host cloudx-{cloudx_env}-{host_pattern}
             
             # Build base configuration with wildcard hostname pattern
             # Start with a header comment
-            base_config = "# cloudx-proxy SSH Configuration\n"
-            
-            # Add base host pattern with wildcard
-            base_config += self._build_host_config(cloudx_env, None, None, include_proxy=True)
-            
-            # Add SSH multiplexing configuration
-            control_path = "~/.ssh/control/%r@%h:%p"
-            if platform.system() == 'Windows':
-                # Use forward slashes for Windows as well, SSH client will handle conversion
-                control_path = "~/.ssh/control/%r@%h:%p"
-                
-            base_config += f"""    TCPKeepAlive yes
-    ControlMaster auto
-    ControlPath {control_path}
-    ControlPersist 4h
-
+            base_config = """# cloudx-proxy SSH Configuration
+# Environment configuration with settings applied to all hosts in this environment
 """
             
+            # Add environment-wide configuration with all common settings
+            base_config += self._build_environment_config(cloudx_env)
+            
             # If file exists, append the new config, otherwise create it
             if self.ssh_config_file.exists():
                 with open(self.ssh_config_file, 'a') as f:
@@ -598,9 +605,9 @@ Host cloudx-{cloudx_env}-{host_pattern}
                 self.ssh_config_file.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 600 permissions (owner read/write)
                 self.print_status("Set config file permissions to 600", True, 2)
 
-            # Add specific host entry using the consolidated helper method
+            # Add specific host entry - only specifying the hostname
             self.print_status(f"Adding host entry for cloudx-{cloudx_env}-{hostname}", None, 2)
-            host_entry = self._build_host_config(cloudx_env, hostname, instance_id, include_proxy=False)
+            host_entry = self._build_host_config(cloudx_env, hostname, instance_id)
             with open(self.ssh_config_file, 'a') as f:
                 f.write(host_entry)
             self.print_status("Host entry added", True, 2)

{cloudx_proxy-0.4.2 → cloudx_proxy-0.4.3}/cloudx_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.4.2
+Version: 0.4.3
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -112,6 +112,15 @@ uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
 # Setup with AWS environment
 uvx cloudx-proxy setup --aws-env prod
+
+# Setup with custom SSH config location
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
+
+# Setup with 1Password integration
+uvx cloudx-proxy setup --1password
+
+# Combine options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 The setup command will:
@@ -123,13 +132,16 @@ The setup command will:
 
 2. Manage SSH Keys:
    - Creates new SSH key pair if needed
-   - Offers 1Password integration options:
-     * Using 1Password SSH agent
-     * Storing private key as 1Password document
+   - Fully supports 1Password integration:
+     * Using 1Password SSH agent via `--1password` flag
+     * Creates keys directly in 1Password's secure vault
+     * Only public keys are exported to the filesystem
+     * Follows SSH best practices using public keys to limit authentication attempts
 
 3. Configure SSH:
-   - Creates ~/.ssh/vscode/config with proper settings
-   - Sets up environment-specific configurations
+   - Creates SSH configs with proper settings (default: ~/.ssh/vscode/config)
+   - Custom config location can be specified with `--ssh-config`
+   - Sets up optimized environment-specific configurations
    - Configures ProxyCommand with all necessary parameters
    - Ensures main ~/.ssh/config includes the configuration
 
@@ -150,12 +162,18 @@ Will create a configuration like this:
 
 ```
 # Base environment config (created once per environment)
+# Environment-wide configuration
 Host cloudx-dev-*
     User ec2-user
     IdentityFile ~/.ssh/vscode/mykey
+    IdentitiesOnly yes
     ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+    TCPKeepAlive yes
+    ControlMaster auto
+    ControlPath ~/.ssh/control/%r@%h:%p
+    ControlPersist 4h
 
-# Host entry (added for specific instance)
+# Minimal host entry (inherits all settings from environment config)
 Host cloudx-dev-myserver
     HostName i-0123456789abcdef0
 ```
@@ -173,17 +191,19 @@ In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofi
 VSCode will be able to connect to the instance using the same SSH configuration.
 
 ### SSH Configuration Details
-The setup command creates:
+The setup command creates an optimized SSH configuration structure:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
-   - 1Password integration if selected
+   - 1Password SSH agent integration if selected
    - ProxyCommand with appropriate parameters
+   - SSH multiplexing for better performance
+   - TCP keepalive for connection stability
 
-2. Individual host entries for each instance:
+2. Minimal host entries for each instance:
    - Uses consistent naming (cloudx-{env}-hostname)
-   - Maps to instance IDs automatically
-   - Inherits environment-level settings
+   - Only contains the HostName directive for the instance ID
+   - Inherits all environment-level settings automatically
 
 When adding new instances to an existing environment, you can choose to:
 - Override the environment configuration with new settings
@@ -211,7 +231,9 @@ uvx cloudx-proxy setup [OPTIONS]
 
 Options:
 - `--profile` (default: vscode): AWS profile to use. The profile's IAM user should follow the format cloudX-{env}-{user}. The environment part will be used as the default environment during setup.
-- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in ~/.ssh/vscode/{name}. This same name can be used in the connect command.
+- `--ssh-key` (default: vscode): Name of the SSH key to create/use. The key will be stored in the SSH config directory. This same name can be used in the connect command.
+- `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
+- `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
 
 Example usage:
@@ -222,8 +244,11 @@ uvx cloudx-proxy setup
 # Setup with custom profile and key
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
 
-# Setup with AWS environment
-uvx cloudx-proxy setup --profile myprofile --aws-env prod
+# Setup with custom SSH config and 1Password integration
+uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config --1password
+
+# Complete setup with all options
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
 
 #### Connect Command
@@ -238,6 +263,7 @@ Arguments:
 Options:
 - `--profile` (default: vscode): AWS profile to use. Should match the profile used in setup.
 - `--ssh-key` (default: vscode): Name of the SSH key to use. Should match the key name used in setup.
+- `--ssh-config` (optional): Path to the SSH config file to use. If provided during setup, should match here.
 - `--region` (optional): AWS region to use. If not specified, uses the region from the AWS profile.
 - `--aws-env` (optional): AWS environment directory to use. Should match the environment used in setup.
 
@@ -303,12 +329,17 @@ These permissions are required to bootstrap the instance, so that after creation
    - Check that your AWS credentials have the required permissions
    - Verify the instance ID is correct
    - Increase the VSCode SSH timeout if needed
+   - Check if the instance is starting up (can take several minutes)
 
 3. **SSH Key Issues**
    - If using 1Password SSH agent, verify agent is running (~/.1password/agent.sock exists)
    - Check file permissions (600 for private key, 644 for public key)
    - Verify the public key is being successfully pushed to the instance
-   - For stored keys in 1Password, ensure you can access them via the CLI
+   - For 1Password-managed keys, make sure:
+     * 1Password CLI is installed and authenticated (`op account list` works)
+     * SSH agent is enabled in 1Password settings
+     * Keys are added to the SSH agent in 1Password
+     * The key is visible with `op item list --categories "SSH Key"`
 
 4. **AWS Configuration**
    - Confirm AWS CLI is configured with valid credentials