CH 28 · Security and Compliance

Word count~3,490 wordsTime~20 minPrereqCH 04LevelConceptual focus

Chapter Goal

Let an Agent that can run commands and write files work on your computer — will you worry: will it randomly delete my files? Will it secretly send my keys out? Will it change my system settings?

These worries are valid — an Agent without security boundaries is a ticking time bomb. dsh's answer is three layers of protection: file sandbox, operation approval, write-only keys. CH 04 mentioned some when talking about the permission model; this chapter makes the principles of each layer clear — how it really keeps the Agent in check, which are hard boundaries you can't get around, and which need your own judgment. Once you understand these, you'll know what you can safely hand over and what you must watch yourself.

First Clarify: dsh's Security Thinking

The core of dsh's security design is eight characters: restricted by default, allow on demand.

Not "give all permissions first, then rely on your caution", but the other way around — by default it can only touch the scope you explicitly allow, and to cross the line it must get your consent. This is a completely different mindset from "give it the admin password and let it figure it out".

Three layers of protection, from outside to inside:

Layer	What it manages	How
Layer 1: file sandbox	Which files it can touch	Three permission levels, OS kernel-level isolation
Layer 2: operation approval	Whether sensitive operations can execute	Pop-up asking you, you say no and it doesn't run
Layer 3: write-only keys	How API Keys are stored	Write-only, not displayed in UI, local storage not uploaded

Each layer below.

Layer One: File Sandbox

CH 04 covered the three permission levels; here's the principle behind them.

The sandbox isn't a piece of JavaScript doing an if check — "if the path is not in the workspace, error out". That kind of approach the model can bypass (e.g. with relative path jumps, with symlinks). dsh's sandbox is OS kernel-level: on Windows it uses job objects to limit the resources a process can access, on Linux/macOS it uses namespaces and seccomp to filter system calls. No matter what tricks the model uses, if it can't pass the kernel, it can't pass.

The three permission levels, strict to loose:

Mode	What it can write	What scenarios it's for
read-only	Nothing	Read-only analysis, code review, pure Q&A — let it see but not change
workspace-write (default)	Only the current workspace directory + system temp directory	Daily work — can change project files, can't touch the system or other projects
danger-full-access	No restrictions	Only when you clearly need full-disk operation, e.g. system maintenance, installing software — risk is on you

An easily overlooked point: the sandbox only governs file system side effects, not network or process isolation. That means, under workspace-write mode, the Agent can't write files outside the workspace, but it can make network requests, can read files outside the workspace (read-only). So don't think that turning on workspace-write is absolutely safe — it can send sensitive file content from your workspace out via API requests (a normal model won't do this, but it's a theoretical boundary).

Switching was covered in CH 04: temporarily for the current session use /permission, to change the default go to Settings → General → Permission (only affects newly created sessions).

Layer Two: Operation Approval

The sandbox keeps "which files it can touch" in check, approval keeps "whether sensitive operations can execute" in check.

When the Agent wants to do something beyond the current permission scope — e.g. write a file outside the workspace in workspace-write mode, or execute a command that might change the system — it doesn't just run, but first initiates an approval request, the interface pops up a dialog telling you:

• What operation it wants to execute (the specific command or file path)
• Why it wants to do this (the model's reason)

Then you get three choices: Allow once, Deny, Cancel.

Image placeholder: put a screenshot here of "Agent requests writing a file outside the workspace, approval dialog pops up" — you can see the operation, the model's reason, the allow/deny buttons.

A few key details:

1. Allow once means once — not "always allowed in the future". Next time the same operation comes up, it will ask again.
2. Deny means deny — once the model receives the denial, it will find another path or tell you it can't do it, not sneak around.
3. Approval is a plugin-level extension point — CH 11 covered the tool call pipeline, approval is one stage. You can write your own plugin to customize approval policy, e.g. "auto-allow some commands, auto-deny some".

Approval and the sandbox work together: the sandbox is a hard boundary (kernel-level, can't bypass), approval is a soft boundary (policy-level, can let through). Daily use of workspace-write + approval pop-up is the balance of "secure by default, manually allow when needed".

Layer Three: Write-Only Keys

The API Key is the most sensitive thing — if lost, others can use your quota, even use your identity to call APIs. dsh's handling of keys is write-only.

What does write-only mean? After you fill in the API Key in Settings → Models and click save, the Key on the interface "disappears", leaving only a redacted descriptor (e.g. deepseek://sk-...x8f2). You can never read the complete plaintext Key back from the interface.

This isn't a bug, it's deliberate design:

• The plaintext Key only lands in the local $DSH_HOME/.credentials.yaml (on Windows: C:\Users\<your-username>\.dsh\.credentials.yaml)
• The interface and settings.yaml only store a reference (like apiKeyEnv field), not plaintext
• Browser memory, network logs, front-end state will not secondarily expose the complete Key

Image placeholder: put a screenshot here of "Settings → Models page, DeepSeek card after saving only shows the redacted descriptor" — you can see the key field has become deepseek://sk-...xxxx format.

Key priority (from high to low):

1. Process environment variable (export DEEPSEEK_API_KEY=sk-xxx)
2. $DSH_HOME/.credentials.yaml file
3. Project directory's .env file

Environment variable has the highest priority, suited for temporary use; file method is most commonly used, suited for long-term config.

Security reminder: the .credentials.yaml file has 0600 permissions (only you can read/write), but if you back up the entire ~/.dsh directory to the cloud or share with others, the keys go with it. Be careful to redact when backing up.

Data Privacy

Besides keys, all data dsh produces is also local:

Data	Where it's stored	Will it be uploaded?
Session records	~/.dsh/sessions/	No
Trajectory	Embedded in session records	No
Plugin config	~/.dsh/profiles/	No
API Key	~/.dsh/.credentials.yaml	No
Workspace files	Your selected workspace directory	No

dsh has no cloud sync, no account system, no telemetry reporting. Your conversation content with the model is only sent to the model provider (DeepSeek etc.) when you send the request, dsh itself doesn't keep a copy in the cloud.

This means:

• Benefit: data is completely in your hands, privacy is controllable
• Cost: switching computers requires manually migrating the ~/.dsh directory, no one-click sync

Security Best Practices

Putting the above mechanisms into daily use, remember these:

1. Use workspace-write daily, don't keep full access on — under full access the sandbox is effectively gone, the Agent can touch your entire hard drive. Only temporarily turn it on when you clearly need system-level operation, and switch back when done.
2. Don't push the ~/.dsh directory directly to GitHub — there's a .credentials.yaml plaintext key in it. If you need to back up the config, export settings.yaml separately (without keys), and manage the keys separately.
3. Docker team deployment: note no multi-user isolation — CH 27 covered, in the current version everyone uses the same Basic Auth to log in and sees the same session and config. When the team shares it, don't store sensitive information in it, or have each person deploy an independent instance.
4. Pick a clean directory as the workspace — don't set the entire C:\Users or home directory as the workspace. Pick a dedicated project directory, and the Agent's touchable range is limited to there.

What you learned in this chapter

You pass if you can complete the items below:

• [ ] Know the core idea of dsh's security design: restricted by default, allow on demand
• [ ] Know what the three layers of protection are: file sandbox, operation approval, write-only keys
• [ ] Know the sandbox is OS kernel-level, not JS if check, the model can't get around it
• [ ] Can clearly state the differences between the three permission levels (read-only / workspace-write / danger-full-access) and applicable scenarios
• [ ] Know that approval is "allow once", not permanent
• [ ] Know the API Key is write-only, after saving the interface doesn't echo back, the plaintext is only in the local .credentials.yaml
• [ ] Know all dsh data is local, no cloud sync
• [ ] Can state at least 3 daily security best practices