OpenFn / OpenFn/lightning

sandboxes: update Provisioner API to support sandboxes

Open
#3,393 6 comments 0 reactions 1 assignee View on GitHub

@josephjclark is already working on this.

Since Feb 24, 2026.

needs technical design sandboxes and sync
Dominant language
Elixir
Stars
296
Forks
86
Avg merge
1d 13h
Merged PRs (30d)
50

Description

A key requirement of the Sandbox feature is that sandboxes can be created and modified through the CLI.

To that end, there's a bunch of changes needed in the provisioner API to support Sandboxes:

  • Allow new sandboxes to be created
  • Allow sandboxes to be modified
  • Return sandboxes related to a project
  • Respond to HEAD requests to tell us if a sandbox exists at a given URL

If a new sandbox is posted:

  • the incoming payload will include UUIDs
  • The new sandbox state should be returned, plus a URL to access it

The provisioner API should mirror the app: so instead of just asking for a project in the URL, clients will ask for a project and a sandbox. If no sandbox is provided then, for backwards compatibility, the base project is used (ie, default the sandbox to main, which is a synonym for the root project).

Sandboxes will be identified by name, rather than UUID.

provisioner/<projectid>/<sandbox-name>

Sandbox creation may be subject to account limits.

Additionally, the state.json which the provisioner accepts and returns will be a little different, and must support the new keys introduced in #3394

I don't think this is a breaking change, so the updated provisioner should retain full backwards compatibility.

We do want to introduce a strategy for versioning the provisioner API. We could choose to take that on here, but I think we can defer it.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.