Як запустити агенти Nanocode в Cloudflare Durable Objects з історією сесій

У матеріалі розбирається підхід авторів Nanocode: як запускати їхні coding-агенти в Cloudflare Durable Objects, зберігаючи історію сесій і можливість відновлення після збоїв.

Що саме змінилося

Nanocode — це рушій coding-агентів на Rust, який компілюється в WebAssembly і вміє працювати з форматами підказок та інструментів, сумісними з Codex і Claude Code. Раніше його запуск в інфраструктурі Cloudflare вимагав власної обв'язки. Тепер можна використовувати окремий хост на базі Cloudflare Durable Objects:

рушій Nanocode запускається всередині Durable Object як WebAssembly;
історія сесії та проміжні результати інструментів зберігаються в SQLite;
alarms Durable Objects дають змогу відновити незавершену роботу після перерв (рестарт воркера, тайм-аут, оновлення коду тощо).

Хост для Nanocode підтримує сам проєкт Nanocode, він працює незалежно від Cloudflare Agents SDK і не вимагає його підключення.

Архітектура: як поєднуються Nanocode, Workers і Durable Objects

З погляду Cloudflare, схема виглядає так:

звичайний Cloudflare Worker приймає HTTP-запити від клієнта;
цей Worker звертається до Durable Object, який інкапсулює один агент Nanocode;
усередині Durable Object завантажується WebAssembly-рушій Nanocode;
Durable Object веде стан сесії (промпти, відповіді, проміжні виклики інструментів) у SQLite;
якщо робота агента вимагає тривалих обчислень або зовнішніх викликів, Durable Object ставить alarm, щоб продовжити виконання, коли дозволить платформа.

Таке розділення дає змогу:

мати по одному екземпляру агента на кожен ключ або користувача (через унікальний Durable Object id);
уникати втрати контексту при рестартах воркерів завдяки збереженому стану в SQLite;
використовувати Nanocode без інтеграції з Cloudflare Agents SDK, що підходить, якщо вже є власна інфраструктура виклику моделей.

Сумісність з Codex і Claude Code

Рушій Nanocode у WebAssembly реалізує звичні для coding-агентів патерни:

підтримує структуру промптів, сумісну з Codex та Claude Code;
розуміє формат інструментів (tools), який очікують такі агенти;
використовує конвенції для кроків генерації коду, аналізу, запуску інструментів і повернення результатів.

Це важливо, якщо у вас уже є інструменти, написані під Codex/Claude Code, — їх можна адаптувати до Nanocode без повного переписування логіки, зосередившись на обгортці під Cloudflare.

Стійкість: SQLite для стану та alarms для продовження роботи

Ключова технічна деталь хоста на Durable Objects — те, як він поводиться зі станом і перервами в роботі:

SQLite усередині Durable Object зберігає:

історію діалогів (turns) агента з клієнтом;
прогрес поточного завдання (які інструменти вже викликані, які результати отримані);
метадані сесії для відновлення після рестарту.

Alarms Durable Objects використовуються для відкладеного продовження роботи:

якщо агент не встигає завершити завдання в один виклик, створюється alarm із потрібним часом спрацьовування;
коли alarm спрацьовує, Durable Object прочитує стан із SQLite та продовжує роботу Nanocode з місця зупинки;
це знижує ризик «завислих» завдань і дає більш прогнозовану поведінку при перериваннях.

Автори Nanocode підтримують цей хост окремо: оновлення хоста не прив'язані до циклу оновлень Cloudflare Agents SDK, і можна розвивати логіку стійкості під потреби конкретних coding-агентів.

Як стартувати: референсний Worker і офіційний гайд

Щоб не будувати інтеграцію з нуля, команда Nanocode пропонує готовий приклад:

референсний Worker у репозиторії nanocode-cloudflare-durable — там показано, як:

ініціалізувати Durable Object з WebAssembly-рушієм Nanocode;
прокидати HTTP-запити клієнта до відповідного об'єкта (за сесійним ключем або id);
використовувати SQLite та alarms для збереження стану.

документація Cloudflare Nanocode on Workers описує:

початкове налаштування середовища Workers/Durable Objects;
конфігурацію моделей, з якими працює Nanocode;
обмеження на відновлення сесій (recovery limits), зокрема за часом і обсягом стану.

Практична послідовність для запуску за цим підходом виглядає так:

Склонуйте репозиторій nanocode-cloudflare-durable як стартовий проєкт.
Налаштуйте свій Cloudflare Worker та Durable Object згідно з інструкцією Nanocode on Workers.
Підключіть моделі, які ви плануєте використовувати, враховуючи обмеження за токенами і часом виконання.
Перевірте, як поводиться відновлення після переривань у ваших сценаріях (довгі задачі, ланцюжки інструментів).

Коли підхід із Nanocode без Agents SDK може бути корисним

Описаний хост не вимагає Cloudflare Agents SDK. Це підходить для сценаріїв, де:

вже є власна логіка роутингу запитів до моделей і немає бажання переносити все на Agents SDK;
потрібен контрольований, ізольований runtime для coding-агентів з чітким збереженням стану;
важлива сумісність з Codex/Claude Code промптами та інструментами без повної перебудови агентної системи.

У таких випадках Nanocode в Durable Objects дозволяє поєднати знайомі патерни coding-агентів із персистентним станом та механізмами відновлення, які надає платформа Cloudflare.

Джерело: Cloudflare Changelog