un-inception/clients/ruby/sync/README.md

Un - Ruby SDK for unsandbox.com

Synchronous Ruby client for the unsandbox.com secure code execution service.

Installation

Add to your Gemfile:

gem 'un', git: 'https://github.com/unsandbox/un-ruby'

Or copy src/un.rb directly into your project.

Quick Start

require 'un'

# Execute code synchronously
result = Un.execute_code('python', 'print("Hello, World!")')
puts result['stdout']  # => "Hello, World!\n"

Authentication

The SDK uses a 4-tier credential resolution system:

1. Method arguments - Pass public_key: and secret_key: directly
2. Environment variables - UNSANDBOX_PUBLIC_KEY and UNSANDBOX_SECRET_KEY
3. User config file - ~/.unsandbox/accounts.csv
4. Local config file - ./accounts.csv

CSV Format

unsb-pk-xxxxx-xxxxx-xxxxx-xxxxx,unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx

Use UNSANDBOX_ACCOUNT=N to select a specific account (0-indexed).

Request Signing

All requests are signed using HMAC-SHA256:

X-Signature: HMAC-SHA256(secret_key, "timestamp:METHOD:path:body")
X-Timestamp: <unix_seconds>
Authorization: Bearer <public_key>

API Reference

Execute Code

# Synchronous execution (blocks until complete)
result = Un.execute_code('python', 'print(42)')
# => {"status"=>"completed", "stdout"=>"42\n", "stderr"=>"", "exit_code"=>0}

# Asynchronous execution (returns immediately)
job_id = Un.execute_async('python', 'import time; time.sleep(10); print("done")')
# => "job-abc123"

# Wait for async job
result = Un.wait_for_job(job_id, timeout: 60)
# => {"status"=>"completed", "stdout"=>"done\n", ...}

Job Management

# Get job status
job = Un.get_job(job_id)
# => {"job_id"=>"...", "status"=>"running", ...}

# List all jobs
jobs = Un.list_jobs
# => [{"job_id"=>"...", "status"=>"completed"}, ...]

# Cancel a running job
Un.cancel_job(job_id)

Languages

# Get supported languages (cached for 1 hour)
languages = Un.get_languages
# => ["python", "javascript", "go", "rust", ...]

# Detect language from filename
Un.detect_language('script.py')    # => "python"
Un.detect_language('app.js')       # => "javascript"
Un.detect_language('main.go')      # => "go"

Snapshots

# Create session snapshot
snapshot_id = Un.session_snapshot(session_id, name: 'my-backup')

# Create ephemeral session snapshot
snapshot_id = Un.session_snapshot(session_id, ephemeral: true)

# Create service snapshot
snapshot_id = Un.service_snapshot(service_id, name: 'prod-backup')

# List snapshots
snapshots = Un.list_snapshots

# Restore snapshot
result = Un.restore_snapshot(snapshot_id)

# Delete snapshot
Un.delete_snapshot(snapshot_id)

Error Handling

begin
  result = Un.execute_code('python', 'print("hello")')
rescue Un::CredentialsError => e
  # No credentials found
  puts e.message
rescue Un::APIError => e
  # API request failed
  puts "HTTP #{e.status_code}: #{e.message}"
  puts e.response_body
end

Error Types

• Un::CredentialsError - No valid credentials found
• Un::APIError - API request failed (includes status_code and response_body)

HTTP Status Codes

• 401 - Invalid or missing API key
• 429 - Rate limit or concurrency limit exceeded
• 500 - Server error

Supported Languages

50+ runtimes including:

• Interpreted: Python, JavaScript, TypeScript, Ruby, PHP, Perl, Lua, R, Bash
• Compiled: C, C++, Go, Rust, Java, Kotlin, C#, F#
• Functional: Haskell, OCaml, Elixir, Erlang, Clojure, Scheme
• Other: Dart, Crystal, Nim, Zig, V, Julia, Fortran, COBOL

Examples

See the examples/ directory:

• hello_world.rb - Basic code execution
• async_job.rb - Async execution with polling
• language_detection.rb - Detect language from filename
• snapshots.rb - Snapshot operations

Testing

bundle install
bundle exec rake test

License

Public Domain - No License, No Warranty