Vercel изменил lifecycle Sandbox так, чтобы объект после Sandbox.create() действительно означал готовую среду выполнения.

Раньше создание могло завершиться до конца восстановления snapshot. В результате первая команда или файловая операция неожиданно ждала оставшуюся часть startup.

Теперь promise Sandbox.create() разрешается только после завершения snapshot restoration.

Что изменилось в поведении API

Новая схема выглядит проще:

const sandbox = await Sandbox.create();

// sandbox уже готов
await sandbox.runCommand('node', ['--version']);

После возврата из create() можно сразу запускать команду или читать и записывать файлы.

Дополнительного ожидания восстановления snapshot на первой операции больше нет.

Почему старое поведение было неудобным

С точки зрения кода разработчик видел успешный await Sandbox.create() и логично считал, что environment уже готов.

Но реальная startup latency могла проявиться только на следующем действии.

Для обычного script это просто несколько дополнительных миллисекунд ожидания. Для agent runtime это влияет на архитектуру сильнее.

AI-agent обычно выполняет цепочку:

1. создать sandbox;
2. загрузить или восстановить workspace;
3. запустить первую команду;
4. посмотреть результат;
5. продолжить задачу.

Если этап 2 частично скрыт внутри этапа 3, метрики и обработка ошибок становятся менее очевидными.

Startup errors теперь появляются раньше

Вторая важная часть изменения — ошибки запуска.

Если sandbox не смог корректно стартовать, теперь должен reject сам Sandbox.create().

Раньше startup failure мог проявиться уже во время первой команды или файловой операции.

Это усложняло диагностику: приложение считало create успешным и обрабатывало проблему как ошибку конкретной команды, хотя сама среда так и не стала готовой.

Sandbox не стал магически быстрее

Здесь легко неправильно прочитать анонс.

Vercel не утверждает, что snapshot restoration исчез.

Время просто учитывается в другом месте: раньше часть ожидания попадала в первую операцию, теперь вся startup-фаза завершена до возврата из Sandbox.create().

По данным Vercel, creation на p50 стала примерно на 50 мс дольше. Для uncached snapshots увеличение может быть больше.

Общее время до первой команды остаётся примерно тем же

Vercel отдельно отмечает, что total time через первую operation остаётся тем же.

То есть ускорение здесь в первую очередь архитектурное и UX API, а не физическое сокращение всей startup цепочки.

Первая команда выглядит быстрее именно потому, что ожидание уже произошло там, где оно логически должно находиться — во время создания среды.

Почему это полезно для AI-агентов

Agent runtime обычно управляет множеством короткоживущих environments.

Для каждой задачи может создаваться отдельный sandbox, восстанавливаться snapshot и запускаться набор команд.

Предсказуемое состояние после create позволяет проще строить orchestrator:

• не нужен отдельный workaround перед первой командой;
• легче измерять startup latency;
• проще повторять create при startup failure;
• ошибка не смешивается с ошибкой пользовательской команды;
• worker можно считать ready сразу после успешного create.

Особенно полезно при параллельном создании sandboxes

Представим систему, которая запускает 20 coding agents параллельно.

Каждый получает отдельный environment из snapshot.

Если create возвращает объект в промежуточном состоянии, orchestrator вынужден учитывать скрытый startup на следующем шаге каждого worker.

После изменения контракт проще: завершённый create означает готовность выполнять task.

Что происходит с snapshots

Snapshot по-прежнему нужен для быстрого запуска environment в заранее подготовленном состоянии.

В нём могут находиться зависимости, системные пакеты, проектные файлы или другая база, которую нет смысла готовить с нуля для каждого агента.

Изменение касается момента, когда Vercel считает процесс восстановления завершённым относительно API.

Нужно ли обновлять SDK

Нет. Vercel пишет, что изменение применяется автоматически.

Не требуется:

• обновлять SDK только ради этого поведения;
• менять конфигурацию sandbox;
• добавлять новый флаг;
• переписывать обычный вызов Sandbox.create().

Существующий код должен получить более предсказуемую семантику автоматически.

Может ли код заметить изменение

Да, если приложение отдельно измеряет latency create и первой команды.

В такой телеметрии часть времени переместится:

• Sandbox.create() может стать немного дольше;
• первая command/file operation — короче;
• общая цепочка до завершения первой операции останется близкой к прежней.

Это нужно учитывать, если внутренний SLA или dashboard построен именно на времени отдельных API calls.

Обработка ошибок становится чище

Теперь можно разделять два типа проблем.

try {
  const sandbox = await Sandbox.create();
  await sandbox.runCommand('npm', ['test']);
} catch (error) {
  // create failure и command failure можно классифицировать
}

На практике приложение всё равно должно различать источник ошибки, но startup failure больше не должен маскироваться под проблему первой операции.

Sandbox и безопасность — разные задачи

Готовность environment после create не говорит о том, какие права получает запускаемый внутри него код.

Если sandbox используется для AI-generated code, отдельно нужно контролировать:

• network access;
• secrets;
• filesystem;
• лимиты CPU и memory;
• время выполнения;
• доступ к внешним API.

Мы недавно разбирали похожий вопрос на локальной стороне в статье про local sandboxing GitHub Copilot.

Что проверить после изменения

Практический вывод

Изменение небольшое, но делает API более честным.

После успешного Sandbox.create() разработчик получает environment, который действительно готов к работе. Это особенно полезно для agent orchestration, где lifecycle каждой временной среды должен быть максимально однозначным.

Vercel не сократил общий startup за счёт этого изменения — ожидание snapshot просто перенесено в правильную фазу.

Официальный источник

Vercel Changelog — Vercel Sandbox creation now returns a ready sandbox