agentOS: Лёгкая Linux-песочница для AI-агентов

Я интегрировал агенты ИИ для кодирования в несколько скриптов автоматизации на бэкенде TecMint. Эти агенты создавали черновик, выполняли команду, проверяли результат и повторяли процесс, пока задача не была выполнена.

Поскольку я не хотел, чтобы ИИ-агент напрямую выполнял случайные команды в оболочке на моем производственном сервере, каждая задача требовала собственной изолированной среды. Как и многие, я начал с Docker, а позже перешел на облачную песочницу, когда время запуска Docker стало узким местом.

Сначала всё работало хорошо, но в конечном итоге и стоимость, и задержка запуска стали трудно игнорировать. Песочница, которая запускается за 400-900 миллисекунд, сама по себе может не казаться медленной.

Однако, когда агент ИИ создаёт новую песочницу для каждой задачи, повтора или небольшого шага, эта задержка быстро накапливается. Кроме того, я платил за полноценную виртуальную машину с 1 ГиБ памяти, даже когда она использовалась лишь для выполнения простой двухстрочной команды в оболочке.

Именно тогда я наткнулся на agentOS, проект с открытым исходным кодом от команды Rivet.

Прежде чем идти дальше, важно понять, что такое agentOS, потому что его название может быть вводящим в заблуждение. Это не инструмент командной строки, который вы устанавливаете с помощью менеджера пакетов и используете как eza или bat.

Вместо этого это библиотека Node.js, которая позволяет запускать изолированную виртуальную машину, похожую на Linux, прямо внутри вашего серверного приложения. Она включает версии многих знакомых утилит GNU на основе WebAssembly, таких как coreutils, grep, sed, gawk, findutils, tar, gzip и другие.

Эта разница важна, поэтому я подробно объясню, как именно я это настроил.

Что на самом деле делает agentOS

agentOS — это ядро операционной системы, работающее в процессе, написанное на Rust и распространяемое как npm-пакет. Когда вы вызываете AgentOs.create() в вашем приложении Node.js, оно создаёт виртуальную среду, похожую на Linux, внутри вашего существующего процесса. Эта среда включает виртуальную файловую систему, таблицу процессов, каналы (pipes), ПСУ (псевдотерминалы) и виртуальный сетевой стек.

Важно то, что на вашей хост-системе ничего не запускается. Он не создает контейнер Docker, не загружает виртуальную машину и не скачивает образ контейнера.

Всё работает внутри вашего процесса Node.js, поэтому agentOS может запускаться всего за несколько миллисекунд, в отличие от сотен миллисекунд, которые часто требуют контейнеры.

Внутри этой виртуальной среды agentOS запускает программные пакеты, созданные в виде бинарных файлов WebAssembly (WASM). Эти пакеты предоставляют команды Linux, которые работают очень похоже на те, что вы используете каждый день.

Проект поддерживает реестр пакетов, который включает знакомые инструменты, такие как coreutils, grep, sed, gawk, findutils, diffutils, tar, gzip, curl, jq, ripgrep, fd, tree, file, yq, zip и unzip.

По умолчанию эти инструменты работают с строгими ограничениями безопасности. Они не могут получать доступ к файлам, сети или процессам вашего компьютера, если вы явно этого не разрешите. Это делает среду намного безопаснее для выполнения команд, созданных ИИ.

На виртуальной машине agentOS также включает три встроенных кодировочных агента: Pi, Claude Code и OpenCode. Эти агенты общаются с использованием Протокола Коммуникации Агента (ACP).

Ваше приложение Node.js создает сессию, отправляет запрос агенту, и агент выполняет свою работу полностью внутри песочницы. Он может читать и записывать файлы, выполнять команды Linux с помощью встроенных WASM-утилит и выполнять задачи программирования без прямого доступа к вашей хост-системе.

Если вы хотите, чтобы агент работал с файлами на вашем сервере, вы должны явно смонтировать эти директории в виртуальную среду.

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть следующее:

• Сервер Linux с установленной Ubuntu 22.04 или более поздней версией, Debian 12 или более поздней версией, или RHEL 9/Rocky Linux 9 или более поздней версией с доступом к терминалу.
• Node.js 18 или новее, вместе с npm.
• Базовое знакомство с JavaScript, так как agentOS используется как библиотека Node.js, а не как автономный инструмент командной строки.
• Ключ API Anthropic, если вы планируете использовать встроенных агентов Pi или Claude Code. Вы можете создать его через консоль Anthropic. Если вы хотите только экспериментировать с песочницей и выполнять команды Linux с помощью vm.exec(), ключ API не нужен.

Шаг 1: Установите Node.js

agentOS требует Node.js 18 или более позднюю версию. Сначала установите Node.js и npm с помощью менеджера пакетов вашего дистрибутива.

На Ubuntu/Debian

sudo apt update
sudo apt install -y nodejs npm

На RHEL/Rocky Linux

sudo dnf install -y nodejs npm

После установки проверьте установленные версии:

node -v
npm -v

Пример вывода:

v24.18.0
11.16.0

agentOS требует Node.js 18 или новее для поддержки своих API. Если ваша дистрибуция предоставляет более старую версию, установите более новую версию из репозитория NodeSource, вместо того чтобы использовать пакеты по умолчанию.

Шаг 2: Создайте проект и установите agentOS

В отличие от Docker или других системных служб, agentOS полностью работает внутри проекта Node.js. Нет системного пакета для установки и нет службы для запуска.

Создайте новый каталог проекта и инициализируйте его с помощью npm:

mkdir ~/agentos-demo
cd ~/agentos-demo
npm init -y

Вы должны увидеть вывод, похожий на:

Wrote to /home/ravi/agentos-demo/package.json:

{
  "name": "agentos-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

Далее установите основную библиотеку agentOS вместе с общим пакетом программного обеспечения и агентом кодирования для Pi:

npm install @rivet-dev/agentos-core \
            @agentos-software/common \
            @agentos-software/pi

Установка может занять несколько минут, в зависимости от вашего интернет-соединения. Вы также можете увидеть вывод, похожий на следующий:

npm WARN deprecated @mariozechner/[email : please use @earendil-works/pi-ai instead going forward
npm WARN deprecated @mariozechner/[email : please use @earendil-works/pi-coding-agent instead going forward

added 359 packages, and audited 360 packages in 3m

69 packages are looking for funding
  run `npm fund` for details

8 vulnerabilities (2 low, 5 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

Some issues need review and may require choosing
a different dependency.

Run `npm audit` for details.

Не беспокойтесь, если при установке вы видите предупреждения о устаревании или уязвимостях. Они связаны с некоторыми зависимостями проекта и встречаются во многих проектах Node.js.

Пакеты всё ещё устанавливаются успешно, поэтому вы можете продолжить следующий шаг. Если вы планируете использовать agentOS в производственной среде, рекомендуется просмотреть отчёт npm audit и поддерживать ваши зависимости в актуальном состоянии.

Три пакета, которые вы установили, каждый выполняет разную роль:

• @rivet-dev/agentos-core предоставляет ядро движка agentOS, которое создаёт виртуальную файловую систему, таблицу процессов, сетевой стек и управляет сессиями агентов.
• @agentos-software/common устанавливает коллекцию утилит Linux на базе WebAssembly, включая coreutils, grep, sed, gawk, findutils, diffutils, tar и gzip.
• @agentos-software/pi устанавливает Pi, одного из встроенных кодировочных агентов, доступных в agentOS, наряду с Claude Code и OpenCode.

Шаг 3: Запустите вашу первую сессию агента

Если вы хотите использовать встроенного агента Pi, вам сначала нужно предоставить ваш ключ API Anthropic. Самый простой способ — экспортировать его как переменную окружения в вашей текущей сессии терминала, чтобы не пришлось прописывать его напрямую в скрипте.

export ANTHROPIC_API_KEY="your-api-key-here"

Теперь создайте файл с именем index.mjs со следующим кодом:

cat > index.mjs << 'EOF' import { AgentOs } from "@rivet-dev/agentos-core"; import common from "@agentos-software/common"; import pi from "@agentos-software/pi"; const vm = await AgentOs.create({ software: [common, pi] }); const { sessionId } = await vm.createSession("pi", { env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }, }); vm.onSessionEvent(sessionId, (event) => {
  console.log(event);
});

await vm.prompt(sessionId, "Write a hello world script to /home/agentos/hello.js");

const content = await vm.readFile("/home/agentos/hello.js");
console.log(new TextDecoder().decode(content));

vm.closeSession(sessionId);
await vm.dispose();
EOF

Этот скрипт выполняет следующие задачи:

• Создаёт новую виртуальную машину agentOS.
• Загружает общие утилиты Linux и агент программирования Pi.
• Запускает новую сессию агента Pi.
• Передает ваш ключ API Anthropic агенту.
• Просит агента создать простую программу Hello World на JavaScript.
• Считывает сгенерированный файл с виртуальной файловой системы и выводит его содержимое.
• Закрывает сессию и удаляет виртуальную машину.

Запустите скрипт с помощью:

node index.mjs

Если всё работает правильно, вы увидите вывод, похожий на этот:

{ type: 'session_start', sessionId: 'sess_8f2a1c' }
{ type: 'agent_message', text: 'Writing hello.js now.' }
{ type: 'tool_call', name: 'write_file', path: '/home/agentos/hello.js' }
{ type: 'session_end', sessionId: 'sess_8f2a1c' }

console.log("Hello, World!");

Последняя строка — это содержимое файла hello.js, который создал агент. Скрипт читает файл из виртуальной файловой системы с помощью vm.readFile() и выводит его в ваш терминал.

Обратите внимание, что файл существует только внутри виртуальной среды agentOS. Он не записывается в реальную файловую систему вашего сервера. Как только скрипт вызывает vm.dispose(), виртуальная машина уничтожается вместе со всем, что было в ней сохранено. Если вы хотите, чтобы файлы сохранялись, необходимо явно смонтировать директорию из вашей хост-системы в виртуальную среду.

Шаг 4: Выполняйте команды Linux без агента ИИ

Одним из приятных аспектов agentOS является то, что вам не обязательно использовать ИИ-агента. Вы можете использовать его как лёгкую песочницу для выполнения команд Linux, вызывая vm.exec() напрямую.

Создайте новый файл с именем shell-test.mjs:

cat > shell-test.mjs << 'EOF'
import { AgentOs } from "@rivet-dev/agentos-core";
import common from "@agentos-software/common";

const vm = await AgentOs.create({ software: [common] });

const result = await vm.exec("echo 'tecmint rocks' | grep -i tecmint");

console.log(result);

await vm.dispose();
EOF

Теперь запустите скрипт:

node shell-test.mjs

Если команда выполнится успешно, вы увидите вывод, похожий на этот:

{
  stdout: 'tecmint rocks\n',
  stderr: '',
  exitCode: 0
}

Вот что происходит за кулисами:

• echo 'tecmint rocks' выводит текст внутри виртуальной среды.
• Конвейер (|) отправляет этот вывод непосредственно следующей команде, так же, как это было бы в обычной оболочке Linux.
• grep -i tecmint ищет слово tecmint, не учитывая регистр букв, и возвращает совпадающую строку.

Хотя команды выглядят как обычные Linux команды, на самом деле это версии WebAssembly, работающие внутри виртуальной среды agentOS. Они не выполняются на вашей хост-системе и не взаимодействуют с вашей реальной оболочкой.

Я также протестировал, что происходит, когда вы пытаетесь выполнить команду, которая недоступна, или забываете загрузить необходимый программный пакет. Вместо того чтобы вызывать сбой, agentOS возвращает структурированную ошибку с ненулевым кодом выхода. Это значительно упрощает обнаружение ошибок и их обработку в вашем приложении, особенно когда команды генерируются агентом ИИ.

Шаг 5: Почему важны быстрые времена запуска

Одним из главных преимуществ agentOS является то, как быстро он запускает новую виртуальную среду.

Согласно бенчмаркам, опубликованным проектом, типичный экземпляр agentOS запускается примерно за 5 миллисекунд, в то время как традиционная хостинговая песочница может занимать около 440 миллисекунд на запуск. Разница становится еще больше при более высокой нагрузке.

Также использование памяти намного ниже. Типичная сессия кодирования в agentOS использует около 130 МБ памяти, тогда как многие размещённые сервисы песочниц выделяют 1 ГБ виртуальной машины для каждой сессии, потому что им необходимо загрузить целую операционную систему.

Для приложений, которые создают множество краткоживущих сессий агентов, эти различия могут оказывать значительное влияние. Более быстрое время запуска сокращает ожидание, а меньший расход памяти означает, что вы можете запускать больше сессий агентов на одном и том же сервере.

Сказав это, agentOS не предназначен для замены всех типов песочниц. Если вашей рабочей нагрузке требуется запускать веб-браузер, компилировать нативные приложения или запускать программное обеспечение, которое недоступно в виде пакета WebAssembly, вам по-прежнему понадобится полноценная виртуальная машина или контейнер.

В таких ситуациях agentOS может работать вместе с внешними поставщиками песочниц, подключаясь к реальной песочнице только тогда, когда это действительно необходимо.

Обновление agentOS

Как и большинство пакетов npm, agentOS обновляется регулярно. Вы можете проверить, доступна ли новая версия, запустив:

npm outdated @rivet-dev/agentos-core

Пример вывода:

Package                   Current  Wanted  Latest  Location
@rivet-dev/agentos-core     0.2.5   0.2.7   0.2.7  agentos-demo

Если обновления доступны, установите их с помощью:

npm update @rivet-dev/agentos-core \
           @agentos-software/common \
           @agentos-software/pi

Также полезно следить за выпусками проекта на GitHub. Новые версии основной библиотеки и программных пакетов часто выпускаются независимо друг от друга, поэтому вы можете увидеть новые утилиты для Linux на основе WebAssembly, даже если основной пакет не изменился.

Если вы используете agentOS в производстве, рассмотрите возможность закрепления версий пакетов в вашем package.json и тестирования новых релизов перед их развертыванием на серверах.

Заключение

Теперь у вас есть рабочий проект agentOS, который создает изолированную среду, похожую на Linux, выполняет знакомые команды Linux с использованием инструментов на базе WebAssembly и может безопасно передать эту среду агенту AI для кодирования. Поскольку agentOS запускает все внутри легковесной виртуальной среды, нет необходимости запускать контейнер или виртуальную машину для каждой задачи.

То, что отличает agentOS, — это его фокус. Вместо того чтобы заменять традиционных поставщиков песочниц, он предлагает быстрое, лёгкое окружение для выполнения краткоживущих задач агентов и команд Linux. Для многих автоматизированных рабочих процессов это может означать сокращение времени запуска, уменьшение использования памяти и снижение затрат на инфраструктуру.

Прежде чем добавлять AI-агента в ваше приложение, потратьте некоторое время на использование vm.exec() самостоятельно. Попробуйте выполнить несколько обычных команд Linux, создайте простые конвейеры и намеренно выполните недопустимую команду, чтобы увидеть, как agentOS сообщает об ошибках. Это поможет вам понять, на что способны встроенные инструменты WebAssembly и где их ограничения.

Если вашему приложению в конечном итоге понадобятся такие функции, как запуск браузера, компиляция нативного кода или выполнение программного обеспечения вне доступных пакетов WASM, вы всегда можете сочетать agentOS с традиционным песочницей для этих конкретных рабочих нагрузок.

По мере того как проект продолжает развиваться, стоит экспериментировать с реальными рабочими нагрузками, чтобы понять, где он лучше всего подходит в вашей собственной автоматизационной цепочке. Легкий дизайн делает его интересным вариантом для автоматизации Linux с поддержкой ИИ, особенно когда важны быстрое время запуска и эффективное использование ресурсов.