agentsphere-mcp-server

Upload local files or folders to a specified directory in the sandbox. Can upload single files or entire folders, maintaining the original directory structure during upload. Tip: If you know the file name but are unsure of the complete path, you can first use the find_file_path tool to determine the absolute path of the file. Args: local_path: Absolute path of local file or folder target_path: Target directory path in sandbox, defaults to /user_uploaded_files/ (ending with / indicates directory) sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Upload result containing list of successfully uploaded files or error information

Write content to a file in a sandbox. This tool writes content to a file in a sandbox. If sandbox_id is not provided, it will use the default managed sandbox. Otherwise, it will connect to the specified sandbox. Writing to a file that doesn't exist creates the file. Writing to a file that already exists overwrites the file. Writing to a file at path that doesn't exist creates the necessary directories. Args: path: Path to the file in the sandbox (e.g., "/home/user/test.txt") content: Content to write to the file sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Dictionary containing: - success: "true" or "false" - path: Path of the written file - name: Name of the file - type: Type of the entry ("file") - message: Success or error message Example: # Write a file to the default managed sandbox sandbox_file_write(path="/home/user/config.json", content='{"key": "value"}') # Write a file to a specific sandbox sandbox_file_write(path="/home/user/config.json", content='{"key": "value"}', sandbox_id="sbx_abc123")

Get the URL for web services running in the sandbox. Note: You need to first create and start web services (like Next.js, Streamlit, etc.) using exec_command. Make sure the web service port is not occupied. Due to sandbox network security policies, all web services cannot be accessed directly via IP + port number. You need to call this method to get the externally accessible URL. Args: port: Port number sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: URL link

Read file content from a sandbox. This tool reads the content of a file from a sandbox. If sandbox_id is not provided, it will use the default managed sandbox. Otherwise, it will connect to the specified sandbox. Args: path: Path to the file in the sandbox (e.g., "/home/user/test.txt") sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: File content as string. Returns empty string if file doesn't exist or error occurs. Example: # Read a file from the default managed sandbox content = file_read(path="/home/user/config.json") # Read a file from a specific sandbox content = file_read(path="/home/user/config.json", sandbox_id="sbx_abc123")

Check if a file or directory exists in a sandbox. This tool checks whether a file or directory exists at the specified path. If sandbox_id is not provided, it will use the default managed sandbox. Otherwise, it will connect to the specified sandbox. Args: path: Path to check (e.g., "/home/user/config.json" or "/home/user/projects") sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Boolean: True if the path exists (file or directory), False otherwise Example: # Check if path exists in the default managed sandbox exists = sandbox_dir_exist(path="/home/user/config.json") # Check if path exists in a specific sandbox exists = sandbox_dir_exist(path="/home/user/projects", sandbox_id="sbx_abc123")

跨平台启动终端并执行 agentsphere CLI 命令 这个工具启动终端应用并执行 uv run 脚本。 - macOS: 使用 iTerm2（如可用）或 Terminal - Windows: 使用 PowerShell 或 cmd.exe - Linux: 使用 GNOME Terminal、KDE Konsole 等 脚本会连接到指定的 sandbox，并通过 TCP 连接到服务器。 Args: sandbox_id: 可选。sandbox_id 参数。如果不提供，命令将不包含 sandbox_id。 Returns: Dictionary containing: - success: "true" or "false" - message: Success or error message - platform: 检测到的操作系统平台 - process_id: 启动的进程ID - command: 执行的完整命令 - sandbox_id: 传入的 sandbox_id（如有） Example: # 启动终端并执行脚本（不带 sandbox_id） pty_create() # 启动终端并执行脚本，带有 sandbox_id pty_create(sandbox_id="sbx_abc123")

Execute Linux system commands in the sandbox Note: - If the executed command occupies the command line window (like starting a web service), the function will wait indefinitely - For services that need to run continuously, it's recommended to use nohup background startup: * Next.js example: "nohup npm run dev > nextjs.log 2>&1 &" - Command execution timeout is 60 seconds Args: cmd: Command to execute sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Command execution result containing stdout, stderr and success fields

Check if a sandbox is running. This tool checks if a specific sandbox is currently in running state by calling Sandbox.list() and checking its state field. Args: sandbox_id: The unique identifier of the sandbox to check Returns: Boolean: True if sandbox is running, False otherwise Example: # Check if a sandbox is running is_running = sandbox_is_running(sandbox_id="sbx_abc123")

List entries in a directory (similar to ls -al). This tool lists all files and directories in the specified path. If sandbox_id is not provided, it will use the default managed sandbox. Otherwise, it will connect to the specified sandbox. Args: path: Path to the directory to list (e.g., "/home/user/projects") sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Dictionary containing: - success: "true" or "false" - path: Path of the listed directory - entries: List of entries, each with: - name: Name of the entry - type: Type of the entry ("file" or "dir") - path: Full path to the entry - total_count: Total number of entries - files_count: Number of files - dirs_count: Number of directories - message: Success or error message Example: # List directory in the default managed sandbox sandbox_list_dir(path="/home/user")

关闭 PTY 连接并清理客户端 这个工具向指定的 sandbox 客户端发送 PTY_CLOSE 消息，通知其： 1. 调用 pty.send_input("exit\n") 优雅地关闭 PTY 2. 退出主程序 3. 本工具随后清理对应的 TCP 连接 工作流程: 1. 发送 PTY_CLOSE TLV 消息给目标客户端 2. 等待客户端自行退出（关闭连接） 3. 清理 PTY 管理器中的连接记录 Args: sandbox_id: 必需。要关闭的 sandbox_id Returns: Dictionary containing: - success: "true" or "false" - message: Success or error message - sandbox_id: 处理的 sandbox_id - timestamp: 操作时间戳 Example: # 关闭指定 sandbox 的 PTY 连接 pty_close(sandbox_id="sbx_abc123")

获取沙箱 PTY 的最新输出 这个工具从指定的沙箱客户端获取最近的 PTY 输出内容。 如果没有提供 sandbox_id，将使用 sandbox_manager 中管理的默认沙箱。 工作流程: 1. 如果 sandbox_id 为 None，使用 sandbox_manager.get_sandbox() 获取默认沙箱 2. 从沙箱对象获取 sandbox_id 3. 检查 PTY 管理器中是否存在该 sandbox 的 PTY 连接 4. 使用 pty_manager.get_recent_output_from_client() 获取最新输出 5. 返回输出结果 Args: sandbox_id: 可选。目标 sandbox_id。如果不提供，使用默认管理沙箱。 timeout: 可选。等待输出响应的超时时间（秒），默认为 2.0 秒。 Returns: Dictionary containing: - success: "true" or "false" - message: Success or error message - sandbox_id: 实际使用的 sandbox_id - output: 获取到的 PTY 输出内容（如果成功） - timestamp: 获取时的时间戳 - has_output: 是否获取到输出内容 - error: 错误信息（如果失败） Example: # 使用默认沙箱获取输出 pty_get_latest_output() # 指定 sandbox_id 并设置超时时间 pty_get_latest_output(sandbox_id="sbx_abc123", timeout=5.0)

Create a new sandbox instance. This tool creates a brand new sandbox without reusing existing ones. Each call will create a completely new sandbox instance. Args: template: Sandbox template name or ID, defaults to "agentsphere-code-interpreter-v1" timeout: Timeout for the sandbox in seconds, defaults to 43200 (12 hours). Maximum is 24 hours (86400s) for Pro users and 1 hour (3600s) for Hobby users. metadata: Custom metadata for the sandbox (optional) envs: Custom environment variables for the sandbox (optional) Returns: Dictionary containing: - success: "true" or "false" - sandbox_id: Unique identifier of the new sandbox - template: Template used for the sandbox - envd_version: Version of envd running in the sandbox - message: Success or error message Example: # Create a sandbox with default settings sandbox_create() # Create a sandbox with custom template and timeout sandbox_create(template="custom-template", timeout=7200) # Create a sandbox with environment variables sandbox_create(envs={"PYTHON_VERSION": "3.11", "NODE_VERSION": "18"})

Create a new directory in a sandbox (similar to mkdir -p). This tool creates a directory and all parent directories along the way if needed. If sandbox_id is not provided, it will use the default managed sandbox. Otherwise, it will connect to the specified sandbox. Args: path: Path to the directory to create (e.g., "/home/user/my/nested/dir") sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Dictionary containing: - success: "true" or "false" - path: Path of the created directory - created: "true" if directory was created, "false" if it already existed - message: Success or error message Example: # Create directory in the default managed sandbox sandbox_mkdir(path="/home/user/projects/new_project") # Create directory in a specific sandbox sandbox_mkdir(path="/home/user/data/output", sandbox_id="sbx_abc123")

向 PTY 沙箱发送输入命令 这个工具向已注册的沙箱 PTY 客户端发送命令。 如果没有提供 sandbox_id，将使用 sandbox_manager 中管理的默认沙箱。 工作流程: 1. 如果 sandbox_id 为 None，使用 sandbox_manager.get_sandbox() 获取默认沙箱 2. 从沙箱对象获取 sandbox_id 3. 检查 PTY 管理器中是否存在该 sandbox 的 PTY 连接 4. 如果不存在，提示需要先使用 pty_create 创建 PTY 连接 5. 使用 pty_manager.send_command_to_client() 发送命令 Args: input: 要发送到沙箱的输入命令内容 sandbox_id: 可选。目标 sandbox_id。如果不提供，使用默认管理沙箱。 Returns: Dictionary containing: - success: "true" or "false" - message: Success or error message - sandbox_id: 实际使用的 sandbox_id - input: 发送的命令内容 - timestamp: 发送时的时间戳 Example: # 使用默认沙箱发送命令 pty_send_input(input="echo hello") # 指定 sandbox_id 发送命令 pty_send_input(input="ls -al", sandbox_id="sbx_abc123")

Dynamically adjust the sandbox lifetime/expiration timeout. This tool sets a new timeout for a sandbox, which determines how long the sandbox will remain alive after the API call. The sandbox will expire exactly `timeout` seconds from the current time. Note: Calling this method multiple times overwrites the TTL (time-to-live). Each call uses the current timestamp as the starting point to measure the timeout duration. Args: timeout: Timeout duration in seconds. The sandbox will expire after this many seconds from now. Examples: 300 (5 minutes), 3600 (1 hour), 86400 (24 hours) sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Dictionary containing: - success: "true" or "false" - sandbox_id: The sandbox_id that was updated - timeout: The timeout value set (in seconds) - message: Success or error message - timestamp: The time when the timeout was set Example: # Set timeout to 10 minutes (600 seconds) for the default sandbox sandbox_settimeout(timeout=600) # Set timeout to 1 hour (3600 seconds) for a specific sandbox sandbox_settimeout(timeout=3600, sandbox_id="sbx_abc123") # Extend timeout to 24 hours sandbox_settimeout(timeout=86400)

Search for absolute paths of files or directories by name This tool can search for and return complete absolute paths based on names. The returned paths can be directly used for the upload_files_to_sandbox tool. Use cases: - When you know the file name but are unsure of the complete path - When you need to upload files to sandbox but don't remember the file location - When batch searching for certain types of files Args: filename: File name to search for (supports wildcards) Examples: "test.py", "*.txt", "project*", "*.json" search_path: Search starting path or shortcut options (optional) Specific paths, such as: - macOS: "/Users/username/Desktop/Projects" - Windows: "C:\Users\username\Documents\Work" - Linux: "/home/username/workspace" Shortcut options: - "desktop": Search desktop directory (default option) - "documents": Search documents directory - "downloads": Search downloads directory - "home": Search user home directory (high success rate but very slow search, recommend trying desktop/documents etc. smaller scope options first, use this option if not found) Tip: If unsure about file location or user's operating system, recommend using shortcut options or leave this parameter empty to use default value. The system will default to searching the user's desktop Returns: Search results containing list of found files/directories, each result includes complete path, type, size, modification time, etc. Examples: # Search for specific file name find_file_path("config.json") # Search for files of specified format find_file_path("*.py") # Search for all files starting with "project" (like project.json, project_config.py, project1.txt etc.) find_file_path("project*") # Search in specific directory find_file_path("*.txt", "/Users/username/Documents")

Get sandbox logs starting from a specified position. This tool retrieves logs from a sandbox, with support for pagination via start position and limit. Logs contain both the log line content and timestamp of when the entry was created. Args: limit: Maximum number of log entries to return. Defaults to 1000. Valid range: 1-5000. The API may return fewer entries if not enough logs exist. sandbox_id: Optional. The unique identifier of the sandbox. If None, uses the default managed sandbox. Returns: Dictionary containing: - success: "true" or "false" - sandbox_id: The sandbox_id from which logs were retrieved - logs: List of log entries, each containing: - line: The log line content - timestamp: ISO format timestamp of the log entry - total_logs: Total number of logs retrieved - limit: The limit used - message: Success or error message - has_more: Boolean indicating if there are more logs available Example: # Get first 100 logs from default sandbox sandbox_get_logs(start=0, limit=100) # Get logs starting from position 500 for a specific sandbox sandbox_get_logs(start=500, limit=1000, sandbox_id="sbx_abc123") # Pagination example logs_batch1 = sandbox_get_logs(start=0, limit=1000) if logs_batch1["has_more"]: logs_batch2 = sandbox_get_logs(start=1000, limit=1000)