# VM on Golem Requestor
Rent compute on demand — like Airbnb for servers. The `golem` CLI helps you discover providers, fund pay‑as‑you‑go streams, launch VMs, and connect via SSH.
## Quick Start (Rent a VM)
1) Install:
```bash
pip install request-vm-on-golem
```
2) Find providers (testnet by default):
```bash
golem vm providers
```
3) Create a VM (auto‑opens a payment stream if needed):
```bash
golem vm create my-vm --provider-id 0xProvider --cpu 2 --memory 4 --storage 20
```
4) SSH in:
```bash
golem vm ssh my-vm
```
Check your installed version and whether an update is available:
```bash
golem version
```
5) Stop or destroy when done:
```bash
golem vm stop my-vm
golem vm destroy my-vm
```
## 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
## Streaming Payments (Native ETH on L2)
This requestor integrates with an on‑chain StreamPayment contract to enable “pay‑as‑you‑go” rentals using native ETH (no ERC20 approvals when the token address is zero).
Flow:
1. Fetch provider info (preferred addresses):
- `GET http://{provider}:7466/api/v1/provider/info` → `provider_id`, `stream_payment_address`, `glm_token_address` (zero address means native ETH).
2. Compute `ratePerSecond` from provider pricing and requested VM resources.
3. Ensure `deposit >= ratePerSecond * 3600` (≥ 1 hour runway recommended/minimum).
4. Create a stream (`createStream(0x000...0, provider_id, deposit, ratePerSecond)` plus `value=deposit`), capture `stream_id`. For ERC20 mode use a token address and approve first.
5. Create VM: `POST /api/v1/vms` with `stream_id` included.
6. Top‑up over time with `topUp(stream_id, amount)` to extend stopTime and keep the VM running indefinitely.
7. On stop/destroy: the requestor will best‑effort `withdraw` / `terminate` to settle.
CLI helpers
- Open a stream for a planned VM (computes rate from provider pricing):
```bash
golem vm stream open \
--provider-id 0xProvider \
--cpu 2 --memory 4 --storage 20 \
--hours 1
# prints { stream_id, rate_per_second_wei, deposit_wei }
```
- Top up an existing stream:
```bash
# Add 3 hours at prior rate
golem vm stream topup --stream-id 123 --hours 3
# Or specify exact GLM amount
golem vm stream topup --stream-id 123 --glm 25.0
```
- Check stream status via provider (by VM name recorded in your DB):
```bash
golem vm stream status my-vm
# add --json for machine-readable output
```
- Inspect a stream directly on-chain:
```bash
golem vm stream inspect --stream-id 123
```
- Stopping or destroying a VM ends the stream:
```bash
# Stop VM and terminate payment stream (best-effort)
golem vm stop my-vm
# Destroy VM and terminate stream
golem vm destroy my-vm
```
- Create a VM and attach an existing stream (no auto-streams are created by the requestor):
```bash
golem vm create my-vm \
--provider-id 0xProvider \
--cpu 2 --memory 4 --storage 20 \
--stream-id 123
```
Environment (env prefix `GOLEM_REQUESTOR_`):
- `payments_network` — Payments network profile (defaults to `l2.holesky`). Profiles provide RPC + faucet defaults.
- `polygon_rpc_url` — EVM RPC URL (defaults from `payments_network` profile; can be overridden)
- `stream_payment_address` — StreamPayment address (defaults from `contracts/deployments/l2.json`; overridden by provider info)
- `glm_token_address` — Token address (defaults from `contracts/deployments/l2.json`; zero address means native ETH)
- Optional override of deployments directory: set `GOLEM_DEPLOYMENTS_DIR` to a folder containing `l2.json`.
- `provider_eth_address` — optional dev helper; in production always use `/provider/info`
- `network` — Target network for discovery filtering: `testnet` (default) or `mainnet`
Efficiency tips:
- Batch top‑ups (e.g., add several hours at once) to reduce on‑chain calls.
- Withdrawals are typically executed by providers; requestors don’t need to withdraw.
- The CLI `vm stream open` will prefer the provider’s advertised contract/token addresses to prevent mismatches.
Monitoring and auto top-up:
- The requestor API runs a background monitor that keeps each running VM’s stream funded with at least 1 hour runway (configurable). It checks every 30s and tops up to the target runway.
- Configure via env (prefix `GOLEM_REQUESTOR_`): `stream_monitor_enabled` (default true), `stream_monitor_interval_seconds` (default 30), `stream_min_remaining_seconds` (default 3600), `stream_topup_target_seconds` (default 3600).
## Faucet (Testnet only)
- Request L2 test ETH to cover stream transactions:
```bash
golem wallet faucet
```
- Defaults:
- Faucet URL and enablement come from the active `payments_network` profile. On `mainnet` (or other profiles without faucet) the command is disabled.
- CAPTCHA: `https://cap.gobas.me/05381a2cef5e`
- Override with env: `GOLEM_REQUESTOR_l2_faucet_url`, `GOLEM_REQUESTOR_captcha_url`, `GOLEM_REQUESTOR_captcha_api_key`.
## Installation
```bash
# Install using pip
pip install request-vm-on-golem
# Or install from source
git clone https://github.com/golem/vm-on-golem.git
cd vm-on-golem/requestor-server
pip install -e .
```
## Development
To run the application in development mode, you need to set environment variables to configure development-specific settings. These are defined in the `.env.dev` file.
You can run the server in development mode using one of the following methods:
### Using `source`
First, source the development environment variables:
```bash
source .env.dev
```
Then, run any `golem` command. For example: `golem vm providers`
### Prepending variables
Alternatively, you can prepend the environment variables directly to the command:
```bash
GOLEM_REQUESTOR_ENVIRONMENT="development" GOLEM_REQUESTOR_FORCE_LOCALHOST="true" poetry run golem vm providers
```
### Mode vs. Network
- Development Mode (`GOLEM_REQUESTOR_ENVIRONMENT=development`)
- Improves local workflows: prefixes central discovery URL with `DEVMODE-` and, when using the central driver, maps provider IPs to `localhost` for easier testing.
- Does not determine chain selection.
- Network Selection (`--network` or `GOLEM_REQUESTOR_NETWORK`)
- Filters results by `testnet|mainnet`. Defaults are sensible; most users don’t need to change anything.
- Payments Network (`GOLEM_REQUESTOR_PAYMENTS_NETWORK`)
- Selects the payments chain profile (e.g., `l2.holesky`, `mainnet`) used for streaming payments; sets default RPC and faucet behavior.
- Provider discovery filters by this payments network via `vm providers` unless `--all-payments` is supplied. Override payments filter with `--payments-network <name>`.
Examples:
- List providers on mainnet without changing env: `golem vm providers --network mainnet`
- Create a VM while targeting testnet: `golem vm create my-vm --provider-id 0xProvider --cpu 2 --memory 4 --storage 20 --network testnet`
## Usage
### Provider Discovery
List available providers with their resources:
```bash
golem vm providers
```
Example output:
```
────────────────────────────────────────────────
🌍 Available Providers (3 total)
────────────────────────────────────────────────
Provider ID Country CPU Memory Disk
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 Disk
🟢 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
# 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
export GOLEM_REQUESTOR_NETWORK="testnet" # Or "mainnet"; optional filter for listing/creation
```
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. Network discovery (uses sane defaults; no setup required for most users)
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.11",
"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/16/06/a870ee23fa012d3f5e3851f3960d28576c2725040997ebd06fcc93742963/request_vm_on_golem-0.1.54.tar.gz",
"platform": null,
"description": "# VM on Golem Requestor\n\nRent compute on demand \u2014 like Airbnb for servers. The `golem` CLI helps you discover providers, fund pay\u2011as\u2011you\u2011go streams, launch VMs, and connect via SSH.\n\n## Quick Start (Rent a VM)\n\n1) Install:\n\n```bash\npip install request-vm-on-golem\n```\n\n2) Find providers (testnet by default):\n\n```bash\ngolem vm providers\n```\n\n3) Create a VM (auto\u2011opens a payment stream if needed):\n\n```bash\ngolem vm create my-vm --provider-id 0xProvider --cpu 2 --memory 4 --storage 20\n```\n\n4) SSH in:\n\n```bash\ngolem vm ssh my-vm\n```\n\nCheck your installed version and whether an update is available:\n\n```bash\ngolem version\n```\n\n5) Stop or destroy when done:\n\n```bash\ngolem vm stop my-vm\ngolem vm destroy my-vm\n```\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## Streaming Payments (Native ETH on L2)\n\nThis requestor integrates with an on\u2011chain StreamPayment contract to enable \u201cpay\u2011as\u2011you\u2011go\u201d rentals using native ETH (no ERC20 approvals when the token address is zero).\n\nFlow:\n\n1. Fetch provider info (preferred addresses):\n - `GET http://{provider}:7466/api/v1/provider/info` \u2192 `provider_id`, `stream_payment_address`, `glm_token_address` (zero address means native ETH).\n2. Compute `ratePerSecond` from provider pricing and requested VM resources.\n3. Ensure `deposit >= ratePerSecond * 3600` (\u2265 1 hour runway recommended/minimum).\n4. Create a stream (`createStream(0x000...0, provider_id, deposit, ratePerSecond)` plus `value=deposit`), capture `stream_id`. For ERC20 mode use a token address and approve first.\n5. Create VM: `POST /api/v1/vms` with `stream_id` included.\n6. Top\u2011up over time with `topUp(stream_id, amount)` to extend stopTime and keep the VM running indefinitely.\n7. On stop/destroy: the requestor will best\u2011effort `withdraw` / `terminate` to settle.\n\nCLI helpers\n\n- Open a stream for a planned VM (computes rate from provider pricing):\n\n```bash\ngolem vm stream open \\\n --provider-id 0xProvider \\\n --cpu 2 --memory 4 --storage 20 \\\n --hours 1\n# prints { stream_id, rate_per_second_wei, deposit_wei }\n```\n\n- Top up an existing stream:\n\n```bash\n# Add 3 hours at prior rate\ngolem vm stream topup --stream-id 123 --hours 3\n\n# Or specify exact GLM amount\ngolem vm stream topup --stream-id 123 --glm 25.0\n```\n\n- Check stream status via provider (by VM name recorded in your DB):\n\n```bash\ngolem vm stream status my-vm\n# add --json for machine-readable output\n```\n\n- Inspect a stream directly on-chain:\n\n```bash\ngolem vm stream inspect --stream-id 123\n```\n\n- Stopping or destroying a VM ends the stream:\n\n```bash\n# Stop VM and terminate payment stream (best-effort)\ngolem vm stop my-vm\n\n# Destroy VM and terminate stream\ngolem vm destroy my-vm\n```\n\n- Create a VM and attach an existing stream (no auto-streams are created by the requestor):\n\n```bash\ngolem vm create my-vm \\\n --provider-id 0xProvider \\\n --cpu 2 --memory 4 --storage 20 \\\n --stream-id 123\n```\n\nEnvironment (env prefix `GOLEM_REQUESTOR_`):\n\n- `payments_network` \u2014 Payments network profile (defaults to `l2.holesky`). Profiles provide RPC + faucet defaults.\n- `polygon_rpc_url` \u2014 EVM RPC URL (defaults from `payments_network` profile; can be overridden)\n- `stream_payment_address` \u2014 StreamPayment address (defaults from `contracts/deployments/l2.json`; overridden by provider info)\n- `glm_token_address` \u2014 Token address (defaults from `contracts/deployments/l2.json`; zero address means native ETH)\n - Optional override of deployments directory: set `GOLEM_DEPLOYMENTS_DIR` to a folder containing `l2.json`.\n- `provider_eth_address` \u2014 optional dev helper; in production always use `/provider/info`\n- `network` \u2014 Target network for discovery filtering: `testnet` (default) or `mainnet`\n\nEfficiency tips:\n\n- Batch top\u2011ups (e.g., add several hours at once) to reduce on\u2011chain calls.\n- Withdrawals are typically executed by providers; requestors don\u2019t need to withdraw.\n- The CLI `vm stream open` will prefer the provider\u2019s advertised contract/token addresses to prevent mismatches.\n\nMonitoring and auto top-up:\n\n- The requestor API runs a background monitor that keeps each running VM\u2019s stream funded with at least 1 hour runway (configurable). It checks every 30s and tops up to the target runway.\n- Configure via env (prefix `GOLEM_REQUESTOR_`): `stream_monitor_enabled` (default true), `stream_monitor_interval_seconds` (default 30), `stream_min_remaining_seconds` (default 3600), `stream_topup_target_seconds` (default 3600).\n\n## Faucet (Testnet only)\n\n- Request L2 test ETH to cover stream transactions:\n\n```bash\ngolem wallet faucet\n```\n\n- Defaults:\n - Faucet URL and enablement come from the active `payments_network` profile. On `mainnet` (or other profiles without faucet) the command is disabled.\n - CAPTCHA: `https://cap.gobas.me/05381a2cef5e`\n - Override with env: `GOLEM_REQUESTOR_l2_faucet_url`, `GOLEM_REQUESTOR_captcha_url`, `GOLEM_REQUESTOR_captcha_api_key`.\n\n## Installation\n\n```bash\n# Install using pip\npip install request-vm-on-golem\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## Development\n\nTo run the application in development mode, you need to set environment variables to configure development-specific settings. These are defined in the `.env.dev` file.\n\nYou can run the server in development mode using one of the following methods:\n\n### Using `source`\n\nFirst, source the development environment variables:\n\n```bash\nsource .env.dev\n```\n\nThen, run any `golem` command. For example: `golem vm providers`\n\n### Prepending variables\n\nAlternatively, you can prepend the environment variables directly to the command:\n\n```bash\nGOLEM_REQUESTOR_ENVIRONMENT=\"development\" GOLEM_REQUESTOR_FORCE_LOCALHOST=\"true\" poetry run golem vm providers\n```\n\n### Mode vs. Network\n\n- Development Mode (`GOLEM_REQUESTOR_ENVIRONMENT=development`)\n - Improves local workflows: prefixes central discovery URL with `DEVMODE-` and, when using the central driver, maps provider IPs to `localhost` for easier testing.\n - Does not determine chain selection.\n\n- Network Selection (`--network` or `GOLEM_REQUESTOR_NETWORK`)\n - Filters results by `testnet|mainnet`. Defaults are sensible; most users don\u2019t need to change anything.\n\n- Payments Network (`GOLEM_REQUESTOR_PAYMENTS_NETWORK`)\n - Selects the payments chain profile (e.g., `l2.holesky`, `mainnet`) used for streaming payments; sets default RPC and faucet behavior.\n - Provider discovery filters by this payments network via `vm providers` unless `--all-payments` is supplied. Override payments filter with `--payments-network <name>`.\n\nExamples:\n- List providers on mainnet without changing env: `golem vm providers --network mainnet`\n- Create a VM while targeting testnet: `golem vm create my-vm --provider-id 0xProvider --cpu 2 --memory 4 --storage 20 --network testnet`\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 Disk\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 Disk\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# 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\nexport GOLEM_REQUESTOR_NETWORK=\"testnet\" # Or \"mainnet\"; optional filter for listing/creation\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. Network discovery (uses sane defaults; no setup required for most users)\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.54",
"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": "a9b834dd9c89ff10aaf86307f66801000aef7445bc7580de46a378901bd9f11b",
"md5": "4366a8c38743809137c4c68fac6f6bf8",
"sha256": "8ece0a6f2d0e3313e56430a4d72e36bc3082ce3ab27d69e636f9bb89b562b73a"
},
"downloads": -1,
"filename": "request_vm_on_golem-0.1.54-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4366a8c38743809137c4c68fac6f6bf8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 45733,
"upload_time": "2025-09-10T11:31:37",
"upload_time_iso_8601": "2025-09-10T11:31:37.419595Z",
"url": "https://files.pythonhosted.org/packages/a9/b8/34dd9c89ff10aaf86307f66801000aef7445bc7580de46a378901bd9f11b/request_vm_on_golem-0.1.54-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1606a870ee23fa012d3f5e3851f3960d28576c2725040997ebd06fcc93742963",
"md5": "20f0c0319ae2b7b9251796b1aff3135c",
"sha256": "b9b1f9c767b8894087f6438dad0fe39d57a0c718b456806790b1b2fc9d7aadd4"
},
"downloads": -1,
"filename": "request_vm_on_golem-0.1.54.tar.gz",
"has_sig": false,
"md5_digest": "20f0c0319ae2b7b9251796b1aff3135c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 41627,
"upload_time": "2025-09-10T11:31:38",
"upload_time_iso_8601": "2025-09-10T11:31:38.509311Z",
"url": "https://files.pythonhosted.org/packages/16/06/a870ee23fa012d3f5e3851f3960d28576c2725040997ebd06fcc93742963/request_vm_on_golem-0.1.54.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 11:31:38",
"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"
}
JSON
