From 66c65c61674c3c84751ece19bf2a33cac0affd98 Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Tue, 3 Mar 2026 14:53:13 -0300 Subject: [PATCH] Update documentation and add agent workspaces guide --- README.md | 2 +- src/10-rest/storage-api.md | 10 ++--- src/11-features/platform-comparison.md | 2 +- src/13-community/documentation.md | 2 +- src/13-community/ide-extensions.md | 2 +- src/17-autonomous-tasks/agent-workspaces.md | 37 +++++++++++++++++++ .../hosting-dns.md | 4 +- src/SUMMARY.md | 1 + src/introduction.md | 2 +- 9 files changed, 50 insertions(+), 12 deletions(-) create mode 100644 src/17-autonomous-tasks/agent-workspaces.md diff --git a/README.md b/README.md index 0a5d4bc7..e76855a6 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ On first run, botserver automatically: - Installs required components (PostgreSQL, S3 storage, Cache, LLM) - Sets up database with migrations - Downloads AI models -- Starts HTTP server at `http://127.0.0.1:9000` +- Starts HTTP server at `http://127.0.0.1:8080` ### Run the Desktop App diff --git a/src/10-rest/storage-api.md b/src/10-rest/storage-api.md index 5910a531..af059212 100644 --- a/src/10-rest/storage-api.md +++ b/src/10-rest/storage-api.md @@ -14,7 +14,7 @@ The Storage API allows you to: ## Base URL ``` -http://localhost:9000/api/v1/storage +http://localhost:8080/api/v1/storage ``` ## Authentication @@ -190,7 +190,7 @@ Generate a presigned URL for temporary access. **Response:** ```json { - "url": "http://localhost:9000/mybot.gbai/file.pdf?X-Amz-Algorithm=...", + "url": "http://localhost:8080/mybot.gbai/file.pdf?X-Amz-Algorithm=...", "expires_at": "2024-01-15T11:30:00Z" } ``` @@ -268,7 +268,7 @@ curl -X PUT \ -H "Authorization: Bearer token123" \ -H "Content-Type: application/pdf" \ --data-binary @document.pdf \ - http://localhost:9000/api/v1/storage/buckets/mybot.gbai/objects/docs/manual.pdf + http://localhost:8080/api/v1/storage/buckets/mybot.gbai/objects/docs/manual.pdf ``` ### Download File @@ -276,7 +276,7 @@ curl -X PUT \ ```bash curl -X GET \ -H "Authorization: Bearer token123" \ - http://localhost:9000/api/v1/storage/buckets/mybot.gbai/objects/docs/manual.pdf \ + http://localhost:8080/api/v1/storage/buckets/mybot.gbai/objects/docs/manual.pdf \ -o downloaded.pdf ``` @@ -285,7 +285,7 @@ curl -X GET \ ```bash curl -X GET \ -H "Authorization: Bearer token123" \ - "http://localhost:9000/api/v1/storage/buckets/mybot.gbai/objects?prefix=docs/" + "http://localhost:8080/api/v1/storage/buckets/mybot.gbai/objects?prefix=docs/" ``` ## Storage Organization diff --git a/src/11-features/platform-comparison.md b/src/11-features/platform-comparison.md index 8afa8505..ebc30ede 100644 --- a/src/11-features/platform-comparison.md +++ b/src/11-features/platform-comparison.md @@ -159,7 +159,7 @@ Run General Bots on your own infrastructure with single binary deployment, conta ./botserver ``` -Access at `http://localhost:9000` and start building. +Access at `http://localhost:8080` and start building. ## Summary diff --git a/src/13-community/documentation.md b/src/13-community/documentation.md index 4c891469..0a8b83fd 100644 --- a/src/13-community/documentation.md +++ b/src/13-community/documentation.md @@ -123,7 +123,7 @@ Document WebSocket protocols with connection details, message formats for both d ### Connection ``` -ws://localhost:9000/ws +ws://localhost:8080/ws ``` ### Message Format diff --git a/src/13-community/ide-extensions.md b/src/13-community/ide-extensions.md index ad4d810b..dd57c1e3 100644 --- a/src/13-community/ide-extensions.md +++ b/src/13-community/ide-extensions.md @@ -67,7 +67,7 @@ return { 'botserver/nvim-botserver', config = function() require('botserver').setup({ - server_url = 'http://localhost:9000', + server_url = 'http://localhost:8080', default_bot = 'edu' }) end diff --git a/src/17-autonomous-tasks/agent-workspaces.md b/src/17-autonomous-tasks/agent-workspaces.md new file mode 100644 index 00000000..16e360b3 --- /dev/null +++ b/src/17-autonomous-tasks/agent-workspaces.md @@ -0,0 +1,37 @@ +# Agent Workspaces + +General Bots supports an advanced "Agent Mode" UI where the interaction with an AI agent shifts from a simple chat interface to a fully realized multi-panel workspace. This design empowers users to monitor complex autonomous tasks in real-time, providing deep visibility into what the AI is doing. + +## Architectural Overview + +When an application logic branch triggers a computationally heavy or open-ended action (like `APP_CREATE` or deep research), the backend kicks off an **Agent Executor** process. This executor brings up a dedicated, highly isolated LXC container for that specific session. + +The Agent Executor communicates back to the frontend in real-time. This provides a transparent view of: + +1. **Thought Processes**: High-level textual reasoning of the agent. +2. **Terminal Output**: Verbatim standard output and standard error from the LXC container. +3. **Browser Output**: Visual previews of web applications being built or research being conducted, served via localhost proxies from within the container. + +## The Agent UI + +The main interface pivots from a standard 1-panel conversation to a complex multi-panel grid when "Agent Mode" is toggled from the Chat interface. + +This layout includes: + +- **Left Sidebar**: A collapsible "Agents & Workspaces" sidebar that summarizes the current state of active agents, their resource usage (quota), and provides drag-and-drop workspace organization. +- **Center Chat**: A persistent interactive chat with the specific agent, allowing for ongoing refinement of the task. +- **Right Hand Split Screens**: + - **Top Right**: An active Browser Window. The agent can stream HTML rendering updates or host internal applications (`localhost`) from its LXC sandbox, exposing them visually to the user. + - **Bottom Right**: A live Terminal feed streaming `stdout` and `stderr` directly from the bash environment of the underlying LXC container. + +## LXC Sandbox execution + +To prevent dependency collisions, protect the host operating system, and offer clean slate environments for arbitrary execution, every agent session spins up a temporary **Ubuntu 22.04 LXC container**. + +1. When the agent intent classifier matches a heavy task (e.g. `APP_CREATE`), the backend initiates the `ContainerSession` struct. +2. An `lxc launch` command instantiates a fast, lightweight container instance. +3. A bash shell is opened inside this container, and its I/O streams are piped back to the `TaskProgressEvent` broadcast channel using Tokio. +4. The user sees the bash output instantly in the bottom-right terminal panel. +5. On completion or failure, the container is forcibly stopped and deleted (`lxc delete --force`). + +This isolated environment gives agents the absolute freedom to execute package installations (like `npm install`), launch development servers, and write arbitrary code, entirely segregated from the primary `BotServer`. diff --git a/src/18-appendix-external-services/hosting-dns.md b/src/18-appendix-external-services/hosting-dns.md index f64b26d6..735874b1 100644 --- a/src/18-appendix-external-services/hosting-dns.md +++ b/src/18-appendix-external-services/hosting-dns.md @@ -100,7 +100,7 @@ lxc config set botserver limits.memory 4GB lxc config set botserver limits.cpu 2 # Forward ports -lxc config device add botserver http proxy listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:9000 +lxc config device add botserver http proxy listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:8080 lxc config device add botserver https proxy listen=tcp:0.0.0.0:443 connect=tcp:127.0.0.1:8443 # Set environment for Vault @@ -118,7 +118,7 @@ services: botserver: image: generalbots/botserver:latest ports: - - "8080:9000" + - "8080:8080" environment: - VAULT_ADDR=http://vault:8200 volumes: diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ba2db8b3..daf0fb31 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -410,6 +410,7 @@ - [Data Model](./17-autonomous-tasks/data-model.md) - [Examples](./17-autonomous-tasks/examples.md) - [Designer](./17-autonomous-tasks/designer.md) + - [Agent Workspaces](./17-autonomous-tasks/agent-workspaces.md) # Part XVII - Scale diff --git a/src/introduction.md b/src/introduction.md index eb883a92..2e9688de 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -250,7 +250,7 @@ chmod +x botserver ### 2. Open Browser ``` -http://localhost:9000 +http://localhost:8080 ``` ### 3. Start Chatting