npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@brekkylab/ailoy

v0.3.2

Published

Agents that drive a language model through tool-augmented turns, in a virtx console.

Downloads

431

Readme

Ailoy is an open-source SDK for building AI agents right in your own code. Every agent gets a Linux VM of its own as its sandbox, so it can install software, write and run code and keep files without touching your machine. The sandbox is part of how you build the agent, not a separate service you wire in.

It supports Python, JavaScript ( TypeScript), and Rust APIs, and works on Linux, Windows, and macOS.

[!WARNING] Ailoy is under active development, and its API may change between versions.

Requirements

No system dependencies are required, but your agent's model needs a way to run: by default its provider's CLI (Claude Code, Codex or Gemini CLI), or its API with a key.

Mounting host folders into the console (virtx's virtual filesystem) needs FUSE: install FUSE-T on macOS or Dokany on Windows. See the virtx documentation for details.

On Windows, the console's micro-VM runs on the Windows Hypervisor Platform, which is off by default. Turn the optional feature on from an administrator PowerShell and restart, with virtualization enabled in the firmware:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

Quickstart

By default, Claude, GPT and Gemini run through their CLIs, so install and log in to the one for your model: Claude Code (claude), Codex (codex) or Gemini CLI (gemini).

To call the provider's API instead, set its key and switch the org to the api backend before building the agent, e.g. ailoy.set_lang_model_provider("anthropic", "api") in Python (setLangModelProvider in Node.js, ailoy::model::set_lang_model_provider in Rust):

export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, GEMINI_API_KEY

Amazon Bedrock, OpenRouter and vLLM are backends too; see the model providers guide.

Then build your agent with this simple API in your preferred language:

pip install ailoy-py
import asyncio

from ailoy import AgentBuilder
from virtx import ConsoleClient, Recipe, ensure_virtx


async def main() -> None:
    # Fetches virtx's server into its cache the first time; a no-op after.
    await ensure_virtx()

    console = await (
        ConsoleClient.builder()
        .image(Recipe("python:3.12-slim-trixie").step("pip install matplotlib"))
        .mount("./artifacts", "/artifacts")
        .network(True)
        .build()
    )

    agent = await (
        # For openai, use "openai/gpt-5.6-luna"
        AgentBuilder("anthropic/claude-haiku-5-5")
        .instruction("Write what you are asked for into /artifacts.")
        .system_tools()
        .console(console)
        .build()
    )

    async for output in agent.run("Create a bar chart comparing the populations of European countries and save it to /artifacts/population.png."):
        for part in output["message"]["contents"]:
            if part["type"] == "text":
                print(part["text"])

asyncio.run(main())

agent.run yields one complete message for each step of the tool loop, and agent.run_stream streams each message token by token as the model writes it.

npm install @brekkylab/ailoy @brekkylab/virtx
const { AgentBuilder } = require('@brekkylab/ailoy')
const { ConsoleClient, Recipe, ensureVirtx } = require('@brekkylab/virtx')

async function main() {
  // Fetches virtx's server into its cache the first time; a no-op after.
  await ensureVirtx()

  const console_ = await ConsoleClient.builder()
    .image(new Recipe('python:3.12-slim-trixie').step('pip install matplotlib'))
    .mount('./artifacts', '/artifacts')
    .network(true)
    .build()
  // For openai, use "openai/gpt-5.6-luna"
  const agent = await new AgentBuilder('anthropic/claude-haiku-5-5')
    .instruction('Write what you are asked for into /artifacts.')
    .systemTools()
    .console(console_)
    .build()

  try {
    for await (const { message } of agent.run('Create a bar chart comparing the populations of European countries and save it to /artifacts/population.png.')) {
      for (const part of message.contents) {
        if (part.type === 'text') console.log(part.text)
      }
    }
  } finally {
    await agent.close()
  }
}

main()

agent.run yields one complete message for each step of the tool loop, and agent.runStream streams each message token by token as the model writes it.

[dependencies]
ailoy = "0.3"
virtx = "0.1"
use ailoy::{
    agent::AgentBuilder,
    console::ConsoleClient,
    message::{Message, Part, Role},
};
use virtx::image::Recipe;
use futures::StreamExt as _;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Fetches virtx's server into its cache the first time; a no-op after.
    virtx::ensure_virtx().await?;

    let console = ConsoleClient::builder()
        .image(Recipe::new("python:3.12-slim-trixie").step("pip install matplotlib"))
        .mount(std::path::absolute("./artifacts")?, "/artifacts")
        .network(true)
        .build()
        .await?;

    // For openai, use "openai/gpt-5.6-luna"
    let mut agent = AgentBuilder::new("anthropic/claude-haiku-5-5")
        .instruction("Write what you are asked for into /artifacts.")
        .system_tools()
        .console(console)
        .build()
        .await?;

    let query = Message::new(Role::User).with_contents([Part::text("Create a bar chart comparing the populations of European countries and save it to /artifacts/population.png.")]);
    let mut stream = agent.run(query);
    while let Some(output) = stream.next().await {
        let message = output?.message;
        if message.role == Role::Assistant {
            for text in message.contents.iter().filter_map(Part::as_text) {
                println!("{text}");
            }
        }
    }
    Ok(())
}

agent.run yields one complete message for each step of the tool loop, and agent.run_stream streams each message token by token as the model writes it.

...Or skip the reading: point your coding agent (Claude Code, Codex, Cursor, ...) at this README and tell it what agent you want to build. This repo is its own plugin marketplace, so the agent skill installs with no clone first:

claude plugin marketplace add brekkylab/ailoy && claude plugin install ailoy@brekkylab
codex plugin marketplace add brekkylab/ailoy && codex plugin add ailoy@brekkylab

What can an agent do?

You'll need a GPU (any GPU that supports Vulkan, or Metal on Macs) for the examples that run ML models.

| Example | Description | | --- | --- | | hello | One turn with no tools and no console | | cad | Writes CadQuery, renders the model from four sides, looks at the renders and iterates | | offshore_leaks | Analyses the ICIJ Offshore Leaks database with SQL and Python that the agent writes itself | | retail_bench | Runs a supermarket simulator, one day per turn | | gameplay | Plays OpenTTD (Transport Tycoon Deluxe) while you watch over VNC | | sam3 | Segments images and videos with SAM3 on the guest GPU (ncnn + Vulkan) | | tts | Speaks text in a voice described in words, using Qwen3-TTS | | laya | Answers typed decision questions with a local model on the GPU | | browser-use | Waits for what you ask of it, in a window of your own browser |

Each example lives in examples/<name>, with one folder per language (rust, python, node) and, where the three share files (skills, prompts, model preparation scripts), a shared folder.

Rust:

cargo run --example <name>

Python:

cd examples/<name>/python
uv run main.py

Node:

cd examples/<name>/node
npm install
npm start

How it works

Ailoy gives the agent a computer of its own.

Agent stacks are often put together from separate pieces: a library that runs the loop around the model, a hosted service that provides the sandbox, and glue code between the two. Ailoy keeps the loop and the sandbox in one SDK:

  • The Ailoy SDK runs the agent loop on your host. It sends the prompt to the model, runs the tool calls the model asks for, feeds the results back, and decides when the agent is done.
  • virtx gives each agent a Linux VM of its own, built on krun, with no separate VM daemon to install. The VM is the agent's sandbox: its commands and file tools run inside it, and it reaches your machine only through the folders you mount.

That lets you build agents that do more than call predefined tools. Inside its VM an agent can install and use software, write its own scripts and work in a general-purpose computing environment. The VM supports the GPU too, so an agent can run ML models, or even games, in there.

The docs cover the VM's image, mounts and resources, and the virtx README covers the VM layer itself.

Building from source

git clone https://github.com/brekkylab/ailoy
cd ailoy
cargo build

For the bindings:

cd bindings/python && uv run maturin develop  # Python
cd bindings/node && npm install && npm run build  # Node.js

Contributing

Bug reports, ideas and pull requests are welcome. CONTRIBUTING.md covers setup, tests and how to open a PR. Questions and show-and-tell go on Discord.

License

Apache-2.0. See LICENSE.md.