Workspace

Sandbox agent file operations inside a safe, per-session directory

Workspace sandboxing provides secure, isolated file access for agents, ensuring file operations stay within designated boundaries.

Two workspace concepts: The workspace= parameter on Agent (this page) sandboxes file-tool paths at the agent level. The Workspace Boundary gate (workspace_root on PermissionManager) enforces permission-engine rules for both file tools and shell commands at the rule level. Both can be used together for defence-in-depth.

from praisonaiagents import Agent

agent = Agent(
    name="file-assistant",
    instructions="Read and write files only inside the workspace.",
    workspace="./sandbox",
)
agent.start("List files in the project workspace")

The user chats with the agent; file tools stay confined to the workspace root.

Quick Start

1. Basic Bot with Workspace

   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   
   agent = Agent(
       name="Assistant",
       instructions="You help users with files and tasks"
   )
   
   # Workspace is applied automatically when agent runs as a bot
   bot = TelegramBot(token="YOUR_TOKEN", agent=agent)
   
2. Custom Workspace Configuration

   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   from praisonaiagents import BotConfig
   
   config = BotConfig(
       token="YOUR_TOKEN",
       workspace_dir="./my-bot-workspace",  # custom path
       workspace_access="rw",                # "rw" | "ro" | "none"
       workspace_scope="session",            # "shared" | "session" | "user" | "agent"
   )
   
   bot = TelegramBot(config=config, agent=agent)
   

---

How It Works

Workspace containment operates through three key mechanisms:

Mechanism	Purpose	Implementation
Path Resolution	Resolve paths against workspace root	workspace.resolve(path)
Containment Check	Verify paths stay within boundaries	workspace.contains(path)
Access Control	Enforce read/write permissions	Access mode validation

---

Configuration Options

Workspace Access Modes

Workspace Configuration

Option	Type	Default	Description
root	Path	required	Absolute workspace directory (auto-created; refuses /)
access	"rw", "ro", "none"	"rw"	Read-write, read-only, or copy-on-write sandbox
scope	"shared", "session", "user", "agent"	"session"	Workspace scope level
session_key	Optional[str]	None	Session identifier for scope resolution

BotConfig Workspace Fields

Option	Type	Default	Description
workspace_dir	Optional[str]	None → ~/.praisonai/workspaces/<scope>/<session_key>	Override workspace path
workspace_access	str	"rw"	Access mode
workspace_scope	str	"session"	Scope level

---

Common Patterns

Scope Selection Guide

# Shared workspace (all users/agents share files)
config = BotConfig(workspace_scope="shared")

# Session workspace (isolated per conversation)
config = BotConfig(workspace_scope="session")  # default

# User workspace (isolated per user)
config = BotConfig(workspace_scope="user")

# Agent workspace (isolated per agent instance)
config = BotConfig(workspace_scope="agent")

Advanced Path Operations

from praisonaiagents.workspace import Workspace
from pathlib import Path

workspace = Workspace(
    root=Path("./my-workspace").resolve(),
    access="rw"
)

# Check if path is contained
if workspace.contains("user-file.txt"):
    # Safe to access
    safe_path = workspace.resolve("user-file.txt")

# Handle path traversal attempts
try:
    bad_path = workspace.resolve("../../../etc/passwd")
except ValueError as e:
    print(f"Security violation: {e}")

Read-Only Workspace

# Prevent any file modifications
config = BotConfig(
    workspace_access="ro",
    workspace_dir="./read-only-data"
)

---

Best Practices

Choose the Right Scope

Use "session" (default) for most chat bots to isolate conversations. Use "shared" only when agents need to collaborate on files. Use "user" for personal assistants. Use "agent" for specialized single-purpose bots.

Security by Construction

Workspaces reject filesystem root access, resolve symlinks to prevent macOS issues, and validate all path operations. Never bypass workspace containment in production deployments.

Default Path Layout

The default workspace structure is ~/.praisonai/workspaces/<scope>/<session_key>/. This ensures clean separation and predictable file organization across different deployment scenarios.

Backward Compatibility

File tools fall back to os.getcwd() when no workspace is configured, maintaining compatibility with existing code. Bots automatically apply workspace containment for security.

---

Related

Bot Default Tools

Auto-injected tools that work with workspaces

Self-Improving Skills

How skills interact with workspace containment