AI agent builder with a VM at its heart.
Ailoy is a library for building any kind of AI agents right in your own code.
 CAD modeling |  Image editing |
 Gameplay |  Laya(JEV) |
It supports 
Windows, and 
[!WARNING] Ailoy is under active development, and its API may change between versions.
Requirements
No system dependencies are required, but you need an API key for the LLM provider your agent will use.
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 HypervisorPlatformQuickstart
Set the API key for your model's provider, either in the environment or in a .env file:
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...Then build your agent with this simple API in your preferred language:
Python
pip install ailoy-pyimport asyncio
from ailoy import AgentBuilder
from ailoy.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.
Node.js
npm install @brekkylab/ailoyconst { AgentBuilder, ConsoleClient, Recipe } = require('@brekkylab/ailoy')
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.
Rust
[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?;
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.
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 |
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.pyNode:
cd examples/<name>/node
npm install
npm startHow It Works
Ailoy give the agent a computer of its own.
This lets you build agents that do more than call predefined tools: they can install and use software, create their own scripts, and operate in a general-purpose computing environment—without touching the host system beyond what you explicitly expose.
To make this possible, Ailoy uses krun-based virtualization to give each agent a virtual machine of its own, with no separate VM daemon to install.
The virtualization used in Ailoy also supports the GPU, so an agent can run ML models, or even games, inside its VM.
See virtx for more details.
Building from source
git clone https://github.com/brekkylab/ailoy
cd ailoy
cargo buildFor the bindings:
cd bindings/python && uv run maturin develop # Python
cd bindings/node && npm install && npm run build # Node.jsLicense
Apache-2.0. See LICENSE.md.