Control what the desktop agent can do

The SynapseX Desktop agent can edit your files and run shell commands on your machine. This page shows you how to decide, up front, how much of that it is allowed to do without asking. At the end you will have a security mode set and you will have seen a real permission prompt appear before a command runs.

Where do I set it?

Settings (macOS: Cmd+,) → section SynapseX AI → tab Permissions → Agent security mode.

There are three modes: Full access, Sandboxed and Strict.

What exactly does each mode do?

Each mode is a concrete rule set applied per tool. allow runs without asking, ask shows you a prompt first, deny refuses outright.

Read across the rows to see the character of each mode:

• Full access allows everything, including reaching outside the project folder.
• Sandboxed keeps everything that stays inside your project automatic — reading, editing, searching, listing — and asks before anything that touches the shell, the network, or a directory outside the project.
• Strict never lets the agent touch files outside the project at all (external_directory is denied, not prompted), and asks before essentially everything else. Only todowrite, question and lsp stay automatic, because they have no file, system or network side effects of their own.

Which mode should I pick?

Sandboxed for normal work. It removes the prompt fatigue of confirming every file read while still stopping the agent at the two boundaries that matter: your shell and everything outside the project.

Strict for an unfamiliar or sensitive repository. If you have not read the repository yourself, or it contains credentials, customer data or production configuration, Strict is the mode where a mistake costs you one declined prompt instead of a bad edit. The external_directory: deny rule is the important part — the agent cannot wander into your home directory or a sibling project.

Full access only in a throwaway workspace. A scratch clone you can delete, in a container or VM. Do not run it in a repository whose working copy you would miss.

Is this a real control or a label?

It is real. Selecting a mode writes the rule bundle above into the running agent server’s configuration, and the server enforces it per tool call. The same bundle backs both the Settings tab and the in-session permission selector, so both surfaces always mean the same thing.

What does a prompt look like in practice?

When the agent tries to use a tool set to ask, the session stops and shows you what it wants to do — for example the exact shell command it intends to run — and waits.

• Accept and the agent runs that action and continues the turn.
• Decline and the action does not happen. The agent is told the request was refused and carries on with the rest of the turn, usually by trying a different approach or telling you it cannot proceed. Declining a prompt does not end or corrupt the session.

How does auto-accept interact with the mode?

Each project has an auto-accept toggle on the same Permissions tab, under the section for the current project. It does not change your mode’s rules — it answers the prompts for you.

So Sandboxed with auto-accept on behaves, in practice, much like Full access for that project: bash is still classed as “ask”, but nobody is being asked. A deny rule still holds — Strict will not run an external-directory operation even with auto-accept on — but every ask becomes automatic.

Leave auto-accept off while you are still deciding whether to trust a repository.

Verify it yourself

1. Open Settings → SynapseX AI → Permissions and select Strict.

2. Open a project and start a session (Shift+Cmd+S on macOS).

3. Ask the agent for something that needs the shell, for example:

   Run `git status` in this project and tell me which files are modified.

4. The session stops and shows a permission prompt for the bash tool before the command runs. Decline it and the command does not execute; accept it and you get the output.

If you never see a prompt, check that auto-accept is off for this project.

Next step

With permissions set, go and do real work: Work on a project with the desktop agent.