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

​
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.bots 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:
MechanismPurposeImplementation
Path ResolutionResolve paths against workspace rootworkspace.resolve(path)
Containment CheckVerify paths stay within boundariesworkspace.contains(path)
Access ControlEnforce read/write permissionsAccess mode validation

​
Configuration Options

​
Workspace Access Modes

​
Workspace Configuration

OptionTypeDefaultDescription
rootPathrequiredAbsolute 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_keyOptional[str]NoneSession identifier for scope resolution

​
BotConfig Workspace Fields

OptionTypeDefaultDescription
workspace_dirOptional[str]None → ~/.praisonai/workspaces/<scope>/<session_key>Override workspace path
workspace_accessstr"rw"Access mode
workspace_scopestr"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

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.
Workspaces reject filesystem root access, resolve symlinks to prevent macOS issues, and validate all path operations. Never bypass workspace containment in production deployments.
The default workspace structure is ~/.praisonai/workspaces/<scope>/<session_key>/. This ensures clean separation and predictable file organization across different deployment scenarios.
File tools fall back to os.getcwd() when no workspace is configured, maintaining compatibility with existing code. Bots automatically apply workspace containment for security.

Bot Default Tools

Auto-injected tools that work with workspaces

Self-Improving Skills

How skills interact with workspace containment