Skip to content

feat(docs): add automated SSH setup and remote dev guide for VM users #3554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
FedericoMusa wants to merge 1 commit into from
Closed

feat(docs): add automated SSH setup and remote dev guide for VM users #3554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions ENVIRONMENT_SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,40 @@ Set `PYTHONPATH` (required in every new PowerShell session):
```powershell
$env:PYTHONPATH="core;exports"
```
## Remote Development Setup (SSH)
If you are developing inside a Virtual Machine (e.g., VirtualBox) and experience mouse lag or UI latency, it is strongly recommended to use a Remote SSH connection for a more responsive development experience.
### 1. Configure the Virtual Machine (Guest)
Run the automated remote setup script inside your Ubuntu/Linux terminal:

´´´´ bash scripts/setup-remote.sh ´´´
### 2. Configure Port Forwarding
To allow your Host (Windows/Mac) to communicate with the VM, set up a tunnel in your virtualization software:

a) Open VirtualBox Settings → Network → Advanced → Port Forwarding.

b)Add a new rule with the following details:

______________________________
| Field | Value |
|__________|_________________|
| Name | SSH |
|__________|_________________|
| Protocol | TCP |
|__________|_________________|
| Host Port| 2222 |
|__________|_________________|
|Guest Port| 22 |
|__________|_________________|
| Host IP |127.0.0.1 |
| |(or leave blank) |
| ___________________________|
### 3. IDE Connection
Connect your IDE (VS Code, Cursor, or PyCharm) using the following configuration:
- Host: 127.0.0.1
- Port: 2222
- User: your Ubuntu username

Pro Tip: For VS Code users, install the Remote - SSH extension by Microsoft. Once installed, press F1, type Remote-SSH: Connect to Host..., and enter ssh [email protected] -p 2222.

## Alpine Linux Setup

Expand Down
33 changes: 33 additions & 0 deletions scripts/setup-remote.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
#!/bin/bash
# scripts/setup-remote.sh - Aden Agent Framework Remote Development Utility

echo ""
echo "==================================="
echo " Remote Development Setup"
echo "==================================="
echo ""
echo "🚀 This script configures your environment for remote"
echo " development via SSH (VS Code, Cursor, PyCharm)."
echo ""

# 1. Install networking dependencies
echo "📦 Installing openssh-server and net-tools..."
sudo apt update && sudo apt install -y openssh-server net-tools

# 2. Configure Firewall for SSH
echo "🛡️ Configuring Firewall..."
sudo ufw allow 22

# 3. Reload and Restart SSH service
echo "🔄 Refreshing SSH services..."
sudo systemctl daemon-reload
sudo systemctl restart ssh

echo ""
echo "✅ Setup Complete!"
echo "--------------------------------------------------------"
echo "💡 INSTRUCTIONS FOR YOUR HOST (Windows/Mac):"
echo "1. VirtualBox: Map Host Port 2222 to Guest Port 22."
echo "2. Your Internal IP is: $(hostname -I | awk '{print $1}')"
echo "3. Connection Command: ssh [email protected] -p 2222"
echo "--------------------------------------------------------"