Python SDK

The InstaVM Python SDK provides a simple and intuitive way to interact with the InstaVM API. It handles session management, error handling, and provides code execution and browser automation capabilities.

Installation

pip install instavm

Current version: 0.5.0

Quick Start

from instavm import InstaVM

# Initialize with your API key
vm = InstaVM('your_api_key_here')

# Execute code
result = vm.execute("print('Hello from InstaVM!')")
print(result)

Client Configuration

Basic Configuration

from instavm import InstaVM

# Default configuration
client = InstaVM('your_api_key')

# Custom configuration
client = InstaVM(
    api_key='your_api_key',
    base_url='https://api.instavm.io',  # Custom API endpoint
    timeout=30,                         # Request timeout in seconds
    max_retries=3                      # Number of retry attempts
)

Using Environment Variables

import os
from instavm import InstaVM

# Set API key via environment variable
os.environ['INSTAVM_API_KEY'] = 'your_api_key'
client = InstaVM(os.getenv('INSTAVM_API_KEY'))

Core Methods

execute(command)

Execute code synchronously on a virtual machine.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    result = vm.execute("""
    import math
    result = math.sqrt(16)
    print(f"Square root of 16 is {result}")
    """)
    
    print(result['output'])  # Square root of 16 is 4.0
    print(result['execution_time'])  # 0.123

execute_streaming(command, on_output=None) [DEPRECATED]

Note: This method is deprecated as the API no longer supports streaming execution. Use execute() or execute_async() instead.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Use execute() instead for synchronous execution
    result = vm.execute("pip install requests")
    print(result['output'])

upload_file(file_path, remote_path, recursive=False)

Upload a file to the virtual machine.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Upload a file to a specific remote path
    result = vm.upload_file(
        file_path='/path/to/local/file.txt',
        remote_path='/workspace/file.txt'
    )
    print(f"Uploaded {result['filename']}, size: {result['size']} bytes")

    # Now execute code that uses the file
    vm.execute("with open('/workspace/file.txt', 'r') as f: print(f.read())")

download_file(filename, local_path=None)

Download a file from the virtual machine.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Execute code that creates a file
    vm.execute("with open('/workspace/output.txt', 'w') as f: f.write('Hello World')")

    # Download the file
    result = vm.download_file(
        filename='/workspace/output.txt',
        local_path='/path/to/local/output.txt'
    )
    print(f"Downloaded {result['filename']}, size: {result['size']} bytes")

    # Or get content directly without saving
    result = vm.download_file(filename='/workspace/output.txt')
    print(f"File content: {result['content']}")

execute_async(command, language=None, timeout=None)

Execute code asynchronously for long-running operations.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Start async execution
    result = vm.execute_async("""
    import time
    for i in range(10):
        print(f"Step {i}")
        time.sleep(1)
    """)

    execution_id = result.get('execution_id')
    print(f"Started async execution: {execution_id}")

get_usage()

Get usage metrics for the current session.

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    vm.execute("print('Hello World')")
    
    usage = vm.get_usage()
    print(f"CPU Time: {usage['cpu_time']}s")
    print(f"Memory Used: {usage['memory_used']} bytes")
    print(f"Network I/O: {usage['network_io']} bytes")

Session Management

Automatic Session Management (Recommended)

from instavm import InstaVM

# Context manager automatically handles session lifecycle
with InstaVM('your_api_key') as vm:
    result = vm.execute("print('Session managed automatically')")
    # Session automatically closed when exiting context

Manual Session Management

from instavm import InstaVM

vm = InstaVM('your_api_key')
try:
    # Session started automatically
    result = vm.execute("print('Manual session management')")
    
    # Check session status
    if vm.is_session_active():
        print("Session is active")
        
    # Get session info
    info = vm.get_session_info()
    print(f"Session ID: {info['session_id']}")
    
finally:
    # Always close session
    vm.close_session()

Browser Automation

The SDK includes comprehensive browser automation capabilities.

Creating a Browser Session

from instavm import InstaVM

client = InstaVM('your_api_key')

# Create a browser session with custom viewport
session = client.browser.create_session(
    viewport_width=1920,
    viewport_height=1080,
    user_agent="Custom User Agent"
)

# Use the session
session.navigate("https://example.com")
session.click("button.submit")
session.close()

Using Browser Context Manager

from instavm import InstaVM

client = InstaVM('your_api_key')

# Browser session with automatic cleanup
with client.browser.create_session() as session:
    session.navigate("https://example.com")
    session.fill("input#email", "user@example.com")
    session.click("button[type='submit']")
    screenshot = session.screenshot()
    # Session automatically closed when exiting

Browser Methods

navigate(url, wait_timeout=30000)

session.navigate("https://example.com", wait_timeout=30000)

click(selector, force=False, timeout=30000)

session.click("button.submit", force=False, timeout=30000)

type(selector, text, delay=100, timeout=30000)

session.type("input#search", "search query", delay=100)

fill(selector, value, timeout=30000)

session.fill("input[name='email']", "user@example.com")

scroll(selector=None, x=None, y=None)

# Scroll element into view
session.scroll(selector="div.content")

# Scroll to absolute coordinates
session.scroll(x=0, y=500)

wait_for(condition, selector=None, timeout=30000)

session.wait_for("load", timeout=30000)
session.wait_for("visible", selector="div.content", timeout=5000)

screenshot(full_page=True, clip=None, format="png", quality=None)

# Full page screenshot
screenshot_base64 = session.screenshot(full_page=True)

# Clip screenshot
screenshot_base64 = session.screenshot(
    full_page=False,
    clip={"x": 0, "y": 0, "width": 800, "height": 600}
)

extract_elements(selector=None, attributes=None)

# Extract all links
elements = session.extract_elements(
    selector="a",
    attributes=["href", "text"]
)

for elem in elements:
    print(f"Link: {elem['href']} - {elem['text']}")

Browser Manager Methods

The client.browser manager provides convenience methods that auto-create sessions:

from instavm import InstaVM

client = InstaVM('your_api_key')

# These methods auto-create a default session if none exists
client.browser.navigate("https://example.com")
client.browser.click("button.submit")
screenshot = client.browser.screenshot()

# Don't forget to close the default session
client.browser.close()

List Browser Sessions

from instavm import InstaVM

client = InstaVM('your_api_key')

# Get all active browser sessions
sessions = client.list_browser_sessions()
for session in sessions:
    print(f"Session ID: {session['session_id']}")
    print(f"Created: {session['created_at']}")

Error Handling

The SDK provides specific exception types for different error scenarios:

from instavm import (
    InstaVM,
    AuthenticationError,
    SessionError,
    ExecutionError,
    NetworkError,
    RateLimitError,
    BrowserError,
    BrowserSessionError,
    BrowserInteractionError,
    BrowserTimeoutError,
    BrowserNavigationError,
    ElementNotFoundError,
    QuotaExceededError
)

# Code execution errors
try:
    vm = InstaVM('invalid_api_key')
    result = vm.execute("print('This will fail')")

except AuthenticationError:
    print("Invalid API key provided")

except SessionError as e:
    print(f"Session error: {e}")

except ExecutionError as e:
    print(f"Code execution failed: {e}")

except NetworkError as e:
    print(f"Network issue: {e}")

except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")

# Browser automation errors
try:
    client = InstaVM('your_api_key')
    with client.browser.create_session() as session:
        session.navigate("https://example.com")
        session.click("button.nonexistent")

except ElementNotFoundError as e:
    print(f"Element not found: {e}")

except BrowserTimeoutError as e:
    print(f"Browser operation timed out: {e}")

except BrowserNavigationError as e:
    print(f"Navigation failed: {e}")

except QuotaExceededError as e:
    print(f"Browser quota exceeded: {e}")

except BrowserError as e:
    print(f"Browser error: {e}")

Advanced Examples

Data Visualization with Matplotlib

from instavm import InstaVM
import base64

with InstaVM('your_api_key') as vm:
    result = vm.execute("""
import subprocess
import sys
import base64

# Install matplotlib
subprocess.check_call([sys.executable, "-m", "pip", "install", "matplotlib"])

import matplotlib.pyplot as plt
import numpy as np

# Generate data
x = np.linspace(0, 10, 100)
y = np.sin(x)

# Create plot
plt.figure(figsize=(10, 6))
plt.plot(x, y, 'b-', linewidth=2, label='sin(x)')
plt.xlabel('x')
plt.ylabel('y')
plt.title('Sine Wave Generated on InstaVM')
plt.legend()
plt.grid(True, alpha=0.3)

# Save to bytes and encode
import io
buf = io.BytesIO()
plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
buf.seek(0)

# Return base64 encoded image
image_base64 = base64.b64encode(buf.read()).decode('utf-8')
print(f"IMAGE_DATA:{image_base64}")
""")

    # Extract image data from output
    if "IMAGE_DATA:" in result['output']:
        image_data = result['output'].split("IMAGE_DATA:")[1].strip()
        # Save locally or display
        with open('sine_wave.png', 'wb') as f:
            f.write(base64.b64decode(image_data))
        print("Visualization saved as sine_wave.png")

File Processing with FFmpeg

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Upload video file
    upload_result = vm.upload_file('/path/to/input_video.mp4')
    
    # Process with FFmpeg
    result = vm.execute("""
import subprocess

# Install FFmpeg
subprocess.run(['apt-get', 'update'], check=True)
subprocess.run(['apt-get', 'install', '-y', 'ffmpeg'], check=True)

# Convert video
subprocess.run([
    'ffmpeg', '-i', 'input_video.mp4',
    '-vf', 'scale=640:480',
    '-codec:v', 'libx264',
    '-codec:a', 'aac',
    'output_video.mp4'
], check=True)

print("Video processing completed")
""")
    
    # Download processed file (implementation depends on your setup)
    print("Video processed successfully!")

Package Installation and Usage

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    # Install and use scientific packages
    result = vm.execute("""
import subprocess
import sys

# Install scientific packages
packages = ['numpy', 'pandas', 'scikit-learn']
for package in packages:
    subprocess.check_call([sys.executable, "-m", "pip", "install", package])

# Use the packages
import numpy as np
import pandas as pd
from sklearn.linear_model import LinearRegression

# Generate sample data
X = np.random.rand(100, 1) * 10
y = 2.5 * X.ravel() + np.random.randn(100) * 2

# Fit model
model = LinearRegression()
model.fit(X, y)

print(f"Model coefficient: {model.coef_[0]:.2f}")
print(f"Model intercept: {model.intercept_:.2f}")
print(f"Model score: {model.score(X, y):.3f}")
""")
    
    print(result['output'])

Performance Tips

1. Reuse sessions: Keep sessions alive for multiple operations to avoid startup overhead
2. Use streaming for long operations: Monitor progress with execute_streaming()
3. Handle errors gracefully: Implement proper retry logic for network issues
4. Close sessions: Always close sessions to free up resources

Advanced Examples

Web Scraping with Browser Automation

from instavm import InstaVM
import json

client = InstaVM('your_api_key')

with client.browser.create_session() as session:
    # Navigate to page
    session.navigate("https://news.ycombinator.com")

    # Wait for content to load
    session.wait_for("load")

    # Extract all post titles and links
    posts = session.extract_elements(
        selector=".titleline > a",
        attributes=["href", "text"]
    )

    # Save to file
    with open('hn_posts.json', 'w') as f:
        json.dump(posts, f, indent=2)

    print(f"Extracted {len(posts)} posts")

Form Automation

from instavm import InstaVM

client = InstaVM('your_api_key')

with client.browser.create_session() as session:
    # Navigate to form
    session.navigate("https://example.com/contact")

    # Fill form fields
    session.fill("input[name='name']", "John Doe")
    session.fill("input[name='email']", "john@example.com")
    session.fill("textarea[name='message']", "Hello from InstaVM!")

    # Submit form
    session.click("button[type='submit']")

    # Wait for success message
    session.wait_for("visible", selector=".success-message")

    # Take screenshot of result
    screenshot = session.screenshot()

Configuration Options

InstaVM Client

Parameter	Default	Description
api_key	Required	Your InstaVM API key
base_url	https://api.instavm.io	API endpoint URL
timeout	300	Request timeout in seconds
max_retries	0	Number of retry attempts for failed requests

Browser Session

Parameter	Default	Description
viewport_width	1920	Browser viewport width in pixels
viewport_height	1080	Browser viewport height in pixels
user_agent	None	Custom user agent string

Next Steps

• JavaScript SDK
• Go SDK
• Authentication Guide