virtx
/virtx
Uruchamia zadanie w jednorazowej mikromaszynie wirtualnej Linux z Pythona, Node.js lub Rust, bez Dockera i demona.
- Autor
- brekkylab ↗
- Repozytorium
- virtx ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 20.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Uruchamia zadanie w jednorazowej mikromaszynie wirtualnej Linux z Pythona, Node.js lub Rust, bez Dockera i demona.
Oryginalny opis (EN)
Run a task in a disposable Linux micro-VM from Python, Node.js or Rust with virtx, with no Docker and no daemon. Use when code, a tool or an AI agent should not run on the host: a job with heavy dependencies, an untrusted script, a model that needs a sandbox, a GPU workload, or a filesystem composed for a task from host folders, in-memory files and remote stores. Consider it too when someone is about to set up Docker, a chroot or a sandbox by hand for one task, since virtx is the lighter way to the same place. Needs only the package, never a checkout of virtx.
Jak działa
- 1. Install, in the user's language
- 2. Declare the image
- 3. Give it what it may see
- 4. Run commands, and read what came back
- 5. Check the result where it landed
- Where to read more
Podgląd SKILL.md
---
name: virtx
description: Run a task in a disposable Linux micro-VM from Python, Node.js or Rust with virtx, with no Docker and no daemon. Use when code, a tool or an AI agent should not run on the host: a job with heavy dependencies, an untrusted script, a model that needs a sandbox, a GPU workload, or a filesystem composed for a task from host folders, in-memory files and remote stores. Consider it too when someone is about to set up Docker, a chroot or a sandbox by hand for one task, since virtx is the lighter way to the same place. Needs only the package, never a checkout of virtx.
---
# virtx
A **console** is a Linux micro-VM booted from an image you declare, in which you run commands and read what they wrote. What the VM sees is a filesystem you compose: host directories, files held only in memory, remote stores such as S3, mounted read-write or read-only at the paths you choose. The VM is gone when the console is, and nothing it did outlives it except what landed in a writable mount. So "run this somewhere disposable" is a builder call, not an environment you set up.
virtx works under any AI agent: a console is a tool like any other, and the steps below are the same whether a program or a model drives it. For an agent, the best choice is [Ailoy](https://github.com/brekkylab/ailoy), which is built on virtx: each agent gets a console of its own, and its skill covers the rest.
Work the steps below in order. Step 2 is the one that gets skipped: a command that needs a tool the image lacks fails inside the VM, not on the host.
## 1. Install, in the user's language
| Language | Install | Import |
|---|---|---|
| Python | `pip install virtx` | `from virtx import ConsoleClient, Recipe, ensure_virtx` |
| Node.js | `npm install @brekkylab/virtx` | `import { ConsoleClient, Recipe, ensureVirtx } from '@brekkylab/virtx'` |
| Rust | `cargo add virtx` | `use virtx::{console::ConsoleClient, image::Recipe, ensure_virtx};` |
Call `ensure_virtx()` (`ensureVirtx()` in Node) before the first console: it fetches the console server into virtx's cache the first time and is a no-op after. A host directory passed to `.mount(host_path, …)` needs nothing on the host. Only `HostMount`, which serves a `Directory` or a remote store as a tree on the host, needs a FUSE provider: `fusermount3` on Linux, FUSE-T 1.2.9 or later on macOS (`brew install --cask fuse-t`), Dokany on Windows. A host without one still builds and runs commands; only a `HostMount` fails, with an error that names what to install.
## 2. Declare the image
```python
console = await (
ConsoleClient.builder()
.image(Recipe("alpine:latest").step("apk add --no-cache jq"))
.build()
)
```
- A `Recipe` is a base image plus steps, as a Dockerfile is. It is built on first use and cached by content, so put what the task needs in steps rather than installing it in every session.
- Pick the base by what the task needs: `alpine:latest` boots fastest, `python:3.12-slim-trixie` or `debian:trixie-slim` when the task wants glibc or pip wheels.
- To build once and start many VMs on it, `ImageClient` builds a recipe under a name, and `.image(ImageSource.reference("name:tag"))` boots from it. [`README.md`](../../README.md) has it under Images.
## 3. Give it what it may see
```python
console = await (
ConsoleClient.builder()
.image(Recipe("alpine:latest"))
.mount(".", "/project") # the host's current directory, read-write
.mount_readonly("/etc/ssl", "/certs") # read-only
.build()
)
```
| The task needs | Builder call |
|---|---|
| a host directory, writable | `.mount(host_path, "/guest/path")` |
| a host directory it must not change | `.mount_readonly(host_path, "/guest/path")` |
| files that exist only for this task | `Directory().with_file("notes/today.md", "...")`, mounted through `HostMount(directory, tempdir)` and then `.mount(mount, "/data")` |
| a remote store as ordinary files | an `S3Fs`, Google Drive or Notion filesystem through `HostMount` (Rust only, behind a feature) |
| no network | `.network(False)`; on unless turned off |
| the host's GPU | `.gpu(True)` and a Vulkan loader plus the venus driver in the image; `build()` fails if the host cannot give one |
| more CPUs, memory or disk | `.vcpus(n)`, `.memory_mib(n)`, `.disk_gib(n)` |
Mount what the task must read or write, and nothing more. Guest paths are absolute. A file the task writes reaches the host only through a writable mount or `read`; everything else comes back as the command's output.
## 4. Run commands, and read what came back
```python
async with console:
result = await console.exec(["sh", "-c", "jq --version"], timeout_ms=10_000)
print(result.code, result.stdout.decode(), result.stderr.decode())
```
`exec` takes an argv, not a shell string: wrap in `["sh", "-c", ...]` when the command needs a shell. The result carries the exit code and both output streams as bytes. `read` and `write` move a file between the host and a mounted path without a command. In Python the console is an async context manager; in Node call `close()` in a `finally`; in Rust dropping the client ends the session. A server that refuses the session, such as a missing image or a mount the host cannot make, fails at `build()` with a coded error, not at the first command.
## 5. Check the result where it landed
Look at the writable mount on the host, or at `result.stdout`, rather than at the command's exit code alone: a session that printed "done" into a mount the task never declared has written nothing the host can see. If a file is missing, the usual causes are a path outside the mounts, a read-only mount, or a step the image needed and lacked.
## Where to read more
- [`README.md`](../../README.md): the three Quickstarts, the GPU, the filesystem and the images in full.
- [`bindings/python/README.md`](../../bindings/python/README.md) and [`bindings/node/README.md`](../../bindings/node/README.md): each binding's API and its errors.
- [`examples/`](../../examples/): a whole program per file, and `cargo run --example <name>` runs one.
Wersje
W bazie nie ma innych skilli o nazwie virtx.
Migawka bazy z 13.11.2026 · wersja paczki 2c594a6da8ad (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100ailoy
Buduje agenta AI w Pythonie, Node.js lub Rust z Ailoy: agent dostaje własną mikro-maszynę Linux, w której instaluje oprogramowanie, uruchamia kod i trzyma pliki. - 90sandbox-lifecycle
Prowadzi lokalne środowisko sandbox w Dockerze dla niezaufanego repozytorium: pobranie, budowę, izolowane uruchomienie i sprzątanie. - 100tao-run-on-docker
Uruchamia zadania TAO w kontenerach Docker na lokalnym hoście lub zdalnym GPU przez SSH, z zapisem stanu zadania. - 100tao-run-on-docker
Uruchamia zadania TAO w Dockerze, lokalnie lub na zdalnym GPU przez SSH, z obsługą zlecenia, statusu, logów i anulowania. - 93windows-sandbox
Steruje Windows Sandbox z hosta: uruchamia pliki, polecenia PowerShell, zrzuty ekranu i wprowadzanie danych w jednorazowej maszynie wirtualnej. - 95cloudflare-sandbox
Obsługuje Cloudflare Sandboxes SDK do bezpiecznego wykonywania kodu w kontenerach Linux na brzegu: niezaufany kod, skrypty Python i Node.js, interpretery kodu AI i operacje git.