Skip to content
Back to search

ailoy

AI agent builder with a VM at its heart. Every agent gets its own microVM sandbox to install software, run code and use the GPU in. Python, Node.js and Rust.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/brekkylab/ailoy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/brekkylab/ailoy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/brekkylab--ailoy/badge.svg)](/listings/brekkylab--ailoy)

HTML

<a href="/listings/brekkylab--ailoy"><img src="/api/listings/brekkylab--ailoy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

By default, Claude, GPT and Gemini run through their CLIs, so install and log in to the one for your model: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`), [Codex](https://github.com/openai/codex) (`codex`) or [Gemini CLI](https://github.com/google-gemini/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](./docs/guide/model-providers.md).

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

<details> <summary><b>Python</b></summary>

pip install ailoy-py
import asyncio

from ailoy import AgentBuilder
from virtx import ConsoleClient, Recipe

async def main() -> None:
    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-4-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.

</details>

<details> <summary><b>Node.js</b></summary>

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

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-4-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()
}

`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.

</details>

<details> <summary><b>Rust</b></summary>

[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<()> {
    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-4-5")
        .instruction("Write what you are asked for into /artifacts.")
        .system_tools()
        .console(console)
        .build()
        .await?;

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "brekkylab",
  3. "description": "Plugins from brekkylab: Ailoy, for building AI agents with a VM of their own.",
  4. "owner": {
  5. "name": "brekkylab",
  6. "url": "https://github.com/brekkylab"
  7. },
  8. "plugins": [
  9. {
  10. "name": "ailoy",
  11. "source": "./",
  12. "description": "Build an AI agent in Python, Node.js or Rust, with a Linux micro-VM of its own to run code in."
  13. }
  14. ]
  15. }
README.md · README · 288 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/brekkylab/ailoy/main/docs/public/img/ailoy-logo-signature-white.svg">
  4. <img alt="Ailoy" src="https://raw.githubusercontent.com/brekkylab/ailoy/main/docs/public/img/ailoy-logo-signature-black.svg" width="352" style="max-width: 50%;">
  5. </picture>
  6. </p>
  7. <h3 align="center">The open-source agent SDK that gives every agent its own VM.</h3>
  8. <p align="center">
  9. <img src="https://cdn.simpleicons.org/rust/000000/ffffff" width="16"/> <a href="https://crates.io/crates/ailoy"><img src="https://img.shields.io/crates/v/ailoy?label=ailoy&color=dea584" alt="crates.io"></a>
  10. <img src="https://cdn.simpleicons.org/python" width="16"/> <a href="https://pypi.org/project/ailoy-py/"><img src="https://img.shields.io/pypi/v/ailoy-py?color=blue&label=ailoy-py" alt="PyPI"></a>
  11. <img src="https://cdn.simpleicons.org/nodedotjs" width="16"/> <a href="https://www.npmjs.com/package/@brekkylab/ailoy"><img src="https://img.shields.io/npm/v/@brekkylab/ailoy?label=@brekkylab/ailoy&color=339933" alt="npm node"></a>
  12. </p>
  13. <p align="center">
  14. <a href="https://ailoy.co/docs/"><img src="https://img.shields.io/badge/docs-eng-5a9cae" alt="Documentation"></a>
  15. <!-- <a href="https://docs.rs/ailoy"><img src="https://img.shields.io/docsrs/ailoy?label=docs.rs" alt="docs.rs"></a> -->
  16. <a href="https://discord.gg/27rx3EJy3P"><img src="https://img.shields.io/badge/Discord-7289DA?logo=discord&logoColor=white" alt="Discord"></a>
  17. <a href="https://x.com/brekkylab"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X"></a>
  18. </p>
  19. <br>
  20. 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.
  21. <table align="center">
  22. <tr>
  23. <td align="center"><img src="docs/images/ailoy-cad.gif" alt="CAD modeling"><br><sub>CAD modeling</sub></td>
  24. <td align="center"><img src="docs/images/ailoy-sam3-video.gif" alt="Image editing"><br><sub>Image editing</sub></td>
  25. </tr>
  26. <tr>
  27. <td align="center"><img src="docs/images/ailoy-openttd.gif" alt="Gameplay"><br><sub>Gameplay</sub></td>
  28. <td align="center"><img src="docs/images/ailoy-laya.gif" alt="Laya(JEV)"><br><sub>Laya(JEV)</sub></td>
  29. </tr>
  30. </table>
  31. It supports <img src="https://cdn.simpleicons.org/python" width="16"/> Python, <img src="https://cdn.simpleicons.org/javascript" width="16"/> JavaScript (<img src="https://cdn.simpleicons.org/typescript" width="16"/> TypeScript), and <img src="https://cdn.simpleicons.org/rust/000000/ffffff" width="16"/> Rust APIs, and works on <img src="https://cdn.simpleicons.org/linux/000000/ffffff" width="16"/> Linux, <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/windows11/windows11-original.svg" width="16"/> Windows, and <img src="https://cdn.simpleicons.org/apple/000000/ffffff" width="16"/> macOS.
  32. > [!WARNING]
  33. > Ailoy is under active development, and its API may change between versions.
  34. ## Requirements
  35. 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.
  36. On Windows, the sandbox's micro-VM runs on the *Windows Hypervisor Platform*, which is off by default.
  37. Turn the optional feature on from an administrator PowerShell and restart, with virtualization enabled in the firmware:
  38. ```powershell
  39. Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
  40. ```
  41. ## Quickstart
  42. By default, Claude, GPT and Gemini run through their CLIs, so install and log in to the one for your model: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`), [Codex](https://github.com/openai/codex) (`codex`) or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini`).
  43. 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):
  44. ```sh
  45. export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, GEMINI_API_KEY
  46. ```
  47. Amazon Bedrock, OpenRouter and a server you run yourself (vLLM, llama-server, Ollama, LM Studio) are backends too; see the [model providers guide](https://ailoy.co/docs/guides/model-providers/).
  48. Then build your agent with this simple API in your preferred language:
  49. <details>
  50. <summary><b>Python</b></summary>
  51. ```sh
  52. pip install ailoy-py
  53. ```
  54. ```python
  55. import asyncio
  56. from pathlib import Path
  57. from ailoy import AgentBuilder
  58. from virtx import Client
  59. async def main() -> None:
  60. # Starts virtx's server, fetched into its cache the first time.
  61. client = Client.spawn()
  62. await client.pull_image("python:3.12-slim-trixie").complete()
  63. sandbox = await client.create_sandbox("python:3.12-slim-trixie")
  64. agent = await (
  65. # For openai, use "openai/gpt-6-luna"
  66. AgentBuilder("anthropic/claude-haiku-5-5")
  67. .instruction("Write what you are asked for into /artifacts.")
  68. .sandbox(sandbox)
  69. .build()
  70. )
  71. async for output in agent.run("Create a bar chart comparing the populations of European countries and save it to /artifacts/population.png."):
  72. for part in output["message"]["contents"]:
  73. if part["type"] == "text":
  74. print(part["text"])
  75. Path("population.png").write_bytes(await sandbox.read_file("artifacts/population.png"))
  76. asyncio.run(main())
  77. ```
  78. `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.
  79. </details>
  80. <details>
  81. <summary><b>Node.js</b></summary>
  82. ```sh
  83. npm install @brekkylab/ailoy @brekkylab/virtx
  84. ```
  85. ```js
  86. const { writeFileSync } = require('node:fs')
  87. const { AgentBuilder } = require('@brekkylab/ailoy')
  88. const { Client } = require('@brekkylab/virtx')
  89. async function main() {
  90. // Starts virtx's server, fetched into its cache the first time.
  91. const client = Client.spawn()
  92. await client.pullImage('python:3.12-slim-trixie').complete()
  93. const sandbox = await client.createSandbox('python:3.12-slim-trixie')
  94. // For openai, use "openai/gpt-6-luna"
  95. const agent = await new AgentBuilder('anthropic/claude-haiku-5-5')
  96. .instruction('Write what you are asked for into /artifacts.')
  97. .sandbox(sandbox)
  98. .build()
  99. for await (const { message } of agent.run('Create a bar chart comparing the populations of European countries and save it to /artifacts/population.png.')) {
  100. for (const part of message.contents) {
  101. if (part.type === 'text') console.log(part.text)
  102. }
  103. }
  104. writeFileSync('population.png', await sandbox.readFile('artifacts/population.png'))
  105. await agent.close()
  106. await client.close()
  107. }
  108. main()
  109. ```
  110. `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.
  111. </details>
  112. <details>
  113. <summary><b>Rust</b></summary>
  114. ```toml
  115. [dependencies]
  116. ailoy = "0.3"
  117. virtx = "0.1"
  118. ```
  119. ```rust
  120. use ailoy::{
  121. agent::AgentBuilder,
  122. message::{Message, Part, Role},
  123. };
  124. use futures::StreamExt as _;
  125. use virtx::{Client, Files as _, SandboxCreateArgs};
  126. #[tokio::main]
  127. async fn main() -> anyhow::Result<()> {
  128. // Starts virtx's server, fetched into its cache the first time.
  129. let client = Client::spawn_virtx([] as [&str; 0]).await?;
  130. client.pull_image("python:3.12-slim-trixie", None).complete(false).await?;
  131. let sandbox = client
  132. .create_sandbox(&SandboxCreateArgs::new("python:3.12-slim-trixie"))
  133. .await?;
  134. // For openai, use "openai/gpt-6-luna"
  135. let mut agent = AgentBuilder::new("anthropic/claude-haiku-5-5")
  136. .instruction("Write what you are asked for into /artifacts.")
  137. .sandbox(sandbox.clone())
  138. .build()
  139. .await?;
  140. 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.")]);
  141. let mut stream = agent.run(query);
  142. while let Some(output) = stream.next().await {
  143. let message = output?.message;
  144. if message.role == Role::Assistant {
  145. for text in message.contents.iter().filter_map(Part::as_text) {
  146. println!("{text}");
  147. }
  148. }
  149. }
  150. let png = sandbox.read_file("artifacts/population.png", 0, None).await?;
  151. std::fs::write("population.png", png)?;
  152. Ok(())
  153. }
  154. ```
  155. `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.
  156. </details>
  157. ...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](skills/ailoy/SKILL.md) installs with no clone first:
  158. ```bash
  159. claude plugin marketplace add brekkylab/ailoy && claude plugin install ailoy@brekkylab
  160. codex plugin marketplace add brekkylab/ailoy && codex plugin add ailoy@brekkylab
  161. ```
  162. ## What can an agent do?
  163. > You'll need a GPU (any GPU that supports Vulkan, or Metal on Macs) for the examples that run ML models.
  164. | Example | Description |
  165. | --- | --- |
  166. | [hello](./examples/hello) | One turn with no tools and no sandbox |
  167. | [cad](./examples/cad) | Writes CadQuery, renders the model from four sides, looks at the renders and iterates |
  168. | [offshore_leaks](./examples/offshore_leaks) | Analyses the ICIJ Offshore Leaks database with SQL and Python that the agent writes itself |
  169. | [retail_bench](./examples/retail_bench) | Runs a supermarket simulator, one day per turn |
  170. | [gameplay](./examples/gameplay) | Plays OpenTTD (Transport Tycoon Deluxe) while you watch over VNC |
  171. | [sam3](./examples/sam3) | Segments images and videos with SAM3 on the guest GPU (ncnn + Vulkan) |
  172. | [tts](./examples/tts) | Speaks text in a voice described in words, using Qwen3-TTS |
  173. | [laya](./examples/laya) | Answers typed decision questions with a local model on the GPU |
  174. | [browser-use](./examples/browser-use) | Waits for what you ask of it, in a window of your own browser |
  175. 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.
  176. Rust:
  177. ```sh
  178. cargo run --example <name>
  179. ```
  180. Python:
  181. ```sh
  182. cd examples/<name>/python
  183. uv run main.py
  184. ```
  185. Node:
  186. ```sh
  187. cd examples/<name>/node
  188. npm install
  189. npm start
  190. ```
  191. ## How it works
  192. Ailoy gives the agent **a computer of its own**.
  193. 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:
  194. - 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.
  195. - **[virtx](https://github.com/brekkylab/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 files go in and out of it through virtx, never through your machine's own folders.
  196. 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.
  197. The [docs](https://ailoy.co/docs/) cover the VM's image, volumes and resources, and the [virtx](https://github.com/brekkylab/virtx) README covers the VM layer itself.
  198. ## Building from source
  199. ```sh
  200. git clone https://github.com/brekkylab/ailoy
  201. cd ailoy
  202. cargo build
  203. ```
  204. For the bindings:
  205. ```sh
  206. cd bindings/python && uv run maturin develop # Python
  207. cd bindings/node && npm install && npm run build # Node.js
  208. ```
  209. ## Contributing
  210. Bug reports, ideas and pull requests are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) covers setup, tests and how to open a PR. Questions and show-and-tell go on [Discord](https://discord.gg/27rx3EJy3P).
  211. ## License
  212. Apache-2.0. See [LICENSE.md](./LICENSE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.