request-vm-on-golem


Namerequest-vm-on-golem JSON
Version 0.1.21 PyPI version JSON
download
home_pagehttps://github.com/cryptobench/vm-on-golem
SummaryVM on Golem Requestor CLI - Create and manage virtual machines on the Golem Network
upload_time2025-02-20 23:54:50
maintainerNone
docs_urlNone
authorPhillip Jensen
requires_python<4.0,>=3.9
licenseNone
keywords golem vm cloud decentralized cli
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # VM on Golem Requestor

A sophisticated command-line interface for managing virtual machines on the Golem Network. The requestor works in tandem with provider nodes to create and manage VMs with secure SSH access.

## Architecture Overview

```mermaid
graph TB
    subgraph Requestor
        CLI[CLI Interface]
        DB[Local Database]
        SSH[SSH Manager]
        PC[Provider Client]
    end

    subgraph Provider
        API[Provider API]
        VM[VM Manager]
        Proxy[SSH Proxy]
        RT[Resource Tracker]
    end

    CLI --> PC
    PC --> API
    SSH --> Proxy
    VM --> RT
```

## How It Works

### 1. VM Creation Flow

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant SSH
    participant Provider
    participant VM

    User->>CLI: Create VM Command
    CLI->>SSH: Generate SSH Key
    SSH-->>CLI: Key Pair
    CLI->>Provider: Create VM Request + Public Key
    Provider->>VM: Launch with Cloud-Init
    Provider->>Proxy: Configure SSH Port
    Provider-->>CLI: VM Details + Port
    CLI->>DB: Save VM State
    CLI-->>User: Connection Info
```

When you create a VM:

1. The requestor generates an SSH key pair or uses your system's existing keys
2. The provider receives the public key and injects it during VM creation via cloud-init
3. The provider allocates a dedicated port and configures SSH forwarding
4. Connection details are stored locally for future access

### 2. SSH Connection Flow

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant DB
    participant Proxy
    participant VM

    User->>CLI: SSH Command
    CLI->>DB: Get VM Details
    DB-->>CLI: Connection Info
    CLI->>Proxy: SSH Connection
    Proxy->>VM: Forward Connection
    VM-->>User: Interactive Shell
```

The SSH connection process:

1. The CLI retrieves stored VM details from the local database
2. The provider's proxy system forwards your SSH connection to the VM
3. All traffic is securely routed through the allocated port

## Installation

```bash
# Install using pip
pip install golem-vm-requestor

# Or install from source
git clone https://github.com/golem/vm-on-golem.git
cd vm-on-golem/requestor-server
pip install -e .
```

## Usage

### Provider Discovery

List available providers with their resources:

```bash
golem vm providers
```

Example output:

```
────────────────────────────────────────────────
  🌍 Available Providers (3 total)
────────────────────────────────────────────────
Provider ID     Country   CPU    Memory    Storage
provider-1      🌍 SE     💻 4    🧠 8GB    💾 40GB
provider-2      🌍 US     💻 8    🧠 16GB   💾 80GB
provider-3      🌍 DE     💻 2    🧠 4GB    💾 20GB
────────────────────────────────────────────────
```

### Creating a VM

```bash
golem vm create my-webserver --provider-id provider-1 --cpu 2 --memory 4 --storage 20
```

The system will:

1. Verify provider availability
2. Check resource requirements
3. Set up SSH access
4. Deploy and configure the VM
5. Save connection details locally

Example output:

```
────────────────────────────────────────────────
  🎉 VM Deployed Successfully!
────────────────────────────────────────────────

  VM Details
  ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
  🏷️  Name      : my-webserver
  💻 Resources  : 2 CPU, 4GB RAM, 20GB Storage
  🟢 Status     : running

  Connection Details
  ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
  🌐 IP Address : 192.168.1.100
  🔌 Port       : 50800

  Quick Connect
  ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
  🔑 SSH Command : ssh -i ~/.golem/ssh/id_rsa -p 50800 ubuntu@192.168.1.100
────────────────────────────────────────────────
```

### Managing VMs

List your VMs:

```bash
golem vm list
```

Example output:

```
────────────────────────────────────────────────
  📋 Your VMs (2 total)
────────────────────────────────────────────────
Name          Status         IP Address      Resources
my-webserver  ● running     192.168.1.100   2 CPU, 4GB RAM
my-database   ● stopped     192.168.1.101   4 CPU, 8GB RAM
────────────────────────────────────────────────
```

Other commands:

```bash
# SSH into a VM
golem vm ssh my-webserver

# Stop a VM
golem vm stop my-webserver

# Start a VM
golem vm start my-webserver

# Destroy a VM
golem vm destroy my-webserver
```

## Configuration

The requestor uses a hierarchical configuration system:

1. Environment Variables:

```bash
# Discovery Service
export GOLEM_REQUESTOR_DISCOVERY_URL="http://discovery.golem.network:9001"

# Base Directory (default: ~/.golem)
export GOLEM_REQUESTOR_BASE_DIR="/path/to/golem/dir"

# Individual Paths (override base dir)
export GOLEM_REQUESTOR_SSH_KEY_DIR="/path/to/keys"
export GOLEM_REQUESTOR_DB_PATH="/path/to/database.db"

# Environment Mode (defaults to "production")
export GOLEM_REQUESTOR_ENVIRONMENT="development"  # Optional: Switch to development mode
export GOLEM_REQUESTOR_FORCE_LOCALHOST="true"    # Optional: Force localhost in development mode
```

2. Directory Structure:

```
~/.golem/
  ├── ssh/              # SSH keys
  │   ├── id_rsa       # Private key
  │   └── id_rsa.pub   # Public key
  └── vms.db           # SQLite database
```

## Technical Details

### SSH Key Management

The system intelligently handles SSH keys:

1. Uses existing system SSH keys if available
2. Generates and manages Golem-specific keys if needed
3. Ensures proper key permissions (0600 for private, 0644 for public)
4. Supports key reuse across VMs

### State Management

Local state is maintained in SQLite:

-   VM details and configuration
-   Provider information
-   Connection parameters
-   VM status tracking

### Provider Integration

The requestor communicates with providers through:

1. Discovery service for provider location
2. Direct API calls for VM management
3. SSH proxy system for secure access
4. Resource tracking for capacity management

## Error Handling

The system provides clear error messages and recovery steps:

```
Error: Unable to establish SSH connection (VM may be starting up)
Solution: Wait a few moments and try again. The VM is likely still initializing.

Error: Provider is no longer available (they may have gone offline)
Solution: Choose a different provider or wait for the original to come back online.

Error: VM not found in local database
Solution: The VM may have been manually removed. Use 'golem vm list' to see available VMs.
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests
5. Submit a pull request

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/cryptobench/vm-on-golem",
    "name": "request-vm-on-golem",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": "golem, vm, cloud, decentralized, cli",
    "author": "Phillip Jensen",
    "author_email": "phillip+vm-on-golem@golemgrid.com",
    "download_url": "https://files.pythonhosted.org/packages/d6/03/7c9057f4caaaa51c013e95e6ede1a7a7d951f0690d381099d8321e7324f9/request_vm_on_golem-0.1.21.tar.gz",
    "platform": null,
    "description": "# VM on Golem Requestor\n\nA sophisticated command-line interface for managing virtual machines on the Golem Network. The requestor works in tandem with provider nodes to create and manage VMs with secure SSH access.\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph Requestor\n        CLI[CLI Interface]\n        DB[Local Database]\n        SSH[SSH Manager]\n        PC[Provider Client]\n    end\n\n    subgraph Provider\n        API[Provider API]\n        VM[VM Manager]\n        Proxy[SSH Proxy]\n        RT[Resource Tracker]\n    end\n\n    CLI --> PC\n    PC --> API\n    SSH --> Proxy\n    VM --> RT\n```\n\n## How It Works\n\n### 1. VM Creation Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CLI\n    participant SSH\n    participant Provider\n    participant VM\n\n    User->>CLI: Create VM Command\n    CLI->>SSH: Generate SSH Key\n    SSH-->>CLI: Key Pair\n    CLI->>Provider: Create VM Request + Public Key\n    Provider->>VM: Launch with Cloud-Init\n    Provider->>Proxy: Configure SSH Port\n    Provider-->>CLI: VM Details + Port\n    CLI->>DB: Save VM State\n    CLI-->>User: Connection Info\n```\n\nWhen you create a VM:\n\n1. The requestor generates an SSH key pair or uses your system's existing keys\n2. The provider receives the public key and injects it during VM creation via cloud-init\n3. The provider allocates a dedicated port and configures SSH forwarding\n4. Connection details are stored locally for future access\n\n### 2. SSH Connection Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CLI\n    participant DB\n    participant Proxy\n    participant VM\n\n    User->>CLI: SSH Command\n    CLI->>DB: Get VM Details\n    DB-->>CLI: Connection Info\n    CLI->>Proxy: SSH Connection\n    Proxy->>VM: Forward Connection\n    VM-->>User: Interactive Shell\n```\n\nThe SSH connection process:\n\n1. The CLI retrieves stored VM details from the local database\n2. The provider's proxy system forwards your SSH connection to the VM\n3. All traffic is securely routed through the allocated port\n\n## Installation\n\n```bash\n# Install using pip\npip install golem-vm-requestor\n\n# Or install from source\ngit clone https://github.com/golem/vm-on-golem.git\ncd vm-on-golem/requestor-server\npip install -e .\n```\n\n## Usage\n\n### Provider Discovery\n\nList available providers with their resources:\n\n```bash\ngolem vm providers\n```\n\nExample output:\n\n```\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  \ud83c\udf0d Available Providers (3 total)\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nProvider ID     Country   CPU    Memory    Storage\nprovider-1      \ud83c\udf0d SE     \ud83d\udcbb 4    \ud83e\udde0 8GB    \ud83d\udcbe 40GB\nprovider-2      \ud83c\udf0d US     \ud83d\udcbb 8    \ud83e\udde0 16GB   \ud83d\udcbe 80GB\nprovider-3      \ud83c\udf0d DE     \ud83d\udcbb 2    \ud83e\udde0 4GB    \ud83d\udcbe 20GB\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n```\n\n### Creating a VM\n\n```bash\ngolem vm create my-webserver --provider-id provider-1 --cpu 2 --memory 4 --storage 20\n```\n\nThe system will:\n\n1. Verify provider availability\n2. Check resource requirements\n3. Set up SSH access\n4. Deploy and configure the VM\n5. Save connection details locally\n\nExample output:\n\n```\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  \ud83c\udf89 VM Deployed Successfully!\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  VM Details\n  \u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\n  \ud83c\udff7\ufe0f  Name      : my-webserver\n  \ud83d\udcbb Resources  : 2 CPU, 4GB RAM, 20GB Storage\n  \ud83d\udfe2 Status     : running\n\n  Connection Details\n  \u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\n  \ud83c\udf10 IP Address : 192.168.1.100\n  \ud83d\udd0c Port       : 50800\n\n  Quick Connect\n  \u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\u2508\n  \ud83d\udd11 SSH Command : ssh -i ~/.golem/ssh/id_rsa -p 50800 ubuntu@192.168.1.100\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n```\n\n### Managing VMs\n\nList your VMs:\n\n```bash\ngolem vm list\n```\n\nExample output:\n\n```\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  \ud83d\udccb Your VMs (2 total)\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nName          Status         IP Address      Resources\nmy-webserver  \u25cf running     192.168.1.100   2 CPU, 4GB RAM\nmy-database   \u25cf stopped     192.168.1.101   4 CPU, 8GB RAM\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n```\n\nOther commands:\n\n```bash\n# SSH into a VM\ngolem vm ssh my-webserver\n\n# Stop a VM\ngolem vm stop my-webserver\n\n# Start a VM\ngolem vm start my-webserver\n\n# Destroy a VM\ngolem vm destroy my-webserver\n```\n\n## Configuration\n\nThe requestor uses a hierarchical configuration system:\n\n1. Environment Variables:\n\n```bash\n# Discovery Service\nexport GOLEM_REQUESTOR_DISCOVERY_URL=\"http://discovery.golem.network:9001\"\n\n# Base Directory (default: ~/.golem)\nexport GOLEM_REQUESTOR_BASE_DIR=\"/path/to/golem/dir\"\n\n# Individual Paths (override base dir)\nexport GOLEM_REQUESTOR_SSH_KEY_DIR=\"/path/to/keys\"\nexport GOLEM_REQUESTOR_DB_PATH=\"/path/to/database.db\"\n\n# Environment Mode (defaults to \"production\")\nexport GOLEM_REQUESTOR_ENVIRONMENT=\"development\"  # Optional: Switch to development mode\nexport GOLEM_REQUESTOR_FORCE_LOCALHOST=\"true\"    # Optional: Force localhost in development mode\n```\n\n2. Directory Structure:\n\n```\n~/.golem/\n  \u251c\u2500\u2500 ssh/              # SSH keys\n  \u2502   \u251c\u2500\u2500 id_rsa       # Private key\n  \u2502   \u2514\u2500\u2500 id_rsa.pub   # Public key\n  \u2514\u2500\u2500 vms.db           # SQLite database\n```\n\n## Technical Details\n\n### SSH Key Management\n\nThe system intelligently handles SSH keys:\n\n1. Uses existing system SSH keys if available\n2. Generates and manages Golem-specific keys if needed\n3. Ensures proper key permissions (0600 for private, 0644 for public)\n4. Supports key reuse across VMs\n\n### State Management\n\nLocal state is maintained in SQLite:\n\n-   VM details and configuration\n-   Provider information\n-   Connection parameters\n-   VM status tracking\n\n### Provider Integration\n\nThe requestor communicates with providers through:\n\n1. Discovery service for provider location\n2. Direct API calls for VM management\n3. SSH proxy system for secure access\n4. Resource tracking for capacity management\n\n## Error Handling\n\nThe system provides clear error messages and recovery steps:\n\n```\nError: Unable to establish SSH connection (VM may be starting up)\nSolution: Wait a few moments and try again. The VM is likely still initializing.\n\nError: Provider is no longer available (they may have gone offline)\nSolution: Choose a different provider or wait for the original to come back online.\n\nError: VM not found in local database\nSolution: The VM may have been manually removed. Use 'golem vm list' to see available VMs.\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run the tests\n5. Submit a pull request\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "VM on Golem Requestor CLI - Create and manage virtual machines on the Golem Network",
    "version": "0.1.21",
    "project_urls": {
        "Homepage": "https://github.com/cryptobench/vm-on-golem",
        "Repository": "https://github.com/cryptobench/vm-on-golem"
    },
    "split_keywords": [
        "golem",
        " vm",
        " cloud",
        " decentralized",
        " cli"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "847161b595a46119163857acdfba69e318354940c58ca38fb94f6e2f211b87d3",
                "md5": "e227fa603b31c14f766cf58d6da3757e",
                "sha256": "d4e65871999ebba558d4bd7d4ef4b8f74c590e0ee014a32a05316ec82cd2c2f8"
            },
            "downloads": -1,
            "filename": "request_vm_on_golem-0.1.21-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e227fa603b31c14f766cf58d6da3757e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 19440,
            "upload_time": "2025-02-20T23:54:48",
            "upload_time_iso_8601": "2025-02-20T23:54:48.148175Z",
            "url": "https://files.pythonhosted.org/packages/84/71/61b595a46119163857acdfba69e318354940c58ca38fb94f6e2f211b87d3/request_vm_on_golem-0.1.21-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d6037c9057f4caaaa51c013e95e6ede1a7a7d951f0690d381099d8321e7324f9",
                "md5": "3876ba5ceee42ef799e1c56efc1fc2ff",
                "sha256": "c8dacd243b2c3380558cbd45748656a60634437126785caf52a3c583fe8e6461"
            },
            "downloads": -1,
            "filename": "request_vm_on_golem-0.1.21.tar.gz",
            "has_sig": false,
            "md5_digest": "3876ba5ceee42ef799e1c56efc1fc2ff",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 17338,
            "upload_time": "2025-02-20T23:54:50",
            "upload_time_iso_8601": "2025-02-20T23:54:50.950003Z",
            "url": "https://files.pythonhosted.org/packages/d6/03/7c9057f4caaaa51c013e95e6ede1a7a7d951f0690d381099d8321e7324f9/request_vm_on_golem-0.1.21.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-20 23:54:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cryptobench",
    "github_project": "vm-on-golem",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "request-vm-on-golem"
}
        
Elapsed time: 0.41581s