Sandbox (Preview)
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?
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 sandboxCreating a Sandbox
Click Create Sandbox
Click the flask icon in the toolbar, or use Command Palette → "Create Sandbox".
Confirm Creation
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
A new Sidekick 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
Sidekick uses git worktree to create sandboxes when possible, keeping them lightweight and fast. If git isn't available, it creates a full file copy.
Working in a Sandbox
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
| 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
When you're ready to apply sandbox changes to your original project:
Click Merge to Original
Click the "Merge to Original" button in the sandbox toolbar.
Review File Comparison
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
Manual Merge:
- Review each file's diff
- Edit the merged version if needed
- Apply when ready
Agent Merge:
- Click "Agent Merge" button
- Select model (Sidekick credits or custom)
- Agent intelligently combines changes
- Review Agent's merged result
Preview Changes
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
Click "Apply Selected" or "Apply All":
- Confirmation dialog shows summary
- System creates a git stash backup
- Changes write to original project
- Success dialog offers: Close Sandbox or Keep for Reference
Agent-Powered Merging
When files have conflicts (changed in both sandbox and original), the Agent can help:
How Agent Merge Works
- Agent analyzes both versions of each file
- Understands the intent of changes
- Combines modifications intelligently
- Explains its merge decisions
Agent Merge Benefits
- 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
If you don't want to keep the changes:
Click Discard
Click the trash icon in the sandbox toolbar.
Confirm Deletion
Dialog warns: "Permanently delete all changes. Cannot be undone."
Click Discard to confirm.
Sandbox Removed
- 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
You can switch between your original project and sandbox:
From Sandbox Window
- Click the "Sandbox Active" badge
- Or use Command Palette → "Switch to Linked Window"
From Original Window
- 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
Viewing All Sandboxes
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
You can only have one active sandbox per project. The "Create Sandbox" button is disabled if a sandbox already exists.
Best Practices
Before Creating a Sandbox
- 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
- Make focused changes — Easier to review later
- Test thoroughly — Verify changes work
- Don't mix unrelated changes — Keep it manageable
During Merge
- 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
- 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
- Sync across devices (local only)
- Merge to a different branch
- Handle binary file conflicts
- Auto-merge without review