CLI
Fast command-line client for code execution and interactive sessions. 42+ languages, 30+ shells/REPLs.
Official OpenAPI Swagger Docs ↗Quick Start — Raku
# Download + setup
curl -O https://git.unturf.com/engineering/unturf/un-inception/-/raw/main/clients/raku/sync/src/un.raku && chmod +x un.raku && ln -sf un.raku un
export UNSANDBOX_PUBLIC_KEY="unsb-pk-xxxx-xxxx-xxxx-xxxx"
export UNSANDBOX_SECRET_KEY="unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx"
# Run code
./un script.rakuFeatures
- 42+ languages - Python, JS, Go, Rust, C++, Java...
- Sessions - 30+ shells/REPLs, tmux persistence
- Files - Upload files, collect artifacts
- Services - Persistent containers with domains
- Snapshots - Point-in-time backups
- Images - Publish, share, transfer
Integration Quickstart ⚡
Add unsandbox superpowers to your existing Raku app:
1
Download
curl -O https://git.unturf.com/engineering/unturf/un-inception/-/raw/main/clients/raku/sync/src/un.raku
2
Set API Keys
# Option A: Environment variables
export UNSANDBOX_PUBLIC_KEY="unsb-pk-xxxx-xxxx-xxxx-xxxx"
export UNSANDBOX_SECRET_KEY="unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx"
# Option B: Config file (persistent)
mkdir -p ~/.unsandbox
echo "unsb-pk-xxxx-xxxx-xxxx-xxxx,unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx" > ~/.unsandbox/accounts.csv
3
Hello World
# In your Raku app:
use lib '.';
use Un;
my $result = execute-code("raku", 'say "Hello from Raku running on unsandbox!"');
say $result<stdout>; # Hello from Raku running on unsandbox!
Demo cooldown: s
stdout:
JSON Response:
4
Run
raku myapp.raku
MD5:
4126bd03d45e3f751989b8306b509bd0
SHA256: fc1fa5eb2dc583cea451973f203982b68d04bde194416b76b574d4187f2a83b2
#!/usr/bin/env raku
# PUBLIC DOMAIN - NO LICENSE, NO WARRANTY
#
# This is free public domain software for the public good of a permacomputer hosted
# at permacomputer.com - an always-on computer by the people, for the people. One
# which is durable, easy to repair, and distributed like tap water for machine
# learning intelligence.
#
# The permacomputer is community-owned infrastructure optimized around four values:
#
# TRUTH - First principles, math & science, open source code freely distributed
# FREEDOM - Voluntary partnerships, freedom from tyranny & corporate control
# HARMONY - Minimal waste, self-renewing systems with diverse thriving connections
# LOVE - Be yourself without hurting others, cooperation through natural law
#
# This software contributes to that vision by enabling code execution across 42+
# programming languages through a unified interface, accessible to all. Code is
# seeds to sprout on any abandoned technology.
#
# Learn more: https://www.permacomputer.com
#
# Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
# software, either in source code form or as a compiled binary, for any purpose,
# commercial or non-commercial, and by any means.
#
# NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
#
# That said, our permacomputer's digital membrane stratum continuously runs unit,
# integration, and functional tests on all of it's own software - with our
# permacomputer monitoring itself, repairing itself, with minimal human in the
# loop guidance. Our agents do their best.
#
# Copyright 2025 TimeHexOn & foxhop & russell@unturf
# https://www.timehexon.com
# https://www.foxhop.net
# https://www.unturf.com/software
#
# unsandbox SDK for Raku - Execute code in secure sandboxes
# https://unsandbox.com | https://api.unsandbox.com/openapi
#
# Library Usage:
# use lib '.';
# use un;
# my %result = execute("python", 'print("Hello")');
# my %job = execute-async("python", $code);
# my %result = wait(%job<job_id>);
#
# CLI Usage:
# raku un.raku script.py
# raku un.raku -s python 'print("Hello")'
# raku un.raku session --shell python3
#
# Authentication (in priority order):
# 1. Function arguments: execute(..., :public-key<...>, :secret-key<...>)
# 2. Environment variables: UNSANDBOX_PUBLIC_KEY + UNSANDBOX_SECRET_KEY
# 3. Config file: ~/.unsandbox/accounts.csv (public_key,secret_key per line)
#!/usr/bin/env raku
unit module un;
use JSON::Fast;
use Digest::SHA;
# ============================================================================
# Configuration
# ============================================================================
constant $API_BASE is export = "https://api.unsandbox.com";
constant $PORTAL_BASE is export = "https://unsandbox.com";
constant $DEFAULT_TIMEOUT is export = 300;
constant $DEFAULT_TTL is export = 60;
# Polling delays (ms) - exponential backoff
my @POLL_DELAYS = (300, 450, 700, 900, 650, 1600, 2000);
# ANSI colors
constant $BLUE = "\e[34m";
constant $RED = "\e[31m";
constant $GREEN = "\e[32m";
constant $YELLOW = "\e[33m";
constant $RESET = "\e[0m";
# Extension to language mapping
my %EXT_MAP is export = (
py => 'python', js => 'javascript', ts => 'typescript',
rb => 'ruby', php => 'php', pl => 'perl', lua => 'lua',
sh => 'bash', go => 'go', rs => 'rust', c => 'c',
cpp => 'cpp', cc => 'cpp', cxx => 'cpp',
java => 'java', kt => 'kotlin', cs => 'csharp', fs => 'fsharp',
hs => 'haskell', ml => 'ocaml', clj => 'clojure', scm => 'scheme',
lisp => 'commonlisp', erl => 'erlang', ex => 'elixir', exs => 'elixir',
jl => 'julia', r => 'r', R => 'r', cr => 'crystal',
d => 'd', nim => 'nim', zig => 'zig', v => 'vlang',
dart => 'dart', groovy => 'groovy', scala => 'scala',
f90 => 'fortran', f95 => 'fortran', cob => 'cobol',
pro => 'prolog', forth => 'forth', '4th' => 'forth',
tcl => 'tcl', raku => 'raku', pl6 => 'raku', p6 => 'raku',
m => 'objc', awk => 'awk'
);
# ============================================================================
# Exceptions
# ============================================================================
#| Base exception class for unsandbox errors
class UnsandboxError is Exception is export {
has $.message;
method new($message) { self.bless(:$message) }
method Str { $.message }
}
#| Authentication failed - invalid or missing credentials
class AuthenticationError is UnsandboxError is export { }
#| Code execution failed
class ExecutionError is UnsandboxError is export {
has $.exit-code;
has $.stderr;
}
#| API request failed
class APIError is UnsandboxError is export {
has $.status-code;
has $.response;
}
#| Execution timed out
class TimeoutError is UnsandboxError is export { }
# ============================================================================
# HMAC Authentication
# ============================================================================
#| Generate HMAC-SHA256 signature for API request
#| Signature = HMAC-SHA256(secret_key, "timestamp:METHOD:path:body")
sub sign-request(Str $secret-key, Int $timestamp, Str $method, Str $path, Str $body = "") returns Str is export {
my $message = "{$timestamp}:{$method}:{$path}:{$body}";
return hmac-hex($message, $secret-key, &sha256);
}
#| Get API credentials in priority order:
#| 1. Function arguments
#| 2. Environment variables
#| 3. ~/.unsandbox/accounts.csv
sub get-credentials(Str :$public-key, Str :$secret-key, Int :$account-index = 0) returns List is export {
# Priority 1: Function arguments
if $public-key && $secret-key {
return ($public-key, $secret-key);
}
# Priority 2: Environment variables
my $env-pk = %*ENV<UNSANDBOX_PUBLIC_KEY> // '';
my $env-sk = %*ENV<UNSANDBOX_SECRET_KEY> // '';
if $env-pk && $env-sk {
return ($env-pk, $env-sk);
}
# Priority 3: Config file
my $accounts-path = $*HOME.add('.unsandbox').add('accounts.csv');
if $accounts-path.e {
try {
my @lines = $accounts-path.slurp.trim.split("\n");
my @valid-accounts;
for @lines -> $line {
my $trimmed = $line.trim;
next if !$trimmed || $trimmed.starts-with('#');
if $trimmed.contains(',') {
my ($pk, $sk) = $trimmed.split(',', 2);
if $pk.starts-with('unsb-pk-') && $sk.starts-with('unsb-sk-') {
@valid-accounts.push(($pk, $sk));
}
}
}
if @valid-accounts && $account-index < @valid-accounts.elems {
return @valid-accounts[$account-index];
}
}
}
die AuthenticationError.new(
"No credentials found. Set UNSANDBOX_PUBLIC_KEY and UNSANDBOX_SECRET_KEY, " ~
"or create ~/.unsandbox/accounts.csv, or pass credentials to function."
);
}
# ============================================================================
# HTTP Client
# ============================================================================
#| Make authenticated API request with HMAC signature
sub api-request(
Str $endpoint,
Str $method = 'GET',
%data?,
Str :$body-text,
Str :$content-type = 'application/json',
Str :$public-key,
Str :$secret-key,
Int :$timeout = $DEFAULT_TIMEOUT
) returns Hash is export {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key);
my $url = $API_BASE ~ $endpoint;
my @args = 'curl', '-s', '--max-time', $timeout.Str;
my $body = '';
if $method eq 'GET' {
@args.append: '-X', 'GET';
} elsif $method eq 'DELETE' {
@args.append: '-X', 'DELETE';
} elsif $method eq 'POST' || $method eq 'PUT' || $method eq 'PATCH' {
@args.append: '-X', $method;
@args.append: '-H', "Content-Type: $content-type";
if $body-text.defined {
$body = $body-text;
@args.append: '-d', $body;
} elsif %data {
$body = to-json(%data);
@args.append: '-d', $body;
}
}
@args.append: '-H', "Authorization: Bearer $pk";
# Add HMAC signature
my $timestamp = now.Int;
my $signature = sign-request($sk, $timestamp, $method, $endpoint, $body);
@args.append: '-H', "X-Timestamp: $timestamp";
@args.append: '-H', "X-Signature: $signature";
@args.append: $url;
my $proc = run |@args, :out, :err;
my $resp-body = $proc.out.slurp;
my $err = $proc.err.slurp;
if $proc.exitcode != 0 {
die APIError.new("API request failed: $err", :status-code(0), :response($err));
}
# Check for clock drift errors
if $resp-body.contains('timestamp') && ($resp-body.contains('401') || $resp-body.contains('expired') || $resp-body.contains('invalid')) {
die AuthenticationError.new(
"Request timestamp expired (must be within 5 minutes of server time). " ~
"Your computer's clock may have drifted. Sync with NTP."
);
}
return from-json($resp-body);
}
#| Make authenticated API request returning both status code and body
sub api-request-with-status(
Str $endpoint,
Str $method = 'GET',
%data?,
Str :$body-text,
Str :$content-type = 'application/json',
Str :$public-key,
Str :$secret-key,
Int :$timeout = $DEFAULT_TIMEOUT,
Str :$sudo-otp,
Str :$sudo-challenge
) returns List is export {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key);
my $url = $API_BASE ~ $endpoint;
my @args = 'curl', '-s', '-w', '%{http_code}', '--max-time', $timeout.Str;
my $body = '';
if $method eq 'GET' {
@args.append: '-X', 'GET';
} elsif $method eq 'DELETE' {
@args.append: '-X', 'DELETE';
} elsif $method eq 'POST' || $method eq 'PUT' || $method eq 'PATCH' {
@args.append: '-X', $method;
@args.append: '-H', "Content-Type: $content-type";
if $body-text.defined {
$body = $body-text;
@args.append: '-d', $body;
} elsif %data {
$body = to-json(%data);
@args.append: '-d', $body;
}
}
@args.append: '-H', "Authorization: Bearer $pk";
# Add HMAC signature
my $timestamp = now.Int;
my $signature = sign-request($sk, $timestamp, $method, $endpoint, $body);
@args.append: '-H', "X-Timestamp: $timestamp";
@args.append: '-H', "X-Signature: $signature";
# Add sudo OTP headers if provided
if $sudo-otp.defined && $sudo-challenge.defined {
@args.append: '-H', "X-Sudo-OTP: $sudo-otp";
@args.append: '-H', "X-Sudo-Challenge: $sudo-challenge";
}
@args.append: $url;
my $proc = run |@args, :out, :err;
my $output = $proc.out.slurp;
my $err = $proc.err.slurp;
if $proc.exitcode != 0 {
die APIError.new("API request failed: $err", :status-code(0), :response($err));
}
# Extract status code from end of output
my $status-code = 0;
my $resp-body = $output;
if $output.chars >= 3 {
my $code-str = $output.substr($output.chars - 3);
$status-code = $code-str.Int // 0;
$resp-body = $output.substr(0, $output.chars - 3);
}
return ($status-code, $resp-body);
}
#| Handle HTTP 428 sudo OTP challenge
#| Returns True if retry succeeded, False otherwise
sub handle-sudo-challenge(
Str $response-body,
Str $endpoint,
Str $method,
Str :$body-text,
%data?,
Str :$public-key,
Str :$secret-key,
Int :$timeout = $DEFAULT_TIMEOUT
) returns Bool is export {
# Extract challenge_id from response
my $challenge-id = '';
try {
my %resp = from-json($response-body);
$challenge-id = %resp<challenge_id> // '';
}
unless $challenge-id {
note "{$RED}Error: Could not extract challenge_id from response{$RESET}";
return False;
}
# Prompt user for OTP
note "{$YELLOW}Confirmation required. Check your email for a one-time code.{$RESET}";
$*ERR.print("Enter OTP: ");
my $otp = $*IN.get.trim;
unless $otp {
note "{$RED}Error: No OTP provided{$RESET}";
return False;
}
# Retry request with sudo headers
my ($status, $body) = api-request-with-status(
$endpoint, $method, %data,
:$body-text,
:$public-key, :$secret-key, :$timeout,
:sudo-otp($otp), :sudo-challenge($challenge-id)
);
if $status >= 200 && $status < 300 {
return True;
} else {
note "{$RED}Error: OTP verification failed{$RESET}";
return False;
}
}
# ============================================================================
# Core Execution Functions
# ============================================================================
#| Execute code synchronously and return results
#|
#| Parameters:
#| $language - Programming language (python, javascript, go, rust, etc.)
#| $code - Source code to execute
#| :%env - Environment variables
#| :@input-files - List of {filename => "...", content => "..."}
#| :$network-mode - "zerotrust" (no network) or "semitrusted" (internet access)
#| :$ttl - Execution timeout in seconds (1-900, default 60)
#| :$vcpu - Virtual CPUs (1-8, default 1)
#| :$return-artifact - Return compiled binary
#| :$public-key - API public key
#| :$secret-key - API secret key
#|
#| Returns: Hash with stdout, stderr, exit_code, language, job_id, etc.
#|
#| Example:
#| my %result = execute("python", 'print("Hello World")');
#| say %result<stdout>;
sub execute(
Str $language,
Str $code,
:%env,
:@input-files,
Str :$network-mode = 'zerotrust',
Int :$ttl = $DEFAULT_TTL,
Int :$vcpu = 1,
Bool :$return-artifact = False,
Str :$public-key,
Str :$secret-key,
Int :$timeout = $DEFAULT_TIMEOUT
) returns Hash is export {
my %payload = language => $language, code => $code, network_mode => $network-mode, ttl => $ttl, vcpu => $vcpu;
%payload<env> = %env if %env;
if @input-files {
my @files;
for @input-files -> %f {
if %f<content_base64>:exists {
@files.push(%f);
} elsif %f<content>:exists {
@files.push({
filename => %f<filename>,
content_base64 => %f<content>.encode.base64
});
} else {
@files.push(%f);
}
}
%payload<input_files> = @files;
}
%payload<return_artifact> = True if $return-artifact;
return api-request('/execute', 'POST', %payload, :$public-key, :$secret-key, :$timeout);
}
#| Execute code asynchronously. Returns immediately with job_id for polling.
#|
#| Parameters: Same as execute()
#|
#| Returns: Hash with job_id, status ("pending")
#|
#| Example:
#| my %job = execute-async("python", $long-running-code);
#| say "Job submitted: ", %job<job_id>;
#| my %result = wait(%job<job_id>);
sub execute-async(
Str $language,
Str $code,
:%env,
:@input-files,
Str :$network-mode = 'zerotrust',
Int :$ttl = $DEFAULT_TTL,
Int :$vcpu = 1,
Bool :$return-artifact = False,
Str :$public-key,
Str :$secret-key
) returns Hash is export {
my %payload = language => $language, code => $code, network_mode => $network-mode, ttl => $ttl, vcpu => $vcpu;
%payload<env> = %env if %env;
if @input-files {
my @files;
for @input-files -> %f {
if %f<content_base64>:exists {
@files.push(%f);
} elsif %f<content>:exists {
@files.push({
filename => %f<filename>,
content_base64 => %f<content>.encode.base64
});
} else {
@files.push(%f);
}
}
%payload<input_files> = @files;
}
%payload<return_artifact> = True if $return-artifact;
return api-request('/execute/async', 'POST', %payload, :$public-key, :$secret-key);
}
#| Execute code with automatic language detection from shebang
#|
#| Parameters:
#| $code - Source code with shebang (e.g., #!/usr/bin/env python3)
#| :%env - Environment variables
#| :$network-mode - "zerotrust" or "semitrusted"
#| :$ttl - Execution timeout in seconds
#|
#| Returns: Hash with detected_language, stdout, stderr, etc.
#|
#| Example:
#| my $code = q:to/END/;
#| #!/usr/bin/env python3
#| print("Auto-detected!")
#| END
#| my %result = run($code);
#| say %result<detected_language>;
sub run(
Str $code,
:%env,
Str :$network-mode = 'zerotrust',
Int :$ttl = $DEFAULT_TTL,
Str :$public-key,
Str :$secret-key,
Int :$timeout = $DEFAULT_TIMEOUT
) returns Hash is export {
my $endpoint = "/run?ttl={$ttl}&network_mode={$network-mode}";
if %env {
$endpoint ~= "&env=" ~ uri-encode(to-json(%env));
}
return api-request($endpoint, 'POST', :body-text($code), :content-type('text/plain'), :$public-key, :$secret-key, :$timeout);
}
#| Execute code asynchronously with automatic language detection
#|
#| Returns: Hash with job_id, detected_language, status ("pending")
sub run-async(
Str $code,
:%env,
Str :$network-mode = 'zerotrust',
Int :$ttl = $DEFAULT_TTL,
Str :$public-key,
Str :$secret-key
) returns Hash is export {
my $endpoint = "/run/async?ttl={$ttl}&network_mode={$network-mode}";
if %env {
$endpoint ~= "&env=" ~ uri-encode(to-json(%env));
}
return api-request($endpoint, 'POST', :body-text($code), :content-type('text/plain'), :$public-key, :$secret-key);
}
# ============================================================================
# Job Management
# ============================================================================
#| Get job status and results
#|
#| Parameters:
#| $job-id - Job ID from execute-async or run-async
#|
#| Returns: Hash with job_id, status, result (if completed), timestamps
#|
#| Status values: pending, running, completed, failed, timeout, cancelled
sub get-job(Str $job-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/jobs/{$job-id}", 'GET', :$public-key, :$secret-key);
}
#| Wait for job completion with exponential backoff polling
#|
#| Parameters:
#| $job-id - Job ID from execute-async or run-async
#| :$max-polls - Maximum number of poll attempts (default 100)
#|
#| Returns: Final job result Hash
#|
#| Example:
#| my %job = execute-async("python", $code);
#| my %result = wait(%job<job_id>);
#| say %result<stdout>;
sub wait(
Str $job-id,
Int :$max-polls = 100,
Str :$public-key,
Str :$secret-key
) returns Hash is export {
my @terminal-states = <completed failed timeout cancelled>;
for ^$max-polls -> $i {
my $delay-idx = min($i, @POLL_DELAYS.elems - 1);
sleep @POLL_DELAYS[$delay-idx] / 1000;
my %result = get-job($job-id, :$public-key, :$secret-key);
my $status = %result<status> // '';
if $status (elem) @terminal-states {
if $status eq 'failed' {
die ExecutionError.new(
"Job failed: " ~ (%result<error> // 'Unknown error'),
:exit-code(%result<exit_code>),
:stderr(%result<stderr>)
);
}
if $status eq 'timeout' {
die TimeoutError.new("Job timed out: $job-id");
}
return %result;
}
}
die TimeoutError.new("Max polls ($max-polls) exceeded for job $job-id");
}
#| Cancel a running job
#|
#| Returns: Partial output and artifacts collected before cancellation
sub cancel-job(Str $job-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/jobs/{$job-id}", 'DELETE', :$public-key, :$secret-key);
}
#| List all active jobs for this API key
#|
#| Returns: List of job summary hashes with job_id, language, status, submitted_at
sub list-jobs(Str :$public-key, Str :$secret-key) returns Array is export {
my %result = api-request('/jobs', 'GET', :$public-key, :$secret-key);
return %result<jobs> // [];
}
# ============================================================================
# Image Generation
# ============================================================================
#| Generate images from text prompt
#|
#| Parameters:
#| $prompt - Text description of the image to generate
#| :$model - Model to use (optional)
#| :$size - Image size (e.g., "1024x1024")
#| :$quality - "standard" or "hd"
#| :$n - Number of images to generate
#|
#| Returns: Hash with images array, created_at
#|
#| Example:
#| my %result = image("A sunset over mountains");
#| say %result<images>[0];
sub image(
Str $prompt,
Str :$model,
Str :$size = '1024x1024',
Str :$quality = 'standard',
Int :$n = 1,
Str :$public-key,
Str :$secret-key
) returns Hash is export {
my %payload = prompt => $prompt, size => $size, quality => $quality, n => $n;
%payload<model> = $model if $model;
return api-request('/image', 'POST', %payload, :$public-key, :$secret-key);
}
# ============================================================================
# Languages Cache
# ============================================================================
constant $LANGUAGES_CACHE_TTL = 3600; # 1 hour in seconds
#| Get languages cache file path
sub languages-cache-path() returns IO::Path {
return $*HOME.add('.unsandbox').add('languages.json');
}
#| Check if languages cache is valid (less than 1 hour old)
sub is-cache-valid() returns Bool {
my $cache-path = languages-cache-path();
return False unless $cache-path.e;
my $mtime = $cache-path.modified;
my $age = now - $mtime;
return $age < $LANGUAGES_CACHE_TTL;
}
#| Read languages from cache
sub read-languages-cache() returns Hash {
my $cache-path = languages-cache-path();
return {} unless $cache-path.e;
try {
return from-json($cache-path.slurp);
CATCH {
default { return {}; }
}
}
}
#| Write languages to cache
sub write-languages-cache(%data) {
my $cache-path = languages-cache-path();
my $dir = $cache-path.parent;
$dir.mkdir unless $dir.e;
try {
$cache-path.spurt(to-json(%data));
}
}
# ============================================================================
# Utility Functions
# ============================================================================
#| Get list of supported programming languages with caching.
#| Languages are cached in ~/.unsandbox/languages.json for 1 hour.
#|
#| Returns: Hash with languages array, count, aliases
sub languages(Str :$public-key, Str :$secret-key) returns Hash is export {
# Check cache first
if is-cache-valid() {
my %cached = read-languages-cache();
return %cached if %cached;
}
# Fetch from API
my %result = api-request('/languages', 'GET', :$public-key, :$secret-key);
# Cache result
write-languages-cache(%result);
return %result;
}
# ============================================================================
# Session Functions
# ============================================================================
#| List all sessions for this API key
sub session-list(Str :$public-key, Str :$secret-key) returns Array is export {
my %result = api-request('/sessions', 'GET', :$public-key, :$secret-key);
return %result<sessions> // [];
}
#| Get session details by ID
sub session-get(Str $session-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/sessions/{$session-id}", 'GET', :$public-key, :$secret-key);
}
#| Create a new interactive session
sub session-create(
Str :$network-mode = 'zerotrust',
Str :$shell = 'bash',
Str :$public-key,
Str :$secret-key
) returns Hash is export {
my %payload = shell => $shell, network_mode => $network-mode;
return api-request('/sessions', 'POST', %payload, :$public-key, :$secret-key);
}
#| Destroy a session
sub session-destroy(Str $session-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/sessions/{$session-id}", 'DELETE', :$public-key, :$secret-key);
return True;
}
#| Freeze a session
sub session-freeze(Str $session-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/sessions/{$session-id}/freeze", 'POST', :$public-key, :$secret-key);
return True;
}
#| Unfreeze a session
sub session-unfreeze(Str $session-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/sessions/{$session-id}/unfreeze", 'POST', :$public-key, :$secret-key);
return True;
}
#| Boost session CPU (1-8 vCPUs)
sub session-boost(Str $session-id, Int $vcpu, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = vcpu => $vcpu;
api-request("/sessions/{$session-id}/boost", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| Remove CPU boost from session
sub session-unboost(Str $session-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/sessions/{$session-id}/unboost", 'POST', :$public-key, :$secret-key);
return True;
}
#| Execute command in a session
sub session-execute(Str $session-id, Str $command, Str :$public-key, Str :$secret-key) returns Hash is export {
my %payload = command => $command;
return api-request("/sessions/{$session-id}/execute", 'POST', %payload, :$public-key, :$secret-key);
}
# ============================================================================
# Service Functions
# ============================================================================
#| List all services for this API key
sub service-list(Str :$public-key, Str :$secret-key) returns Array is export {
my %result = api-request('/services', 'GET', :$public-key, :$secret-key);
return %result<services> // [];
}
#| Get service details by ID
sub service-get(Str $service-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/services/{$service-id}", 'GET', :$public-key, :$secret-key);
}
#| Create a new service
sub service-create(
Str :$name!,
Str :$ports,
Str :$domains,
Str :$bootstrap,
Str :$network-mode,
Str :$public-key,
Str :$secret-key
) returns Str is export {
my %payload = name => $name;
%payload<ports> = $ports.split(',')>>.Int if $ports;
%payload<domains> = $domains.split(',') if $domains;
%payload<bootstrap> = $bootstrap if $bootstrap;
%payload<network_mode> = $network-mode if $network-mode;
my %result = api-request('/services', 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
#| Destroy a service
sub service-destroy(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}", 'DELETE', :$public-key, :$secret-key);
return True;
}
#| Freeze a service
sub service-freeze(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}/freeze", 'POST', :$public-key, :$secret-key);
return True;
}
#| Unfreeze a service
sub service-unfreeze(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}/unfreeze", 'POST', :$public-key, :$secret-key);
return True;
}
#| Lock a service (prevent deletion)
sub service-lock(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}/lock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Unlock a service
sub service-unlock(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}/unlock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Set unfreeze-on-demand for a service
sub service-set-unfreeze-on-demand(Str $service-id, Bool $enabled, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = unfreeze_on_demand => $enabled;
api-request("/services/{$service-id}", 'PATCH', %payload, :$public-key, :$secret-key);
return True;
}
#| Redeploy a service with optional new bootstrap
sub service-redeploy(Str $service-id, Str :$bootstrap, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload;
%payload<bootstrap> = $bootstrap if $bootstrap;
api-request("/services/{$service-id}/redeploy", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| Get service logs
sub service-logs(Str $service-id, Bool :$all = False, Str :$public-key, Str :$secret-key) returns Str is export {
my $endpoint = "/services/{$service-id}/logs";
$endpoint ~= "?all=true" if $all;
my %result = api-request($endpoint, 'GET', :$public-key, :$secret-key);
return %result<logs> // '';
}
#| Execute command in a service
sub service-execute(Str $service-id, Str $command, Int :$timeout-ms, Str :$public-key, Str :$secret-key) returns Hash is export {
my %payload = command => $command;
%payload<timeout_ms> = $timeout-ms if $timeout-ms;
return api-request("/services/{$service-id}/execute", 'POST', %payload, :$public-key, :$secret-key);
}
#| Get service environment vault
sub service-env-get(Str $service-id, Str :$public-key, Str :$secret-key) returns Str is export {
my %result = api-request("/services/{$service-id}/env", 'GET', :$public-key, :$secret-key);
return %result<content> // '';
}
#| Set service environment vault
sub service-env-set(Str $service-id, Str $content, Str :$public-key, Str :$secret-key) returns Bool is export {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key);
my $url = "{$API_BASE}/services/{$service-id}/env";
my $timestamp = now.Int;
my $signature = sign-request($sk, $timestamp, 'PUT', "/services/{$service-id}/env", $content);
my @args = 'curl', '-s', '-X', 'PUT', $url;
@args.append: '-H', 'Content-Type: text/plain';
@args.append: '-H', "Authorization: Bearer $pk";
@args.append: '-H', "X-Timestamp: $timestamp";
@args.append: '-H', "X-Signature: $signature";
@args.append: '-d', $content;
my $proc = run |@args, :out, :err;
return $proc.exitcode == 0;
}
#| Delete service environment vault
sub service-env-delete(Str $service-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/services/{$service-id}/env", 'DELETE', :$public-key, :$secret-key);
return True;
}
#| Export service environment vault
sub service-env-export(Str $service-id, Str :$public-key, Str :$secret-key) returns Str is export {
my %result = api-request("/services/{$service-id}/env/export", 'POST', :$public-key, :$secret-key);
return %result<content> // '';
}
#| Resize service (change vCPU count)
sub service-resize(Str $service-id, Int $vcpu, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = vcpu => $vcpu;
api-request("/services/{$service-id}", 'PATCH', %payload, :$public-key, :$secret-key);
return True;
}
# ============================================================================
# Snapshot Functions
# ============================================================================
#| List all snapshots for this API key
sub snapshot-list(Str :$public-key, Str :$secret-key) returns Array is export {
my %result = api-request('/snapshots', 'GET', :$public-key, :$secret-key);
return %result<snapshots> // [];
}
#| Get snapshot details by ID
sub snapshot-get(Str $snapshot-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/snapshots/{$snapshot-id}", 'GET', :$public-key, :$secret-key);
}
#| Create snapshot from a session
sub snapshot-session(Str $session-id, Str :$name, Bool :$hot = False, Str :$public-key, Str :$secret-key) returns Str is export {
my %payload = session_id => $session-id, hot => $hot;
%payload<name> = $name if $name;
my %result = api-request('/snapshots', 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
#| Create snapshot from a service
sub snapshot-service(Str $service-id, Str :$name, Bool :$hot = False, Str :$public-key, Str :$secret-key) returns Str is export {
my %payload = service_id => $service-id, hot => $hot;
%payload<name> = $name if $name;
my %result = api-request('/snapshots', 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
#| Restore a snapshot
sub snapshot-restore(Str $snapshot-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/snapshots/{$snapshot-id}/restore", 'POST', :$public-key, :$secret-key);
return True;
}
#| Delete a snapshot
sub snapshot-delete(Str $snapshot-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/snapshots/{$snapshot-id}", 'DELETE', :$public-key, :$secret-key);
return True;
}
#| Lock a snapshot (prevent deletion)
sub snapshot-lock(Str $snapshot-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/snapshots/{$snapshot-id}/lock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Unlock a snapshot
sub snapshot-unlock(Str $snapshot-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/snapshots/{$snapshot-id}/unlock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Clone a snapshot to create a new session or service
sub snapshot-clone(
Str $snapshot-id,
Str :$clone-type!, # "session" or "service"
Str :$name, # name for cloned service
Str :$ports, # ports for cloned service
Str :$shell, # shell for cloned session
Str :$public-key,
Str :$secret-key
) returns Str is export {
my %payload = clone_type => $clone-type;
%payload<name> = $name if $name;
%payload<ports> = $ports.split(',')>>.Int if $ports;
%payload<shell> = $shell if $shell;
my %result = api-request("/snapshots/{$snapshot-id}/clone", 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
# ============================================================================
# Image Functions
# ============================================================================
#| List images (filter: owned, shared, public, or all)
sub image-list(Str :$filter, Str :$public-key, Str :$secret-key) returns Array is export {
my $endpoint = '/images';
$endpoint ~= "?filter={$filter}" if $filter;
my %result = api-request($endpoint, 'GET', :$public-key, :$secret-key);
return %result<images> // [];
}
#| Get image details by ID
sub image-get(Str $image-id, Str :$public-key, Str :$secret-key) returns Hash is export {
return api-request("/images/{$image-id}", 'GET', :$public-key, :$secret-key);
}
#| Publish an image from a service or snapshot
sub image-publish(
Str :$source-type!, # "service" or "snapshot"
Str :$source-id!,
Str :$name,
Str :$description,
Str :$public-key,
Str :$secret-key
) returns Str is export {
my %payload = source_type => $source-type, source_id => $source-id;
%payload<name> = $name if $name;
%payload<description> = $description if $description;
my %result = api-request('/images/publish', 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
#| Delete an image
sub image-delete(Str $image-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/images/{$image-id}", 'DELETE', :$public-key, :$secret-key);
return True;
}
#| Lock an image (prevent deletion)
sub image-lock(Str $image-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/images/{$image-id}/lock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Unlock an image
sub image-unlock(Str $image-id, Str :$public-key, Str :$secret-key) returns Bool is export {
api-request("/images/{$image-id}/unlock", 'POST', :$public-key, :$secret-key);
return True;
}
#| Set image visibility (private, unlisted, public)
sub image-set-visibility(Str $image-id, Str $visibility, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = visibility => $visibility;
api-request("/images/{$image-id}/visibility", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| Grant access to an image for another API key
sub image-grant-access(Str $image-id, Str $trusted-api-key, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = trusted_api_key => $trusted-api-key;
api-request("/images/{$image-id}/access/grant", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| Revoke access to an image from another API key
sub image-revoke-access(Str $image-id, Str $trusted-api-key, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = trusted_api_key => $trusted-api-key;
api-request("/images/{$image-id}/access/revoke", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| List trusted API keys for an image
sub image-list-trusted(Str $image-id, Str :$public-key, Str :$secret-key) returns Array is export {
my %result = api-request("/images/{$image-id}/access", 'GET', :$public-key, :$secret-key);
return %result<trusted_keys> // [];
}
#| Transfer image ownership to another API key
sub image-transfer(Str $image-id, Str $to-api-key, Str :$public-key, Str :$secret-key) returns Bool is export {
my %payload = to_api_key => $to-api-key;
api-request("/images/{$image-id}/transfer", 'POST', %payload, :$public-key, :$secret-key);
return True;
}
#| Spawn a new service from an image
sub image-spawn(
Str $image-id,
Str :$name,
Str :$ports,
Str :$bootstrap,
Str :$network-mode,
Str :$public-key,
Str :$secret-key
) returns Str is export {
my %payload;
%payload<name> = $name if $name;
%payload<ports> = $ports.split(',')>>.Int if $ports;
%payload<bootstrap> = $bootstrap if $bootstrap;
%payload<network_mode> = $network-mode if $network-mode;
my %result = api-request("/images/{$image-id}/spawn", 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
#| Clone an image
sub image-clone(Str $image-id, Str :$name, Str :$description, Str :$public-key, Str :$secret-key) returns Str is export {
my %payload;
%payload<name> = $name if $name;
%payload<description> = $description if $description;
my %result = api-request("/images/{$image-id}/clone", 'POST', %payload, :$public-key, :$secret-key);
return %result<id> // '';
}
# ============================================================================
# PaaS Logs Functions
# ============================================================================
#| Fetch batch logs from portal
#| source: "all", "api", "portal", "pool/cammy", "pool/ai"
#| lines: number of lines (1-10000)
#| since: time window ("1m", "5m", "1h", "1d")
#| grep: optional filter pattern
sub logs-fetch(
Str :$source = 'all',
Int :$lines = 100,
Str :$since = '1h',
Str :$grep,
Str :$public-key,
Str :$secret-key
) returns Str is export {
my $endpoint = "/logs?source={$source}&lines={$lines}&since={$since}";
$endpoint ~= "&grep={uri-encode($grep)}" if $grep;
my %result = api-request($endpoint, 'GET', :$public-key, :$secret-key);
return to-json(%result);
}
#| Stream logs via SSE (blocking call)
#| Returns when interrupted or server closes connection
sub logs-stream(
Str :$source = 'all',
Str :$grep,
:&callback,
Str :$public-key,
Str :$secret-key
) returns Bool is export {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key);
my $endpoint = "/logs/stream?source={$source}";
$endpoint ~= "&grep={uri-encode($grep)}" if $grep;
my $timestamp = now.Int;
my $signature = sign-request($sk, $timestamp, 'GET', $endpoint, '');
my @args = 'curl', '-s', '-N', "{$API_BASE}{$endpoint}";
@args.append: '-H', "Authorization: Bearer $pk";
@args.append: '-H', "X-Timestamp: $timestamp";
@args.append: '-H', "X-Signature: $signature";
@args.append: '-H', 'Accept: text/event-stream';
my $proc = run |@args, :out;
for $proc.out.lines -> $line {
if $line.starts-with('data: ') {
my $data = $line.substr(6);
&callback($source, $data) if &callback;
}
}
return True;
}
# ============================================================================
# Key Validation
# ============================================================================
#| Validate API keys and get account info
sub validate-keys(Str :$public-key, Str :$secret-key) returns Hash is export {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key);
my $url = "{$PORTAL_BASE}/keys/validate";
my $timestamp = now.Int;
my $signature = sign-request($sk, $timestamp, 'POST', '/keys/validate', '');
my @args = 'curl', '-s', '-X', 'POST', $url;
@args.append: '-H', 'Content-Type: application/json';
@args.append: '-H', "Authorization: Bearer $pk";
@args.append: '-H', "X-Timestamp: $timestamp";
@args.append: '-H', "X-Signature: $signature";
my $proc = run |@args, :out;
my $resp = $proc.out.slurp;
return from-json($resp);
}
# ============================================================================
# Utility Functions
# ============================================================================
#| Check API health
sub health-check(Str :$public-key, Str :$secret-key) returns Bool is export {
try {
my %result = api-request('/health', 'GET', :$public-key, :$secret-key);
return %result<status> eq 'ok';
CATCH { default { return False; } }
}
}
#| Get SDK version
sub version() returns Str is export {
return '0.1.0';
}
#| Detect programming language from file extension or shebang
#|
#| Returns: Language name or Nil if undetected
sub detect-language(Str $filename) returns Str is export {
my $ext = $filename.IO.extension;
return %EXT_MAP{$ext} if %EXT_MAP{$ext}:exists;
# Try reading shebang
if $filename.IO.e {
my $first-line = $filename.IO.lines.head;
if $first-line.starts-with('#!') {
return 'python' if $first-line.contains('python');
return 'javascript' if $first-line.contains('node');
return 'ruby' if $first-line.contains('ruby');
return 'perl' if $first-line.contains('perl');
return 'bash' if $first-line.contains('bash') || $first-line.contains('/sh');
return 'lua' if $first-line.contains('lua');
return 'php' if $first-line.contains('php');
}
}
return Nil;
}
# ============================================================================
# Client Class
# ============================================================================
#| Unsandbox API client with stored credentials
#|
#| Example:
#| my $client = Client.new(:public-key<unsb-pk-...>, :secret-key<unsb-sk-...>);
#| my %result = $client.execute("python", 'print("Hello")');
#|
#| # Or load from environment/config automatically:
#| my $client = Client.new;
#| my %result = $client.execute("python", $code);
class Client is export {
has Str $.public-key;
has Str $.secret-key;
#| Initialize client with credentials
#|
#| Parameters:
#| :$public-key - API public key (unsb-pk-...)
#| :$secret-key - API secret key (unsb-sk-...)
#| :$account-index - Account index in ~/.unsandbox/accounts.csv (default 0)
method new(Str :$public-key, Str :$secret-key, Int :$account-index = 0) {
my ($pk, $sk) = get-credentials(:$public-key, :$secret-key, :$account-index);
self.bless(:public-key($pk), :secret-key($sk));
}
#| Execute code synchronously. See module execute() for parameters.
method execute(Str $language, Str $code, *%opts) returns Hash {
return execute($language, $code, :$.public-key, :$.secret-key, |%opts);
}
#| Execute code asynchronously. See module execute-async() for parameters.
method execute-async(Str $language, Str $code, *%opts) returns Hash {
return execute-async($language, $code, :$.public-key, :$.secret-key, |%opts);
}
#| Execute with auto-detect. See module run() for parameters.
method run(Str $code, *%opts) returns Hash {
return run($code, :$.public-key, :$.secret-key, |%opts);
}
#| Execute async with auto-detect. See module run-async() for parameters.
method run-async(Str $code, *%opts) returns Hash {
return run-async($code, :$.public-key, :$.secret-key, |%opts);
}
#| Get job status. See module get-job() for details.
method get-job(Str $job-id) returns Hash {
return get-job($job-id, :$.public-key, :$.secret-key);
}
#| Wait for job completion. See module wait() for details.
method wait(Str $job-id, *%opts) returns Hash {
return wait($job-id, :$.public-key, :$.secret-key, |%opts);
}
#| Cancel a job. See module cancel-job() for details.
method cancel-job(Str $job-id) returns Hash {
return cancel-job($job-id, :$.public-key, :$.secret-key);
}
#| List active jobs. See module list-jobs() for details.
method list-jobs() returns Array {
return list-jobs(:$.public-key, :$.secret-key);
}
#| Generate image. See module image() for parameters.
method image(Str $prompt, *%opts) returns Hash {
return image($prompt, :$.public-key, :$.secret-key, |%opts);
}
#| Get supported languages.
method languages() returns Hash {
return languages(:$.public-key, :$.secret-key);
}
# Session methods
method session-list() returns Array { return session-list(:$.public-key, :$.secret-key); }
method session-get(Str $id) returns Hash { return session-get($id, :$.public-key, :$.secret-key); }
method session-create(*%opts) returns Hash { return session-create(:$.public-key, :$.secret-key, |%opts); }
method session-destroy(Str $id) returns Bool { return session-destroy($id, :$.public-key, :$.secret-key); }
method session-freeze(Str $id) returns Bool { return session-freeze($id, :$.public-key, :$.secret-key); }
method session-unfreeze(Str $id) returns Bool { return session-unfreeze($id, :$.public-key, :$.secret-key); }
method session-boost(Str $id, Int $vcpu) returns Bool { return session-boost($id, $vcpu, :$.public-key, :$.secret-key); }
method session-unboost(Str $id) returns Bool { return session-unboost($id, :$.public-key, :$.secret-key); }
method session-execute(Str $id, Str $cmd) returns Hash { return session-execute($id, $cmd, :$.public-key, :$.secret-key); }
# Service methods
method service-list() returns Array { return service-list(:$.public-key, :$.secret-key); }
method service-get(Str $id) returns Hash { return service-get($id, :$.public-key, :$.secret-key); }
method service-create(*%opts) returns Str { return service-create(:$.public-key, :$.secret-key, |%opts); }
method service-destroy(Str $id) returns Bool { return service-destroy($id, :$.public-key, :$.secret-key); }
method service-freeze(Str $id) returns Bool { return service-freeze($id, :$.public-key, :$.secret-key); }
method service-unfreeze(Str $id) returns Bool { return service-unfreeze($id, :$.public-key, :$.secret-key); }
method service-lock(Str $id) returns Bool { return service-lock($id, :$.public-key, :$.secret-key); }
method service-unlock(Str $id) returns Bool { return service-unlock($id, :$.public-key, :$.secret-key); }
method service-redeploy(Str $id, *%opts) returns Bool { return service-redeploy($id, :$.public-key, :$.secret-key, |%opts); }
method service-logs(Str $id, *%opts) returns Str { return service-logs($id, :$.public-key, :$.secret-key, |%opts); }
method service-execute(Str $id, Str $cmd, *%opts) returns Hash { return service-execute($id, $cmd, :$.public-key, :$.secret-key, |%opts); }
method service-resize(Str $id, Int $vcpu) returns Bool { return service-resize($id, $vcpu, :$.public-key, :$.secret-key); }
# Snapshot methods
method snapshot-list() returns Array { return snapshot-list(:$.public-key, :$.secret-key); }
method snapshot-get(Str $id) returns Hash { return snapshot-get($id, :$.public-key, :$.secret-key); }
method snapshot-session(Str $id, *%opts) returns Str { return snapshot-session($id, :$.public-key, :$.secret-key, |%opts); }
method snapshot-service(Str $id, *%opts) returns Str { return snapshot-service($id, :$.public-key, :$.secret-key, |%opts); }
method snapshot-restore(Str $id) returns Bool { return snapshot-restore($id, :$.public-key, :$.secret-key); }
method snapshot-delete(Str $id) returns Bool { return snapshot-delete($id, :$.public-key, :$.secret-key); }
method snapshot-lock(Str $id) returns Bool { return snapshot-lock($id, :$.public-key, :$.secret-key); }
method snapshot-unlock(Str $id) returns Bool { return snapshot-unlock($id, :$.public-key, :$.secret-key); }
method snapshot-clone(Str $id, *%opts) returns Str { return snapshot-clone($id, :$.public-key, :$.secret-key, |%opts); }
# Image methods
method image-list(*%opts) returns Array { return image-list(:$.public-key, :$.secret-key, |%opts); }
method image-get(Str $id) returns Hash { return image-get($id, :$.public-key, :$.secret-key); }
method image-publish(*%opts) returns Str { return image-publish(:$.public-key, :$.secret-key, |%opts); }
method image-delete(Str $id) returns Bool { return image-delete($id, :$.public-key, :$.secret-key); }
method image-lock(Str $id) returns Bool { return image-lock($id, :$.public-key, :$.secret-key); }
method image-unlock(Str $id) returns Bool { return image-unlock($id, :$.public-key, :$.secret-key); }
method image-set-visibility(Str $id, Str $v) returns Bool { return image-set-visibility($id, $v, :$.public-key, :$.secret-key); }
method image-grant-access(Str $id, Str $key) returns Bool { return image-grant-access($id, $key, :$.public-key, :$.secret-key); }
method image-revoke-access(Str $id, Str $key) returns Bool { return image-revoke-access($id, $key, :$.public-key, :$.secret-key); }
method image-list-trusted(Str $id) returns Array { return image-list-trusted($id, :$.public-key, :$.secret-key); }
method image-transfer(Str $id, Str $key) returns Bool { return image-transfer($id, $key, :$.public-key, :$.secret-key); }
method image-spawn(Str $id, *%opts) returns Str { return image-spawn($id, :$.public-key, :$.secret-key, |%opts); }
method image-clone(Str $id, *%opts) returns Str { return image-clone($id, :$.public-key, :$.secret-key, |%opts); }
# Logs methods
method logs-fetch(*%opts) returns Str { return logs-fetch(:$.public-key, :$.secret-key, |%opts); }
method logs-stream(*%opts) returns Bool { return logs-stream(:$.public-key, :$.secret-key, |%opts); }
# Utility methods
method validate-keys() returns Hash { return validate-keys(:$.public-key, :$.secret-key); }
method health-check() returns Bool { return health-check(:$.public-key, :$.secret-key); }
method version() returns Str { return version(); }
}
# ============================================================================
# CLI Interface
# ============================================================================
sub uri-encode(Str $s) {
return $s.subst(/<-[A-Za-z0-9\-_.~]>/, { .encode.list.map({ '%' ~ .fmt('%02X') }).join }, :g);
}
sub cmd-execute(@args) {
my ($public-key, $secret-key) = get-credentials();
my $source-file = '';
my %env-vars;
my @input-files;
my $artifacts = False;
my $output-dir = '.';
my $network = '';
my $vcpu = 0;
# Parse arguments
my $i = 0;
while $i < @args.elems {
given @args[$i] {
when '-e' {
$i++;
my ($key, $value) = @args[$i].split('=', 2);
%env-vars{$key} = $value;
}
when '-f' {
$i++;
@input-files.push(@args[$i]);
}
when '-a' {
$artifacts = True;
}
when '-o' {
$i++;
$output-dir = @args[$i];
}
when '-n' {
$i++;
$network = @args[$i];
}
when '-v' {
$i++;
$vcpu = @args[$i].Int;
}
default {
if @args[$i].starts-with('-') {
note "$RED\Unknown option: {@args[$i]}$RESET";
exit 1;
} else {
$source-file = @args[$i];
}
}
}
$i++;
}
unless $source-file {
note "Usage: un.raku [options] <source_file>";
exit 1;
}
unless $source-file.IO.e {
note "{$RED}Error: File not found: $source-file{$RESET}";
exit 1;
}
# Read source file
my $code = $source-file.IO.slurp;
my $language = detect-language($source-file);
unless $language {
note "{$RED}Error: Cannot detect language for $source-file{$RESET}";
exit 1;
}
# Build request payload
my %payload = language => $language, code => $code;
# Add environment variables
%payload<env> = %env-vars if %env-vars;
# Add input files
if @input-files {
my @files;
for @input-files -> $filepath {
unless $filepath.IO.e {
note "{$RED}Error: Input file not found: $filepath{$RESET}";
exit 1;
}
my $content = $filepath.IO.slurp(:bin);
@files.push({
filename => $filepath.IO.basename,
content_base64 => $content.encode('latin1').decode('latin1').encode.base64
});
}
%payload<input_files> = @files;
}
# Add options
%payload<return_artifacts> = True if $artifacts;
%payload<network> = $network if $network;
%payload<vcpu> = $vcpu if $vcpu > 0;
# Execute
my %result = api-request('/execute', 'POST', %payload, :$public-key, :$secret-key);
# Print output
if %result<stdout> {
print "{$BLUE}{%result<stdout>}{$RESET}";
}
if %result<stderr> {
note "{$RED}{%result<stderr>}{$RESET}";
}
# Save artifacts
if $artifacts && %result<artifacts> {
mkdir $output-dir unless $output-dir.IO.d;
for %result<artifacts>.list -> %artifact {
my $filename = %artifact<filename>;
my $content = %artifact<content_base64>.decode('base64');
my $path = "$output-dir/$filename";
$path.IO.spurt($content, :bin);
run 'chmod', '755', $path;
note "{$GREEN}Saved: $path{$RESET}";
}
}
exit %result<exit_code> // 0;
}
sub cmd-session(@args) {
my ($public-key, $secret-key) = get-credentials();
my $list-mode = False;
my $kill-id = '';
my $shell = '';
my $network = '';
my $vcpu = 0;
my @input-files;
# Parse arguments
my $i = 0;
while $i < @args.elems {
given @args[$i] {
when '--list' {
$list-mode = True;
}
when '--kill' {
$i++;
$kill-id = @args[$i];
}
when '--shell' {
$i++;
$shell = @args[$i];
}
when '-n' {
$i++;
$network = @args[$i];
}
when '-v' {
$i++;
$vcpu = @args[$i].Int;
}
when '-f' {
$i++;
@input-files.push(@args[$i]);
}
}
$i++;
}
if $list-mode {
my %result = api-request('/sessions', 'GET', :$public-key, :$secret-key);
my @sessions = %result<sessions>.list;
unless @sessions {
say "No active sessions";
return;
}
say sprintf("%-40s %-10s %-10s %s", 'ID', 'Shell', 'Status', 'Created');
for @sessions -> %s {
say sprintf("%-40s %-10s %-10s %s",
%s<id>, %s<shell>, %s<status>, %s<created_at>);
}
return;
}
if $kill-id {
api-request("/sessions/$kill-id", 'DELETE', :$public-key, :$secret-key);
say "{$GREEN}Session terminated: $kill-id{$RESET}";
return;
}
# Create new session
my %payload = shell => ($shell || 'bash');
%payload<network> = $network if $network;
%payload<vcpu> = $vcpu if $vcpu > 0;
# Add input files
if @input-files {
my @files;
for @input-files -> $filepath {
unless $filepath.IO.e {
note "{$RED}Error: Input file not found: $filepath{$RESET}";
exit 1;
}
my $content = $filepath.IO.slurp(:bin);
@files.push({
filename => $filepath.IO.basename,
content_base64 => $content.encode('latin1').decode('latin1').encode.base64
});
}
%payload<input_files> = @files;
}
say "{$YELLOW}Creating session...{$RESET}";
my %result = api-request('/sessions', 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Session created: {%result<id>}{$RESET}";
say "{$YELLOW}(Interactive sessions require WebSocket - use un2 for full support){$RESET}";
}
sub cmd-service(@args) {
my ($public-key, $secret-key) = get-credentials();
my $list-mode = False;
my $info-id = '';
my $logs-id = '';
my $sleep-id = '';
my $wake-id = '';
my $destroy-id = '';
my $resize-id = '';
my $set-unfreeze-on-demand-id = '';
my $set-unfreeze-on-demand-val = False;
my $name = '';
my $ports = '';
my $type = '';
my $bootstrap = '';
my $bootstrap-file = '';
my $network = '';
my $vcpu = 0;
my $unfreeze-on-demand = False;
my @input-files;
# Parse arguments
my $i = 0;
while $i < @args.elems {
given @args[$i] {
when '--list' {
$list-mode = True;
}
when '--info' {
$i++;
$info-id = @args[$i];
}
when '--logs' {
$i++;
$logs-id = @args[$i];
}
when '--freeze' {
$i++;
$sleep-id = @args[$i];
}
when '--unfreeze' {
$i++;
$wake-id = @args[$i];
}
when '--destroy' {
$i++;
$destroy-id = @args[$i];
}
when '--resize' {
$i++;
$resize-id = @args[$i];
}
when '--set-unfreeze-on-demand' {
$i++;
$set-unfreeze-on-demand-id = @args[$i];
$i++;
my $val = @args[$i];
$set-unfreeze-on-demand-val = ($val eq 'true' || $val eq '1');
}
when '--unfreeze-on-demand' {
$unfreeze-on-demand = True;
}
when '--name' {
$i++;
$name = @args[$i];
}
when '--ports' {
$i++;
$ports = @args[$i];
}
when '--type' {
$i++;
$type = @args[$i];
}
when '--bootstrap' {
$i++;
$bootstrap = @args[$i];
}
when '--bootstrap-file' {
$i++;
$bootstrap-file = @args[$i];
}
when '-n' {
$i++;
$network = @args[$i];
}
when '-v' {
$i++;
$vcpu = @args[$i].Int;
}
when '-f' {
$i++;
@input-files.push(@args[$i]);
}
}
$i++;
}
if $list-mode {
my %result = api-request('/services', 'GET', :$public-key, :$secret-key);
my @services = %result<services>.list;
unless @services {
say "No services";
return;
}
say sprintf("%-20s %-15s %-10s %-15s %s", 'ID', 'Name', 'Status', 'Ports', 'Domains');
for @services -> %s {
my $port-str = %s<ports>.join(',');
my $domain-str = %s<domains>.join(',');
say sprintf("%-20s %-15s %-10s %-15s %s",
%s<id>, %s<name>, %s<status>, $port-str, $domain-str);
}
return;
}
if $info-id {
my %result = api-request("/services/$info-id", 'GET', :$public-key, :$secret-key);
say to-json(%result, :pretty);
return;
}
if $logs-id {
my %result = api-request("/services/$logs-id/logs", 'GET', :$public-key, :$secret-key);
say %result<logs>;
return;
}
if $sleep-id {
api-request("/services/$sleep-id/freeze", 'POST', :$public-key, :$secret-key);
say "{$GREEN}Service frozen: $sleep-id{$RESET}";
return;
}
if $wake-id {
api-request("/services/$wake-id/unfreeze", 'POST', :$public-key, :$secret-key);
say "{$GREEN}Service unfreezing: $wake-id{$RESET}";
return;
}
if $destroy-id {
my ($status, $body) = api-request-with-status("/services/$destroy-id", 'DELETE', :$public-key, :$secret-key);
if $status == 428 {
if handle-sudo-challenge($body, "/services/$destroy-id", 'DELETE', :$public-key, :$secret-key) {
say "{$GREEN}Service destroyed: $destroy-id{$RESET}";
} else {
note "{$RED}Error: Failed to destroy service (OTP verification failed){$RESET}";
exit 1;
}
} elsif $status >= 200 && $status < 300 {
say "{$GREEN}Service destroyed: $destroy-id{$RESET}";
} else {
note "{$RED}Error: Failed to destroy service (HTTP $status){$RESET}";
exit 1;
}
return;
}
if $resize-id {
unless $vcpu >= 1 && $vcpu <= 8 {
note "{$RED}Error: --resize requires --vcpu N (1-8){$RESET}";
exit 1;
}
my %payload = vcpu => $vcpu;
api-request("/services/$resize-id", 'PATCH', %payload, :$public-key, :$secret-key);
my $ram = $vcpu * 2;
say "{$GREEN}Service resized to $vcpu vCPU, $ram GB RAM{$RESET}";
return;
}
if $set-unfreeze-on-demand-id {
my %payload = unfreeze_on_demand => $set-unfreeze-on-demand-val;
api-request("/services/$set-unfreeze-on-demand-id", 'PATCH', %payload, :$public-key, :$secret-key);
my $status = $set-unfreeze-on-demand-val ?? 'enabled' !! 'disabled';
say "{$GREEN}Unfreeze-on-demand $status for service: $set-unfreeze-on-demand-id{$RESET}";
return;
}
# Create new service
if $name {
my %payload = name => $name;
if $ports {
%payload<ports> = $ports.split(',')>>.Int;
}
if $type {
%payload<service_type> = $type;
}
if $bootstrap {
%payload<bootstrap> = $bootstrap;
}
if $bootstrap-file {
if $bootstrap-file.IO.e && $bootstrap-file.IO.f {
%payload<bootstrap_content> = $bootstrap-file.IO.slurp;
} else {
note "{$RED}Error: Bootstrap file not found: $bootstrap-file{$RESET}";
exit 1;
}
}
%payload<network> = $network if $network;
%payload<vcpu> = $vcpu if $vcpu > 0;
%payload<unfreeze_on_demand> = True if $unfreeze-on-demand;
# Add input files
if @input-files {
my @files;
for @input-files -> $filepath {
unless $filepath.IO.e {
note "{$RED}Error: Input file not found: $filepath{$RESET}";
exit 1;
}
my $content = $filepath.IO.slurp(:bin);
@files.push({
filename => $filepath.IO.basename,
content_base64 => $content.encode('latin1').decode('latin1').encode.base64
});
}
%payload<input_files> = @files;
}
my %result = api-request('/services', 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Service created: {%result<id>}{$RESET}";
say "Name: {%result<name>}";
say "URL: {%result<url>}" if %result<url>;
return;
}
note "{$RED}Error: Specify --name to create a service, or use --list, --info, etc.{$RESET}";
exit 1;
}
sub cmd-languages(@args) {
my ($public-key, $secret-key) = get-credentials();
my $json-output = False;
for @args -> $arg {
if $arg eq '--json' {
$json-output = True;
}
}
my %result = languages(:$public-key, :$secret-key);
my @langs = %result<languages>.list;
if $json-output {
# JSON array output
say to-json(@langs);
} else {
# One language per line (default)
for @langs -> $lang {
say $lang;
}
}
}
sub cmd-key(@args) {
my ($public-key, $secret-key) = get-credentials();
my $extend = False;
for @args -> $arg {
if $arg eq '--extend' {
$extend = True;
}
}
# Validate key (using portal endpoint)
my $url = $PORTAL_BASE ~ "/keys/validate";
my @curl-args = 'curl', '-s', '-X', 'POST';
@curl-args.append: $url;
@curl-args.append: '-H', 'Content-Type: application/json';
@curl-args.append: '-H', "Authorization: Bearer $public-key";
my $timestamp = now.Int;
my $sig-input = "{$timestamp}:POST:/keys/validate:";
my $signature = hmac-hex($sig-input, $secret-key, &sha256);
@curl-args.append: '-H', "X-Timestamp: $timestamp";
@curl-args.append: '-H', "X-Signature: $signature";
my $proc = run |@curl-args, :out, :err;
my $body = $proc.out.slurp;
my %result = from-json($body);
if $extend {
my $pk = %result<public_key>;
if $pk {
say "{$BLUE}Opening browser to extend key...{$RESET}";
run 'xdg-open', "$PORTAL_BASE/keys/extend?pk=$pk";
return;
} else {
note "{$RED}Error: Could not retrieve public key{$RESET}";
exit 1;
}
}
if %result<expired> {
say "{$RED}Expired{$RESET}";
say "Public Key: {%result<public_key> // 'N/A'}";
say "Tier: {%result<tier> // 'N/A'}";
say "Expired: {%result<expires_at> // 'N/A'}";
say "{$YELLOW}To renew: Visit https://unsandbox.com/keys/extend{$RESET}";
exit 1;
}
say "{$GREEN}Valid{$RESET}";
say "Public Key: {%result<public_key> // 'N/A'}";
say "Tier: {%result<tier> // 'N/A'}";
say "Status: {%result<status> // 'N/A'}";
say "Expires: {%result<expires_at> // 'N/A'}";
say "Time Remaining: {%result<time_remaining> // 'N/A'}";
say "Rate Limit: {%result<rate_limit> // 'N/A'}";
say "Burst: {%result<burst> // 'N/A'}";
say "Concurrency: {%result<concurrency> // 'N/A'}";
}
sub cmd-image(@args) {
my ($public-key, $secret-key) = get-credentials();
my $list-mode = False;
my $info-id = '';
my $delete-id = '';
my $lock-id = '';
my $unlock-id = '';
my $publish-id = '';
my $source-type = '';
my $visibility-id = '';
my $visibility-mode = '';
my $spawn-id = '';
my $clone-id = '';
my $name = '';
my $ports = '';
# Parse arguments
my $i = 0;
while $i < @args.elems {
given @args[$i] {
when '--list' {
$list-mode = True;
}
when '-l' {
$list-mode = True;
}
when '--info' {
$i++;
$info-id = @args[$i];
}
when '--delete' {
$i++;
$delete-id = @args[$i];
}
when '--lock' {
$i++;
$lock-id = @args[$i];
}
when '--unlock' {
$i++;
$unlock-id = @args[$i];
}
when '--publish' {
$i++;
$publish-id = @args[$i];
}
when '--source-type' {
$i++;
$source-type = @args[$i];
}
when '--visibility' {
$i++;
$visibility-id = @args[$i];
$i++;
$visibility-mode = @args[$i] if $i < @args.elems && !@args[$i].starts-with('-');
}
when '--spawn' {
$i++;
$spawn-id = @args[$i];
}
when '--clone' {
$i++;
$clone-id = @args[$i];
}
when '--name' {
$i++;
$name = @args[$i];
}
when '--ports' {
$i++;
$ports = @args[$i];
}
}
$i++;
}
if $list-mode {
my %result = api-request('/images', 'GET', :$public-key, :$secret-key);
my @images = %result<images>.list;
unless @images {
say "No images found";
return;
}
say sprintf("%-40s %-20s %-12s %s", 'ID', 'Name', 'Visibility', 'Created');
for @images -> %img {
say sprintf("%-40s %-20s %-12s %s",
%img<id> // 'N/A', %img<name> // '-', %img<visibility> // 'N/A', %img<created_at> // 'N/A');
}
return;
}
if $info-id {
my %result = api-request("/images/$info-id", 'GET', :$public-key, :$secret-key);
say "{$BLUE}Image Details{$RESET}";
say "";
say "Image ID: {%result<id> // 'N/A'}";
say "Name: {%result<name> // '-'}";
say "Visibility: {%result<visibility> // 'N/A'}";
say "Created: {%result<created_at> // 'N/A'}";
return;
}
if $delete-id {
my ($status, $body) = api-request-with-status("/images/$delete-id", 'DELETE', :$public-key, :$secret-key);
if $status == 428 {
if handle-sudo-challenge($body, "/images/$delete-id", 'DELETE', :$public-key, :$secret-key) {
say "{$GREEN}Image deleted successfully{$RESET}";
} else {
note "{$RED}Error: Failed to delete image (OTP verification failed){$RESET}";
exit 1;
}
} elsif $status >= 200 && $status < 300 {
say "{$GREEN}Image deleted successfully{$RESET}";
} else {
note "{$RED}Error: Failed to delete image (HTTP $status){$RESET}";
exit 1;
}
return;
}
if $lock-id {
api-request("/images/$lock-id/lock", 'POST', :$public-key, :$secret-key);
say "{$GREEN}Image locked successfully{$RESET}";
return;
}
if $unlock-id {
my ($status, $body) = api-request-with-status("/images/$unlock-id/unlock", 'POST', :$public-key, :$secret-key);
if $status == 428 {
if handle-sudo-challenge($body, "/images/$unlock-id/unlock", 'POST', :$public-key, :$secret-key) {
say "{$GREEN}Image unlocked successfully{$RESET}";
} else {
note "{$RED}Error: Failed to unlock image (OTP verification failed){$RESET}";
exit 1;
}
} elsif $status >= 200 && $status < 300 {
say "{$GREEN}Image unlocked successfully{$RESET}";
} else {
note "{$RED}Error: Failed to unlock image (HTTP $status){$RESET}";
exit 1;
}
return;
}
if $publish-id {
unless $source-type {
note "{$RED}Error: --source-type required for --publish (service or snapshot){$RESET}";
exit 1;
}
my %payload = source_type => $source-type, source_id => $publish-id;
%payload<name> = $name if $name;
my %result = api-request('/images/publish', 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Image published successfully{$RESET}";
say "Image ID: {%result<id> // 'N/A'}";
return;
}
if $visibility-id {
unless $visibility-mode {
note "{$RED}Error: visibility mode required (private, unlisted, or public){$RESET}";
exit 1;
}
my %payload = visibility => $visibility-mode;
api-request("/images/$visibility-id/visibility", 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Image visibility set to $visibility-mode{$RESET}";
return;
}
if $spawn-id {
my %payload;
%payload<name> = $name if $name;
if $ports {
%payload<ports> = $ports.split(',')>>.Int;
}
my %result = api-request("/images/$spawn-id/spawn", 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Service spawned from image{$RESET}";
say "Service ID: {%result<id> // 'N/A'}";
return;
}
if $clone-id {
my %payload;
%payload<name> = $name if $name;
my %result = api-request("/images/$clone-id/clone", 'POST', %payload, :$public-key, :$secret-key);
say "{$GREEN}Image cloned successfully{$RESET}";
say "Image ID: {%result<id> // 'N/A'}";
return;
}
note "{$RED}Error: Specify --list, --info ID, --delete ID, --lock ID, --unlock ID, --publish ID, --visibility ID MODE, --spawn ID, or --clone ID{$RESET}";
exit 1;
}
sub cmd-snapshot(@args) {
my ($public-key, $secret-key) = get-credentials();
my $list-mode = False;
my $info-id = '';
my $delete-id = '';
my $lock-id = '';
my $unlock-id = '';
my $restore-id = '';
my $clone-id = '';
my $session-id = '';
my $service-id = '';
my $name = '';
my $hot = False;
my $clone-type = '';
my $ports = '';
my $shell = '';
# Parse arguments
my $i = 0;
while $i < @args.elems {
given @args[$i] {
when '--list' | '-l' { $list-mode = True; }
when '--info' { $i++; $info-id = @args[$i]; }
when '--delete' { $i++; $delete-id = @args[$i]; }
when '--lock' { $i++; $lock-id = @args[$i]; }
when '--unlock' { $i++; $unlock-id = @args[$i]; }
when '--restore' { $i++; $restore-id = @args[$i]; }
when '--clone' { $i++; $clone-id = @args[$i]; }
when '--session' { $i++; $session-id = @args[$i]; }
when '--service' { $i++; $service-id = @args[$i]; }
when '--name' { $i++; $name = @args[$i]; }
when '--hot' { $hot = True; }
when '--clone-type' { $i++; $clone-type = @args[$i]; }
when '--ports' { $i++; $ports = @args[$i]; }
when '--shell' { $i++; $shell = @args[$i]; }
}
$i++;
}
if $list-mode {
my @snapshots = snapshot-list(:$public-key, :$secret-key);
unless @snapshots {
say "No snapshots found";
return;
}
say sprintf("%-40s %-20s %-10s %-10s %s", 'ID', 'Name', 'Type', 'Locked', 'Created');
for @snapshots -> %s {
say sprintf("%-40s %-20s %-10s %-10s %s",
%s<id> // 'N/A', %s<name> // '-', %s<type> // 'N/A',
%s<locked> ?? 'Yes' !! 'No', %s<created_at> // 'N/A');
}
return;
}
if $info-id {
my %result = snapshot-get($info-id, :$public-key, :$secret-key);
say to-json(%result, :pretty);
return;
}
if $delete-id {
my ($status, $body) = api-request-with-status("/snapshots/$delete-id", 'DELETE', :$public-key, :$secret-key);
if $status == 428 {
if handle-sudo-challenge($body, "/snapshots/$delete-id", 'DELETE', :$public-key, :$secret-key) {
say "{$GREEN}Snapshot deleted: $delete-id{$RESET}";
} else {
note "{$RED}Error: Failed to delete snapshot (OTP verification failed){$RESET}";
exit 1;
}
} elsif $status >= 200 && $status < 300 {
say "{$GREEN}Snapshot deleted: $delete-id{$RESET}";
} else {
note "{$RED}Error: Failed to delete snapshot (HTTP $status){$RESET}";
exit 1;
}
return;
}
if $lock-id {
snapshot-lock($lock-id, :$public-key, :$secret-key);
say "{$GREEN}Snapshot locked: $lock-id{$RESET}";
return;
}
if $unlock-id {
my ($status, $body) = api-request-with-status("/snapshots/$unlock-id/unlock", 'POST', :$public-key, :$secret-key);
if $status == 428 {
if handle-sudo-challenge($body, "/snapshots/$unlock-id/unlock", 'POST', :$public-key, :$secret-key) {
say "{$GREEN}Snapshot unlocked: $unlock-id{$RESET}";
} else {
note "{$RED}Error: Failed to unlock snapshot (OTP verification failed){$RESET}";
exit 1;
}
} elsif $status >= 200 && $status < 300 {
say "{$GREEN}Snapshot unlocked: $unlock-id{$RESET}";
} else {
note "{$RED}Error: Failed to unlock snapshot (HTTP $status){$RESET}";
exit 1;
}
return;
}
if $restore-id {
snapshot-restore($restore-id, :$public-key, :$secret-key);
say "{$GREEN}Snapshot restored: $restore-id{$RESET}";
return;
}
if $clone-id {
unless $clone-type {
note "{$RED}Error: --clone-type required (session or service){$RESET}";
exit 1;
}
my $new-id = snapshot-clone($clone-id, :$clone-type, :$name, :$ports, :$shell, :$public-key, :$secret-key);
say "{$GREEN}Cloned to $clone-type: $new-id{$RESET}";
return;
}
if $session-id {
my $snap-id = snapshot-session($session-id, :$name, :$hot, :$public-key, :$secret-key);
say "{$GREEN}Snapshot created: $snap-id{$RESET}";
return;
}
if $service-id {
my $snap-id = snapshot-service($service-id, :$name, :$hot, :$public-key, :$secret-key);
say "{$GREEN}Snapshot created: $snap-id{$RESET}";
return;
}
note "{$RED}Error: Specify --list, --info ID, --delete ID, --lock ID, --unlock ID, --restore ID, --clone ID, --session ID, or --service ID{$RESET}";
exit 1;
}
sub MAIN(*@args) is export {
unless @args {
note "Usage: un.raku [options] <source_file>";
note " un.raku session [options]";
note " un.raku service [options]";
note " un.raku snapshot [options]";
note " un.raku image [options]";
note " un.raku key [options]";
note " un.raku languages [--json]";
note "";
note "Languages options:";
note " --json Output as JSON array";
note "";
note "Snapshot options:";
note " --list List all snapshots";
note " --info ID Get snapshot details";
note " --delete ID Delete a snapshot";
note " --lock ID Lock snapshot to prevent deletion";
note " --unlock ID Unlock snapshot";
note " --restore ID Restore a snapshot";
note " --clone ID Clone snapshot (requires --clone-type)";
note " --session ID Create snapshot from session";
note " --service ID Create snapshot from service";
note " --name NAME Name for the snapshot";
note " --hot Create hot snapshot (while running)";
note " --clone-type TYPE Clone type: session or service";
note " --ports PORTS Ports for cloned service";
note " --shell SHELL Shell for cloned session";
note "";
note "Image options:";
note " --list List all images";
note " --info ID Get image details";
note " --delete ID Delete an image";
note " --lock ID Lock image to prevent deletion";
note " --unlock ID Unlock image";
note " --publish ID Publish image from service/snapshot";
note " --source-type TYPE Source type: service or snapshot";
note " --visibility ID MODE Set visibility: private, unlisted, public";
note " --spawn ID Spawn new service from image";
note " --clone ID Clone an image";
note " --name NAME Name for spawned service or cloned image";
note " --ports PORTS Ports for spawned service";
note " --grant ID KEY Grant image access to API key";
note " --revoke ID KEY Revoke image access from API key";
note " --trusted ID List trusted API keys for image";
note " --transfer ID KEY Transfer image ownership";
exit 1;
}
given @args[0] {
when 'session' {
cmd-session(@args[1..*]);
}
when 'service' {
cmd-service(@args[1..*]);
}
when 'snapshot' {
cmd-snapshot(@args[1..*]);
}
when 'image' {
cmd-image(@args[1..*]);
}
when 'key' {
cmd-key(@args[1..*]);
}
when 'languages' {
cmd-languages(@args[1..*]);
}
default {
cmd-execute(@args);
}
}
}
Documentation clarifications
Dependencies
C Binary (un1) — requires libcurl and libwebsockets:
sudo apt install build-essential libcurl4-openssl-dev libwebsockets-dev
wget unsandbox.com/downloads/un.c && gcc -O2 -o un un.c -lcurl -lwebsocketsSDK Implementations — most use stdlib only (Ruby, JS, Go, etc). Some require minimal deps:
pip install requests # PythonExecute Code
Run a Script
./un hello.py
./un app.js
./un main.rsWith Environment Variables
./un -e DEBUG=1 -e NAME=World script.pyWith Input Files (teleport files into sandbox)
./un -f data.csv -f config.json process.pyGet Compiled Binary (teleport artifacts out)
./un -a -o ./bin main.cInteractive Sessions
Start a Shell Session
# Default bash shell
./un session
# Choose your shell
./un session --shell zsh
./un session --shell fish
# Jump into a REPL
./un session --shell python3
./un session --shell node
./un session --shell juliaSession with Network Access
./un session -n semitrustedSession Auditing (full terminal recording)
# Record everything (including vim, interactive programs)
./un session --audit -o ./logs
# Replay session later
zcat session.log*.gz | less -RCollect Artifacts from Session
# Files in /tmp/artifacts/ are collected on exit
./un session -a -o ./outputsSession Persistence (tmux/screen)
# Default: session terminates on disconnect (clean exit)
./un session
# With tmux: session persists, can reconnect later
./un session --tmux
# Press Ctrl+b then d to detach
# With screen: alternative multiplexer
./un session --screen
# Press Ctrl+a then d to detachList Active Sessions
./un session --list
# Output:
# Active sessions: 2
#
# SESSION ID CONTAINER SHELL TTL STATUS
# abc123... unsb-vm-12345 python3 45m30s active
# def456... unsb-vm-67890 bash 1h2m activeReconnect to Existing Session
# Reconnect by container name (requires --tmux or --screen)
./un session --attach unsb-vm-12345
# Use exit to terminate session, or detach to keep it runningTerminate a Session
./un session --kill unsb-vm-12345Available Shells & REPLs
Shells: bash, dash, sh, zsh, fish, ksh, tcsh, csh, elvish, xonsh, ash
REPLs: python3, bpython, ipython # Python
node # JavaScript
ruby, irb # Ruby
lua # Lua
php # PHP
perl # Perl
guile, scheme # Scheme
ghci # Haskell
erl, iex # Erlang/Elixir
sbcl, clisp # Common Lisp
r # R
julia # Julia
clojure # ClojureAPI Key Management
Check Key Status
# Check if your API key is valid
./un key
# Output:
# Valid: key expires in 30 daysExtend Expired Key
# Open the portal to extend an expired key
./un key --extend
# This opens the unsandbox.com portal where you can
# add more credits to extend your key's expirationAuthentication
Credentials are loaded in priority order (highest first):
# 1. CLI flags (highest priority)
./un -p unsb-pk-xxxx -k unsb-sk-xxxxx script.py
# 2. Environment variables
export UNSANDBOX_PUBLIC_KEY=unsb-pk-xxxx-xxxx-xxxx-xxxx
export UNSANDBOX_SECRET_KEY=unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx
./un script.py
# 3. Config file (lowest priority)
# ~/.unsandbox/accounts.csv format: public_key,secret_key
mkdir -p ~/.unsandbox
echo "unsb-pk-xxxx-xxxx-xxxx-xxxx,unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx" > ~/.unsandbox/accounts.csv
./un script.pyRequests are signed with HMAC-SHA256. The bearer token contains only the public key; the secret key computes the signature (never transmitted).
Resource Scaling
Set vCPU Count
# Default: 1 vCPU, 2GB RAM
./un script.py
# Scale up: 4 vCPUs, 8GB RAM
./un -v 4 script.py
# Maximum: 8 vCPUs, 16GB RAM
./un --vcpu 8 heavy_compute.pyLive Session Boosting
# Boost a running session to 2 vCPU, 4GB RAM
./un session --boost sandbox-abc
# Boost to specific vCPU count (4 vCPU, 8GB RAM)
./un session --boost sandbox-abc --boost-vcpu 4
# Return to base resources (1 vCPU, 2GB RAM)
./un session --unboost sandbox-abcSession Freeze/Unfreeze
Freeze and Unfreeze Sessions
# Freeze a session (stop billing, preserve state)
./un session --freeze sandbox-abc
# Unfreeze a frozen session
./un session --unfreeze sandbox-abc
# Note: Requires --tmux or --screen for persistencePersistent Services
Create a Service
# Web server with ports
./un service --name web --ports 80,443 --bootstrap "python -m http.server 80"
# With custom domains
./un service --name blog --ports 8000 --domains blog.example.com
# Game server with SRV records
./un service --name mc --type minecraft --bootstrap ./setup.sh
# Deploy app tarball with bootstrap script
./un service --name app --ports 8000 -f app.tar.gz --bootstrap-file ./setup.sh
# setup.sh: cd /tmp && tar xzf app.tar.gz && ./app/start.shManage Services
# List all services
./un service --list
# Get service details
./un service --info abc123
# View bootstrap logs
./un service --logs abc123
./un service --tail abc123 # last 9000 lines
# Execute command in running service
./un service --execute abc123 'journalctl -u myapp -n 50'
# Dump bootstrap script (for migrations)
./un service --dump-bootstrap abc123
./un service --dump-bootstrap abc123 backup.sh
# Freeze/unfreeze service
./un service --freeze abc123
./un service --unfreeze abc123
# Service settings (auto-wake, freeze page display)
./un service --auto-unfreeze abc123 # enable auto-wake on HTTP
./un service --no-auto-unfreeze abc123 # disable auto-wake
./un service --show-freeze-page abc123 # show HTML payment page (default)
./un service --no-show-freeze-page abc123 # return JSON error instead
# Redeploy with new bootstrap
./un service --redeploy abc123 --bootstrap ./new-setup.sh
# Destroy service
./un service --destroy abc123Snapshots
List Snapshots
./un snapshot --list
# Output:
# Snapshots: 3
#
# SNAPSHOT ID NAME SOURCE SIZE CREATED
# unsb-snapshot-a1b2-c3d4-e5f6-g7h8 before-upgrade session 512 MB 2h ago
# unsb-snapshot-i9j0-k1l2-m3n4-o5p6 stable-v1.0 service 1.2 GB 1d agoCreate Session Snapshot
# Snapshot with name
./un session --snapshot unsb-vm-12345 --name "before upgrade"
# Quick snapshot (auto-generated name)
./un session --snapshot unsb-vm-12345Create Service Snapshot
# Standard snapshot (pauses container briefly)
./un service --snapshot unsb-service-abc123 --name "stable v1.0"
# Hot snapshot (no pause, may be inconsistent)
./un service --snapshot unsb-service-abc123 --hotRestore from Snapshot
# Restore session from snapshot
./un session --restore unsb-snapshot-a1b2-c3d4-e5f6-g7h8
# Restore service from snapshot
./un service --restore unsb-snapshot-i9j0-k1l2-m3n4-o5p6Delete Snapshot
./un snapshot --delete unsb-snapshot-a1b2-c3d4-e5f6-g7h8Images
Images are independent, transferable container images that survive container deletion. Unlike snapshots (which live with their container), images can be shared with other users, transferred between API keys, or made public in the marketplace.
List Images
# List all images (owned + shared + public)
./un image --list
# List only your images
./un image --list owned
# List images shared with you
./un image --list shared
# List public marketplace images
./un image --list public
# Get image details
./un image --info unsb-image-xxxx-xxxx-xxxx-xxxxPublish Images
# Publish from a stopped or frozen service
./un image --publish-service unsb-service-abc123 \
--name "My App v1.0" --description "Production snapshot"
# Publish from a snapshot
./un image --publish-snapshot unsb-snapshot-xxxx-xxxx-xxxx-xxxx \
--name "Stable Release"
# Note: Cannot publish from running containers - stop or freeze firstCreate Services from Images
# Spawn a new service from an image
./un image --spawn unsb-image-xxxx-xxxx-xxxx-xxxx \
--name new-service --ports 80,443
# Clone an image (creates a copy you own)
./un image --clone unsb-image-xxxx-xxxx-xxxx-xxxxImage Protection
# Lock image to prevent accidental deletion
./un image --lock unsb-image-xxxx-xxxx-xxxx-xxxx
# Unlock image to allow deletion
./un image --unlock unsb-image-xxxx-xxxx-xxxx-xxxx
# Delete image (must be unlocked)
./un image --delete unsb-image-xxxx-xxxx-xxxx-xxxxVisibility & Sharing
# Set visibility level
./un image --visibility unsb-image-xxxx-xxxx-xxxx-xxxx private # owner only (default)
./un image --visibility unsb-image-xxxx-xxxx-xxxx-xxxx unlisted # can be shared
./un image --visibility unsb-image-xxxx-xxxx-xxxx-xxxx public # marketplace
# Share with specific user
./un image --grant unsb-image-xxxx-xxxx-xxxx-xxxx \
--key unsb-pk-friend-friend-friend-friend
# Revoke access
./un image --revoke unsb-image-xxxx-xxxx-xxxx-xxxx \
--key unsb-pk-friend-friend-friend-friend
# List who has access
./un image --trusted unsb-image-xxxx-xxxx-xxxx-xxxxTransfer Ownership
# Transfer image to another API key
./un image --transfer unsb-image-xxxx-xxxx-xxxx-xxxx \
--to unsb-pk-newowner-newowner-newowner-newownerUsage Reference
Usage: ./un [options] <source_file>
./un session [options]
./un service [options]
./un snapshot [options]
./un image [options]
./un key
Commands:
(default) Execute source file in sandbox
session Open interactive shell/REPL session
service Manage persistent services
snapshot Manage container snapshots
image Manage container images (publish, share, transfer)
key Check API key validity and expiration
Options:
-e KEY=VALUE Set environment variable (can use multiple times)
-f FILE Add input file (can use multiple times)
-a Return and save artifacts from /tmp/artifacts/
-o DIR Output directory for artifacts (default: current dir)
-p KEY Public key (or set UNSANDBOX_PUBLIC_KEY env var)
-k KEY Secret key (or set UNSANDBOX_SECRET_KEY env var)
-n MODE Network mode: zerotrust (default) or semitrusted
-v N, --vcpu N vCPU count 1-8, each vCPU gets 2GB RAM (default: 1)
-y Skip confirmation for large uploads (>1GB)
-h Show this help
Authentication (priority order):
1. -p and -k flags (public and secret key)
2. UNSANDBOX_PUBLIC_KEY + UNSANDBOX_SECRET_KEY env vars
3. ~/.unsandbox/accounts.csv (format: public_key,secret_key per line)
Session options:
-s, --shell SHELL Shell/REPL to use (default: bash)
-l, --list List active sessions
--attach ID Reconnect to existing session (ID or container name)
--kill ID Terminate a session (ID or container name)
--freeze ID Freeze a session (requires --tmux/--screen)
--unfreeze ID Unfreeze a frozen session
--boost ID Boost session resources (2 vCPU, 4GB RAM)
--boost-vcpu N Specify vCPU count for boost (1-8)
--unboost ID Return to base resources
--audit Record full session for auditing
--tmux Enable session persistence with tmux (allows reconnect)
--screen Enable session persistence with screen (allows reconnect)
Service options:
--name NAME Service name (creates new service)
--ports PORTS Comma-separated ports (e.g., 80,443)
--domains DOMAINS Custom domains (e.g., example.com,www.example.com)
--type TYPE Service type: minecraft, mumble, teamspeak, source, tcp, udp
--bootstrap CMD Bootstrap command/file/URL to run on startup
-f FILE Upload file to /tmp/ (can use multiple times)
-l, --list List all services
--info ID Get service details
--tail ID Get last 9000 lines of bootstrap logs
--logs ID Get all bootstrap logs
--freeze ID Freeze a service
--unfreeze ID Unfreeze a service
--auto-unfreeze ID Enable auto-wake on HTTP request
--no-auto-unfreeze ID Disable auto-wake on HTTP request
--show-freeze-page ID Show HTML payment page when frozen (default)
--no-show-freeze-page ID Return JSON error when frozen
--destroy ID Destroy a service
--redeploy ID Re-run bootstrap script (requires --bootstrap)
--execute ID CMD Run a command in a running service
--dump-bootstrap ID [FILE] Dump bootstrap script (for migrations)
--snapshot ID Create snapshot of session or service
--snapshot-name User-friendly name for snapshot
--hot Create snapshot without pausing (may be inconsistent)
--restore ID Restore session/service from snapshot ID
Snapshot options:
-l, --list List all snapshots
--info ID Get snapshot details
--delete ID Delete a snapshot permanently
Image options:
-l, --list [owned|shared|public] List images (all, owned, shared, or public)
--info ID Get image details
--publish-service ID Publish image from stopped/frozen service
--publish-snapshot ID Publish image from snapshot
--name NAME Name for published image
--description DESC Description for published image
--delete ID Delete image (must be unlocked)
--clone ID Clone image (creates copy you own)
--spawn ID Create service from image (requires --name)
--lock ID Lock image to prevent deletion
--unlock ID Unlock image to allow deletion
--visibility ID LEVEL Set visibility (private|unlisted|public)
--grant ID --key KEY Grant access to another API key
--revoke ID --key KEY Revoke access from API key
--transfer ID --to KEY Transfer ownership to API key
--trusted ID List API keys with access
Key options:
(no options) Check API key validity
--extend Open portal to extend an expired key
Examples:
./un script.py # execute Python script
./un -e DEBUG=1 script.py # with environment variable
./un -f data.csv process.py # with input file
./un -a -o ./bin main.c # save compiled artifacts
./un -v 4 heavy.py # with 4 vCPUs, 8GB RAM
./un session # interactive bash session
./un session --tmux # bash with reconnect support
./un session --list # list active sessions
./un session --attach unsb-vm-12345 # reconnect to session
./un session --kill unsb-vm-12345 # terminate a session
./un session --freeze unsb-vm-12345 # freeze session
./un session --unfreeze unsb-vm-12345 # unfreeze session
./un session --boost unsb-vm-12345 # boost resources
./un session --unboost unsb-vm-12345 # return to base
./un session --shell python3 # Python REPL
./un session --shell node # Node.js REPL
./un session -n semitrusted # session with network access
./un session --audit -o ./logs # record session for auditing
./un service --name web --ports 80 # create web service
./un service --list # list all services
./un service --logs abc123 # view bootstrap logs
./un key # check API key
./un key --extend # extend expired key
./un snapshot --list # list all snapshots
./un session --snapshot unsb-vm-123 # snapshot a session
./un service --snapshot abc123 # snapshot a service
./un session --restore unsb-snapshot-xxxx # restore from snapshot
./un image --list # list all images
./un image --list owned # list your images
./un image --publish-service abc # publish image from service
./un image --spawn img123 --name x # create service from image
./un image --grant img --key pk # share image with userCLI Inception
The UN CLI has been implemented in 42 programming languages, demonstrating that the unsandbox API can be accessed from virtually any environment.
License
PUBLIC DOMAIN - NO LICENSE, NO WARRANTY
This is free public domain software for the public good of a permacomputer hosted
at permacomputer.com - an always-on computer by the people, for the people. One
that is durable, easy to repair, and distributed like tap water for machine
learning intelligence.
The permacomputer is community-owned infrastructure optimized around four values:
TRUTH - First principles, math & science, open source code freely distributed
FREEDOM - Voluntary partnerships, freedom from tyranny & corporate control
HARMONY - Minimal waste, self-renewing systems with diverse thriving connections
LOVE - Be yourself without hurting others, cooperation through natural law
This software contributes to that vision by enabling code execution across all 42
programming languages through a unified interface, accessible to everyone. Code is
seeds to sprout on any abandoned technology.
Learn more: https://www.permacomputer.com
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
software, either in source code form or as a compiled binary, for any purpose,
commercial or non-commercial, and by any means.
NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
That said, our permacomputer's digital membrane stratum continuously runs unit,
integration, and functional tests on all its own software - with our permacomputer
monitoring itself, repairing itself, with minimal human guidance in the loop.
Our agents do their best.
Copyright 2025 TimeHexOn & foxhop & russell@unturf
https://www.timehexon.com
https://www.foxhop.net
https://www.unturf.com/software