Filesystem Sandbox

Filesystem Sandbox is a new experimental feature in Unreal Editor 5.8 that creates a virtual filesystem inside your project's Intermediate directory to capture all asset changes made to your project through Unreal Editor. While sandboxed, asset changes are saved to a special sandbox directory tree until you explicitly persist them into your real project files — overwriting the originals with the versions you've approved for integration.

This means you can make more ambitious changes to your project without worrying about polluting your pristine project files until you've done a manual review of them.

💡 Filesystem Sandbox is experimental. You can customize how Aura uses sandboxing in Aura's Chat Settings.

How it works

When sandboxing is enabled, any asset Aura or you save is written to the sandbox directory tree rather than to your real project files. Your original files stay untouched until you accept them.

• Accept writes your changes back over the original files, integrating them into the project.
• Reject will attempt to revert changes back to its original state
• Until you persist, your real project files remain exactly as they were.

Working with source control

If you already use source control with file locking — such as Perforce or SVN — modified files will only require checkout when you accept the changes for persistence. Everything you do inside the sandbox stays out of source control until you're ready to commit to it.

Crash recovery

If you crash while in a sandbox, any modifications that were saved to the sandboxed filesystem will still be there when you return to the sandbox in a future session. Your in-progress work isn't lost.

If the crash happens while Aura is working, Automatic Crash Recovery relaunches the editor, re-enables the sandbox, and continues the task.

Reviewing changes

Aura comes with an improved interface that helps you understand exactly what changed for each modified asset, so you can review confidently before persisting.

💡 For the best diff experience, it's recommended you install P4Merge. Some assets can be diffed with the tools built into Unreal Editor, but many require an external merge tool to view their differences.

Gotchas

• Detailed diffs require a configured diff tool. Viewing detailed diffs of sandboxed assets requires your editor to have a diff tool configured for some assets. A few built-in diff tools come with Unreal Editor, but many assets require an external merge tool — installing P4Merge gives the best results.
• Changes must be saved to appear. Changes do not show up in the Sandbox change list until they have been saved to the filesystem. If something seems to be missing, double-check that you don't have any unsaved files.
• Manual changes are sandboxed too. Your own manual changes will appear in the sandbox alongside changes from any tools or agents.
• C++ is not sandboxed. Sandboxing only affects assets — C++ changes are not captured.
• Missing changes after a restart? If you had changes listed in the sandbox and don't see them anymore after restarting the editor, simply re-enabling sandbox should bring them back.
• Individual file rejection is still experimental and may sometimes fail on assets with dependency chains that involve multiple changed assets. This is to prevent putting the project into an inconsistent state.

FAQ

Can Aura automatically reload an old Sandbox/worktree state when it is launched for the first time?

If you've previously elected to use Sandbox, then by default the startup behavior is to load your sandbox at startup. You can change the sandbox startup behavior in Aura's Settings → Chat Options under Project section.

After Sandbox is no longer being used, do old Sandbox sessions or worktrees remain on the system?

Yes, but if there are no pending changes inside them, they are effectively empty.

How can I safely clean up these old Sandbox files without applying any changes to the main Unreal Engine project?

Go into your <ProjectDir>/Intermediate/Sandboxes to see your sandbox sessions. Each folder corresponds to a sandbox by name. The manifest.json file inside each folder has a list of modifiedFiles, addedFiles, and deletedFiles representing the differences in that sandbox. Deleting a sandbox folder is the same as discarding that sandbox session, though this is only possible if you're not actively inside the sandbox.

What exactly do the Accept all, Reject all, and Leave changes behind options do in relation to Unreal Engine assets?

• Accept all = writes the current state of all assets in your sandbox to the real project, meaning they will replace the original versions so that they persist after you leave the sandbox.
• Reject all = discards all sandbox changes, meaning the sandbox will be emptied and return to whatever state your real project files are in.
• Leave changes behind = no changes are made to your real project, but keeps the sandboxed asset changes safe inside the sandbox, meaning the sandboxed asset changes will stay in the sandbox and can be recovered or discarded later.

Does Reject all only delete the changes inside Sandbox, or can it perform any rollback/revert operation on the main project?

It should only delete the changes inside sandbox.

Can Accept all overwrite newer assets in the main project with older Sandbox assets?

Yes, this is possible. If you make changes in your sandbox, then also make changes to the same files outside of your sandbox, you will have to know which version you want to keep.

As a user, how can I definitively verify whether Aura is currently working on the main workspace or on a Sandbox/worktree?

When you've got Aura open, the presence of the sandbox overlay at the bottom of your chat is supposed to identify this. If you want an even more definitive status (and more control over sandboxes in general) you can enable the Sandboxed Editing plugin that ships with the engine, which allows you to manage multiple sandboxes and adds an indicator to the bottom of the editor screen showing which sandbox you are in (if any).

How can I locate the physical directory of the Sandbox/worktree folders created by Aura?

Aura's sandbox is located at <ProjectDir>/Intermediate/Sandboxes/AuraSandbox.

How can I completely disable Sandbox and ensure that Aura always opens only the current main Unreal Engine project from now on?

Go into Aura's Settings → Chat Options and disable Sandbox under the Project section, then change the sandbox startup behavior to Never.

What is the safest way to completely clean up old Sandbox data?

You can either use the Sandboxes window (found in the editor Window menu). This option becomes available after you've enabled the Sandboxed Editing plugin and restarted your editor. Alternatively, you can simply delete the sandbox files from your filesystem (as long as you don't currently have that sandbox loaded).