# Sandbox (Preview)

Sandbox Demo  
1x  
Sandbox lets you experiment with Agent-generated changes in complete isolation. Test modifications, review diffs, and only apply what you want—without risking your original project.

Sandbox is a **preview feature**. We recommend committing your changes and creating a backup before using it.

## [What is a Sandbox?](/content/docs/sandbox#what-is-a-sandbox/index.html)
A sandbox is an isolated copy of your project where you can:

- **Experiment freely** — Let the Agent make changes without affecting your main code
- **Review before applying** — See exactly what changed with side-by-side diffs
- **Merge intelligently** — Use the Agent to combine sandbox changes with your original files
- **Discard safely** — Delete all changes if you're not satisfied

```
Original Project
        ↓
Create Sandbox → Isolated Copy
        ↓
Agent makes changes in sandbox
        ↓
Review & Compare
        ↓
Apply selected changes → Original Project
        or
Discard → Delete sandbox
```

## [Creating a Sandbox](/content/docs/sandbox#creating-a-sandbox/index.html)

### [Click Create Sandbox](/content/docs/sandbox#click-create-sandbox/index.html)
Click the **Plus icon** in the top bar near the project name, or use Command Palette → "Create Sandbox".

### [Confirm Creation](/content/docs/sandbox#confirm-creation/index.html)
A dialog appears with recommendations:

- Commit your current changes
- Create a backup
- Review changes carefully before applying

Click **Create Sandbox** to proceed.

### [New Window Opens](/content/docs/sandbox#new-window-opens/index.html)
A new Invoke window opens with your sandbox. You'll see:

- **"Sandbox Active"** badge in the toolbar
- **Orange "SANDBOX"** indicator in the file explorer
- Sandbox ID in the window title

## [Working in a Sandbox](/content/docs/sandbox#working-in-a-sandbox/index.html)
Once in a sandbox, work normally with the Agent:

- Ask the Agent to make changes
- Edit files manually
- Run terminal commands
- Test your application

All changes are isolated to the sandbox—your original project is untouched.

### [What's Different in Sandbox Mode](/content/docs/sandbox#whats-different-in-sandbox-mode/index.html)

| Feature                | Sandbox Behavior          |
|-----------------------|---------------------------|
| **File changes**      | Saved to sandbox only     |
| **Git push/pull**    | Disabled (use Merge instead) |
| **Terminal commands** | Run in sandbox directory   |
| **Agent file edits**  | Write to sandbox files     |

## [Merging Changes Back](/content/docs/sandbox#merging-changes-back/index.html)
When you're ready to apply sandbox changes to your original project:

### [Click Merge to Original](/content/docs/sandbox#click-merge-to-original/index.html)
Click the **"Merge to Original"** button in the sandbox toolbar.

### [Review File Comparison](/content/docs/sandbox#review-file-comparison/index.html)
The merge panel shows all changed files:

| Icon  | Meaning                                    |
|-------|--------------------------------------------|
| Orange| Conflict — modified in both places         |
| Green | New file — created in sandbox              |
| Blue  | Modified — changed in sandbox only         |
| Red   | Deleted — removed in sandbox               |

Use checkboxes to select which files to include.

### [Choose Merge Method](/content/docs/sandbox#choose-merge-method/index.html)
**Manual Merge:**

- Review each file's diff
- Edit the merged version if needed
- Apply when ready

**Agent Merge:**

- Click **"Agent Merge"** button
- Select model (Invoke credits or custom)
- Agent intelligently combines changes
- Review Agent's merged result

### [Preview Changes](/content/docs/sandbox#preview-changes/index.html)
For each file, you can:

- **Diff tab** — See side-by-side comparison (read-only)
- **Edit tab** — Modify the merged result
- Navigate between files with Previous/Next

### [Apply Changes](/content/docs/sandbox#apply-changes/index.html)
Click **"Apply Selected"** or **"Apply All"**:

1. Confirmation dialog shows summary
2. System creates a git stash backup
3. Changes write to original project
4. Success dialog offers: Close Sandbox or Keep for Reference

## [Agent-Powered Merging](/content/docs/sandbox#agent-powered-merging/index.html)

### [How Agent Merge Works](/content/docs/sandbox#how-agent-merge-works/index.html)
1. Agent analyzes both versions of each file
2. Understands the intent of changes
3. Combines modifications intelligently
4. Explains its merge decisions

### [Agent Merge Benefits](/content/docs/sandbox#agent-merge-benefits/index.html)
- **Handles conflicts automatically** — No manual conflict resolution
- **Preserves intent** — Understands what you were trying to do
- **Shows reasoning** — Explains why it merged the way it did
- **Fully editable** — You can modify the Agent's result before applying

During Agent merge, file writes to the sandbox path are **blocked**. The Agent writes directly to your original project paths, preventing accidental data loss.

## [Discarding a Sandbox](/content/docs/sandbox#discarding-a-sandbox/index.html)
If you don't want to keep the changes:

### [Click Discard](/content/docs/sandbox#click-discard/index.html)
Click the **trash icon** in the sandbox toolbar.

### [Confirm Deletion](/content/docs/sandbox#confirm-deletion/index.html)
Dialog warns: "Permanently delete all changes. Cannot be undone."

Click **Discard** to confirm.

### [Sandbox Removed](/content/docs/sandbox#sandbox-removed/index.html)
- All sandbox files deleted
- Git worktree/branch removed
- Sandbox window closes
- Original project unchanged

Discarding is permanent. All changes in the sandbox are lost and cannot be recovered.

## [Switching Between Windows](/content/docs/sandbox#switching-between-windows/index.html)
You can switch between your original project and sandbox:

### [From Sandbox Window](/content/docs/sandbox#from-sandbox-window/index.html)
- Click the **"Sandbox Active"** badge
- Or use Command Palette → "Switch to Linked Window"

### [From Original Window](/content/docs/sandbox#from-original-window/index.html)
- Click the **flask icon** in the toolbar
- Or use the **Sandbox Windows dropdown** to see all sandboxes

Both windows stay linked—switching brings the other window to focus.

## [Managing Multiple Sandboxes](/content/docs/sandbox#managing-multiple-sandboxes/index.html)

### [Viewing All Sandboxes](/content/docs/sandbox#viewing-all-sandboxes/index.html)
Click the **Sandbox Windows dropdown** (flask icon with chevron) to see:

- All sandboxes for current project
- Creation timestamp
- Status (Active, Available, Invalid)

### [One Active Sandbox Per Project](/content/docs/sandbox#one-active-sandbox-per-project/index.html)
You can only have one active sandbox per project. The "Create Sandbox" button is disabled if a sandbox already exists.

## [Best Practices](/content/docs/sandbox#best-practices/index.html)

### [Before Creating a Sandbox](/content/docs/sandbox#before-creating-a-sandbox/index.html)
- **Commit your changes** — Have a clean git state
- **Push to remote** — Extra backup on server
- **Note what you want to test** — Clear goal helps

### [While in Sandbox](/content/docs/sandbox#while-in-sandbox/index.html)
- **Make focused changes** — Easier to review later
- **Test thoroughly** — Verify changes work
- **Don't mix unrelated changes** — Keep it manageable

### [During Merge](/content/docs/sandbox#during-merge/index.html)
- **Review diffs carefully** — Understand what changed
- **Use Agent merge for conflicts** — Let the Agent handle complex merges
- **Edit merged results** — Don't blindly accept
- **Apply incrementally** — Select specific files if unsure

### [After Applying](/content/docs/sandbox#after-applying/index.html)
- **Test in original** — Verify changes work there too
- **Commit promptly** — Don't leave changes uncommitted
- **Discard sandbox** — Clean up when done

### [What Sandbox Cannot Do](/content/docs/sandbox#what-sandbox-cannot-do/index.html)
- Sync across devices (local only)
- Merge to a different branch
- Handle binary file conflicts
- Auto-merge without review