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.

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:

Configuration Options

Workspace Access Modes

Workspace Configuration

BotConfig Workspace Fields

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

Related