Rebasely Beta: data may be purged
Docs menuSandboxes
View as Markdown

Sandboxes

A sandbox is a hidden branch for one task. Create it from any branch or commit in milliseconds, push to it, run its checks, and merge it back with one command. Agents get one per task; people use them for experiments that should not clutter the branch list.

A sandbox, from creation to merge1. A sandbox is created from a commit of main in milliseconds, as the hidden ref refs/sandbox/a-fixer/fix-login. 2. Its owner pushes commits to it; it never shows up in branch lists or clones. 3. Workflows that declare on: sandbox run its checks. 4. When they pass, the sandbox merges back into main as a fast-forward, a merge commit or one squashed commit, and ends.mainrefs/sandbox/a-fixer/fix-loginhidden from branch lists and cloneschecks passed1 create2 push3 checks4 merge
A sandbox leaves main as a hidden ref, gets its own commits and checks, and merges back.

How a sandbox works

  • Its ref is refs/sandbox/<owner>/<name>. The owner is a-<agent> for an agent and u-<id> for a person; the name is yours to pick (lowercase letters, digits, ., _ and -, up to 64), or a generated one.
  • It does not show up in branch lists, ref advertisements or clones. Fetch it by name when you need it.
  • Only its owner and the repository's owners push to it. A push never creates one: create it with the CLI, the API or the sandbox.create tool.
  • It expires after 24 hours without a push. People can ask for up to 30 days, agents up to 7. An ended sandbox is kept for 7 days for its history.

From creation to merge

  1. Create it

    From main, with a git worktree for it next to your clone:

    Shell
    rebasely sandbox create --from main --name fix-login --worktree ../fix-login

    Without --worktree, the CLI prints the fetch, worktree and push commands instead.

  2. Push to it

    Shell
    cd ../fix-login
git commit -am "Fix the login redirect"
git push origin HEAD:refs/sandbox/<owner>/fix-login

  3. Run its checks

    Workflows run on a sandbox only if they declare on: sandbox, and such runs never get secrets. --wait follows them and exits 1 if one fails.

    Shell
    rebasely sandbox checks fix-login --wait

  4. Merge it

    Shell
    rebasely sandbox merge fix-login --into main --mode squash

    --mode is ff (the default), merge or squash. A merge or a squash writes a commit, which needs an account at least 7 days old or a verified one. A conflicting merge writes nothing and lists the files and lines. --expect <sha> refuses the merge if the sandbox moved since you read it.

Or open a pull request from the sandbox when people should review it first. rebasely sandbox list and rebasely sandbox delete do what they say.

The API and MCP

Shell
rebasely sandbox create --from main --name fix-login
rebasely sandbox merge fix-login --into main
Shell
curl -fsS -X POST -H "Authorization: Bearer $REBASELY_TOKEN" -H "content-type: application/json" \
  -d '{"from":"main","name":"fix-login"}' https://rebasely.com/api/v1/repos/<org>/<repo>/sandboxes
JSON
{"name": "sandbox.create", "arguments": {"repo": "<org>/<repo>", "from": "main", "name": "fix-login"}}
RequestWhat it does
GET /sandboxesThe repository's sandboxes (?mine=1, ?ended=1)
POST /sandboxesCreate one: {from?, name?, ttl_s?, live?}
GET, DELETE /sandboxes/<owner>/<name>Read or delete one
POST /sandboxes/<owner>/<name>/mergeMerge: {into?, mode?, expect?, message?, delete?}
POST /sandboxes/<owner>/<name>/checksRun its on: sandbox workflows

Paths are under /api/v1/repos/<org>/<repo>. A person's token needs repo:write, an agent's sandbox:write. A sandbox created with {"live": true} works like any live branch until it is merged or deleted.

Limits and settings

At most 20 active sandboxes per person or agent in a repository, 200 per repository and 1,000 per organization. An owner can turn sandboxes off for a repository in its settings, under Live and sandboxes. Creating one then fails with sandboxes_disabled; existing sandboxes can still be pushed, merged and deleted.