velyr

    v0.1.0-alpha.1
    Navigation

    Getting Started

    Build Velyr from source, run your first script, and grant it your first permission.

    Velyr is a security-first JavaScript and TypeScript runtime written in Rust. Scripts start with no access to files, network, environment or processes, and you grant what they need.

    Install a prebuilt binary#

    Each GitHub release publishes velyr-<target>.tar.gz (.zip on Windows) archives and a SHA256SUMS file. Targets:

    • Linux: x86_64 and aarch64, with gnu and musl variants.
    • macOS: x86_64-apple-darwin and aarch64-apple-darwin.
    • Windows: x86_64-pc-windows-msvc.

    Download the archive for your platform, verify it against SHA256SUMS, extract it and put velyr on your PATH.

    Build from source#

    You need git and rustup. The repository pins its Rust toolchain in rust-toolchain.toml, and rustup installs it on first build. The build downloads a prebuilt V8 and compiles a large dependency tree, so the first build takes a while.

    1. Clone the repository.

      bash
      git clone https://github.com/velyrlabs/velyr.git
cd velyr

    2. Build the CLI in release mode.

      bash
      cargo build --release -p velyr-cli

    3. The binary is target/release/velyr. Check it.

      bash
      ./target/release/velyr --version

      It prints velyr 0.1.0-alpha.1.

    Put target/release on your PATH, or copy the binary somewhere that is. The examples below assume velyr is on your PATH.

    Run your first script#

    Create hello.js:

    hello.js
    const greeting = new TextEncoder().encode("hello from velyr");
console.log(new TextDecoder().decode(greeting));

await new Promise((resolve) => setTimeout(resolve, 100));
console.log("done");

    Run it:

    bash
    velyr run hello.js

    .js and .mjs files run as ES modules, so import, export and top-level await work. Nothing in this script needs a permission.

    Grant a permission#

    Try reading a file:

    read.js
    try {
  console.log(await Velyr.readTextFile("./notes.txt"));
} catch (error) {
  console.log(error.code);
}

    Without a grant, the read fails:

    bash
    echo "remember this" > notes.txt
velyr run read.js
    VELYR_PERMISSION_DENIED

    Grant read access to the current directory. Note the =: values are attached to the flag.

    bash
    velyr run --allow-read=. read.js
    remember this

    Grants are scoped. --allow-read=./data allows only that directory and what is inside it, and --deny-read=./data/secrets carves out an exception that always wins. You can also put the same settings in a velyr.json file. The full rules are in Permissions.

    What next#