Запускайте команды сразу после создания Sandbox.create()

Что изменилось и зачем это нужно

Vercel изменил поведение создания sandbox: теперь вызов Sandbox.create() разрешается только после завершения восстановления снапшота (snapshot restoration). Это значит, что сразу после успешного создания можно выполнять команды и читать или записывать файлы — первая операция больше не «ждёт» восстановления.

Важная практическая деталь для поиска и отладки — точная форма вызова, показанная в документации: const sandbox = await Sandbox.create();. После этого можно вызывать команды без дополнительного ожидания, например: await sandbox.runCommand('node', ['--version']);.

Одновременно изменилось поведение ошибок при старте: если произошла ошибка запуска среды, она теперь отвергает (rejects) сам Sandbox.create(), а не проявляется позже при первой операции. То есть ошибка обнаруживается и обрабатывается на этапе создания.

Практические последствия для разработчиков

Теперь рабочий сценарий выглядит проще: вы вызываете await Sandbox.create(), получаете объект sandbox и сразу запускаете команды или работаете с файлами. Раньше первая операция могла блокироваться до завершения восстановления снапшота, и это требовало дополнительных проверок или ожиданий в коде.

На уровне задержки время восстановления снапшота теперь учитывается в операции создания. В типичном случае (p50) время создания увеличилось примерно на 50 мс; для сильно не кешированных снапшотов рост может быть больше. При этом суммарное время до завершения первой операции остаётся прежним: уменьшение ожидания в первой операции компенсирует добавление восстановления в создание.

Такое поведение упрощает обработку ошибок: если среда не стартует, вы увидите отказ сразу при Sandbox.create() и сможете выполнить логику повторной попытки или отката, не дожидаясь неопределённого поведения при первой команде.

Изменение применяется автоматически: для работы не требуется обновление SDK или изменение конфигурации. Достаточно использовать текущий код с вызовом Sandbox.create(), и новая семантика вступит в силу.

Как это выглядит в коде

Из документации видно два ключевых шага. Сначала создание и ожидание готовности: const sandbox = await Sandbox.create(); — этот вызов теперь завершается после восстановления снапшота и/или после обнаружения ошибок старта.

Затем можно запускать команды без дополнительного ожидания: await sandbox.runCommand('node', ['--version']);. Раньше вызов runCommand мог блокироваться до окончательного восстановления состояния среды; теперь он стартует сразу после create.

Таким образом стандартный поток создания и выполнения команд упрощается: await Sandbox.create(); → await sandbox.runCommand(...).

Ограничения и на что обратить внимание

Время создания увеличивается: восстановление снапшота теперь учитывается в вызове create. Для большинства случаев это мелкое увеличение (~50 мс на p50), но для uncached (не кешированных) снапшотов задержка может быть заметнее. Если у вас критически важны микрозадержки на этапе создания, это стоит учитывать в профилировании.

Хотя суммарное время до завершения первой операции не изменилось, распределение задержек изменилось: теперь латентность «перетянута» в момент создания. Это меняет точки мониторинга и перехвата ошибок — надо проверять успешность Sandbox.create(), а не полагаться на успешный ответ от первой команды.

Изменение автоматическое и не требует апдейта SDK, но код, который полагается на прежнее поведение (например, ожидал, что первая операция проявит ошибки старта), может потребовать корректировки логики обработки ошибок и логирования.

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