Security & Sandbox

PicoClaw runs in a sandboxed environment by default. The agent can only access files and run commands within the configured workspace.

Default configuration

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

Option	Default	Description
`workspace`	~/.picoclaw/workspace	Working directory for the agent
`restrict_to_workspace`	true	Restrict file/command access to workspace

Protected tools

When restrict_to_workspace: true, these tools are sandboxed:

Tool	Function	Restriction
read_file	Read files	Only within workspace
write_file	Write files	Only within workspace
list_dir	List directories	Only within workspace
edit_file	Edit files	Only within workspace
append_file	Append to files	Only within workspace
exec	Execute commands	Paths must be within workspace

Additional exec protection

Even with restrict_to_workspace: false, the exec tool blocks:

rm -rf, del /f, rmdir /s — bulk deletion
format, mkfs, diskpart — disk formatting
dd if= — disk imaging
Writing to /dev/sd[a-z]
shutdown, reboot, poweroff
Fork bomb :(){ :|:& };:

Error examples

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}

Disabling restrictions (security risk)

Only in controlled environments. Config:

"agents": { "defaults": { "restrict_to_workspace": false } }

Or environment: PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false. Disabling allows the agent to access any path on your system.

Security boundary consistency

restrict_to_workspace applies to main agent, subagents (spawn), and heartbeat tasks. There is no way to bypass the boundary via subagents or scheduled tasks.