DOCSEARCHbyAlgolia
Submit Docs

run-kit Documentation

repository·master·Indexed 21 days ago

https://github.com/esubaalew/run

A polyglot command runner and smart REPL written in Rust that provides a unified CLI for executing code in over 25 programming languages. Run 2.0 introduces WASI component orchestration, hot reloading via run.toml, and a hybrid execution model for migrating Docker Compose services to WASI. It supports deploying components to edge providers including Cloudflare Workers, AWS Lambda, Vercel, and Fastly.

Tokens
25K
Snippets
112
Records
148
Agent score
75%

What's inside run-kit

  1. Run Registry Overview

    master

    The Run Registry is a minimal WASI component registry designed to support the Run 2.0 client. It provides persistence and authentication for WASI components, ensuring reliable component discovery and installation.

    Key Features:

    • Immutable Versioning: Stores WASI components with fixed versions.
    • Integrity: Uses SHA-256 verification during the publishing process.
    • Namespace Ownership: Manages ownership via API tokens.
    • Persistence: Uses SQLite for metadata and on-disk storage for artifacts.
    • Discovery: Provides a search endpoint for finding packages.

  2. Run 2.0 (Experimental) and WASI Component Support

    master

    Run 2.0 is an experimental version that introduces support for WASI 0.2 components. This allows for cross-language composition, instant startup, and deployment to edge environments.

    To access the experimental 2.0 features, use the v2 subcommand:

    run v2 --help

  3. Features of the `run v2 dev` command

    master

    The run v2 dev command provides a comprehensive developer experience through the following features:

    • Hot reload: Automatically reloads components when watched files change.
    • Unified logs: Aggregates logs from all running components into a single stream.
    • Automatic restart: Restarts components automatically if they crash.
    • Multi-component orchestration: Manages the lifecycle of multiple components simultaneously.

  4. Understand the Polyglot SDK Example structure

    master

    The Polyglot SDK example is organized to demonstrate how different languages interface via a shared WIT (WebAssembly Interface Type) definition. The structure includes:

    • run.toml: The configuration file for the run tool.
    • wit/greeter.wit: The interface definition used to design the language bindings.
    • js/: JavaScript implementation.
    • ts/: TypeScript implementation.
    • go/: Go implementation.
    • zig/: Zig implementation.
    polyglot-sdk/
├── run.toml
├── wit/
│   └── greeter.wit
├── js/
│   ├── package.json
│   └── index.js
├── ts/
│   ├── package.json
│   ├── tsconfig.json
│   └── src/index.ts
├── go/
│   ├── go.mod
│   └── main.go
└── zig/
    ├── build.zig
    └── src/main.zig

  5. How the Run 2.0 Hybrid Concept works

    master

    The Run 2.0 hybrid model enables a split architecture for services:

    • WASI Components: Used for application logic to achieve high performance and low overhead.
    • Docker Services: Used for stateful infrastructure (databases, caches) that requires a standard container environment. These services are accessible to WASI components via a bridge.

  6. How run's execution engine works

    master

    run acts as a wrapper that shells out to real toolchains. It uses a LanguageEngine trait implementation for each supported language to:

    1. Detect Toolchains: Check for the presence of compilers or interpreters (e.g., python3, go, rustc).
    2. Workspace Management: Prepare temporary workspaces, such as compiling code for compiled languages or creating transient scripts for interpreters.
    3. Execution: Execute snippets, files, or stdin streams and provide consistent stdout/stderr output.
    4. Session Management: Handle state for the interactive REPL, including persistent modules and stateful scripts.

  8. Quickstart with run

    master

    Use run to execute code snippets, files, or interactive REPLs across multiple languages.

    • Check version: run --version
    • Execute a snippet: Use --lang <language> and --code "<code>".
    • Execute a file: Pass the file path directly; run detects the language via extension.
    • Interactive REPL: Run run without arguments to enter the REPL.
    • Piping stdin: Pipe data into run and use --code to process it (e.g., parsing JSON in Node.js or reading stdin in Python).
    # Show build metadata
run --version

# Execute a snippet explicitly
run --lang python --code "print('hello, polyglot world!')"

# Let run detect language from the file extension
run examples/go/hello/main.go

# Drop into the interactive REPL
run

# Pipe stdin (JSON) into Node.js
echo '{"name":"Ada"}' | run js --code "const data = JSON.parse(require('fs').readFileSync(0, 'utf8')); console.log(`hi ${data.name}`)"

  9. Execute code snippets and files with run

    master

    The run CLI allows you to execute code snippets or source files across 25 supported languages. You can use full flags, shorthand flags, or positional arguments.

    Execution Modes

    • Inline Code: Use --lang (or -l) and --code (or -c) to run a string of code.
    • Source Files: Provide the file path directly; run will attempt to detect the language based on the file extension.
    • Ambiguity Warning: Always use --lang when providing a string that might be ambiguous to ensure the correct interpreter is used.

    Syntax Variations

    # Full syntax
run --lang rust --code "fn main() { println!(\"hello\"); }"

# Shorthand flags
run -l rust -c "fn main() { println!(\"hello\"); }"

# Language first, then code
run rust "fn main() { println!(\"hello\"); }"

# Auto-detect from file
run examples/rust/hello.rs
    run -l python -c "print('hello')"
run --json python -c "print('hello')"

  11. Install run on Debian / Ubuntu

    master

    Download the .deb package and its checksum from the latest GitHub release, verify the checksum, and install via apt.

    ARCH=${ARCH:-amd64}
DEB_FILE=$(curl -s https://api.github.com/repos/Esubaalew/run/releases/latest \
  | grep -oE "run_[0-9.]+_${ARCH}\\.deb" | head -n 1)
curl -LO "https://github.com/Esubaalew/run/releases/latest/download/${DEB_FILE}"
curl -LO "https://github.com/Esubaalew/run/releases/latest/download/${DEB_FILE}.sha256"
sha256sum --check "${DEB_FILE}.sha256"
sudo apt install "./${DEB_FILE}"

  12. Build the Hello World WASI component

    master

    To build the minimal Run 2.0 WASI component, use cargo component to compile the project for the wasm32-wasip1 target in release mode, then copy the resulting .wasm file to your current directory.

    Note: This requires cargo-component to be installed in your environment.

    cargo component build --release
cp target/wasm32-wasip1/release/hello.wasm .