Workspace & sandbox

Sovereign vessel. A sovereign agent runs in a space you control. The settings on this page decide exactly which folders it can reach and where its code runs, granted deliberately by you, not inherited from a platform. See what makes an agent sovereign.

Two ways to run

Turn the sandbox on for a conversation in its chat settings, or for every conversation in Settings → Security.

Where files go

Every project has its own workspace folder, shared by all of the project's conversations, plus one folder shared by every project:

In host mode the agent works with the real folders on your computer, so the sandbox paths don't exist there; shell commands use the variables instead. $PROJECT_PATH and $SHARED_PATH work in the sandbox too, so scripts that use them run in either mode.

On your computer, these folders live under ~/.suzent/sandbox/: projects/<project>/ for each project's workspace and shared/ for the shared folder.

Conversations start in the default project. Use New project in the sidebar (or Move to project on a chat) to group related conversations, so they share a workspace and project memory without seeing another project's files.

The agent cannot read outside these folders. Paths such as /etc/passwd, ../../secret, or Suzent's own source code are refused.

Giving the agent access to your folders

To let the agent work on a folder from your computer, mount it.

The quickest way is the Working Dir button in the chat box: choose a folder, or pick one from Recent folders, and it's mounted for that conversation. Click it again to see or remove what's mounted.

To mount a folder for every conversation, add a line per folder to ~/.suzent/config/local.yaml (settings in that file stay on this computer), in the form "folder on your computer:path the agent sees":

sandbox_volumes:
  - "D:/datasets:/data"
  - "C:/Users/you/Documents/MyVault:/mnt/notebook"

Now the agent sees D:/datasets/file.csv as /data/file.csv. In host mode, shell commands reach the same folder through a variable named after the path: /data becomes $DATA, and a path under /mnt/ such as /mnt/notebook becomes $MOUNT_NOTEBOOK.

Using the sandbox

1. Install Docker and make sure it is running.
2. Turn the sandbox on (see above).

That's it. Each conversation gets its own container the first time it runs a command. The container is restarted automatically if it crashes and stopped after 30 minutes of inactivity. Your files are kept on your computer, so they survive the container being stopped or removed.

By default the container has Python and the shell, can use the internet, and is limited to 512 MB of memory and one CPU. Common changes, in ~/.suzent/config/default.yaml:

sandbox_network: none          # cut the sandbox off from the internet
sandbox_image: suzent-sandbox  # Python + Node.js + common data packages

To use the suzent-sandbox image, build it once from your Suzent folder with docker compose -f docker/sandbox-compose.yml build.

Undoing the last turn (Retry)

Not happy with an answer? Click the retry icon (↺) under the agent's last reply, or send /retry in a chat app. Suzent rolls back everything that turn did and runs your message again:

• the conversation itself,
• files the agent created or edited with its file tools, wherever they are.

Two limits to know:

• Only the last turn can be retried. There is no multi-step undo.
• Changes made by shell commands are not undone, such as installed packages or files a script wrote. Keep your own backups (or Git) for anything important.

Troubleshooting