Frontend architecture 🧵

Generally I like this simplification, there are just going to be some "whatabouts"... like what about the cases that manage many agent-server instances, not just one? Is that what you mean by enterprise, it's the multi-user case?

I would like to ship a Conversations Frontend which only uses an agent-server as the backend

nod thinky spin I knew you were looking at that, and honestly I long felt the code design was heading in that direction. Please let me make sure I understand correctly how it would work:

deprecate the entire OpenHands Web python backend

I'm hearing that • OH-Web would have an Open Source app-server • we will not have / distribute / recommend a Web UI for it • enterprise is, or should be, built on this app-server, basically extending it with enterprise / org / multiuser functionality • and it has a Cloud Web UI And • OH (SDK) is an SDK by definition -ish • it has 2 interfaces to the world, Python API and REST/WS API (agent-server) • the CLI is an app built on it, uses Python API exclusively at the moment (*Xingyao proposed to switch) • the Conversations FE would be a FE (Web-like?) using agent-server API... • I feel like some client side is missing in this picture? (probably it's just me, but idk, at least settings persistence, it's not usable without) Did that make sense? What am I missing?

I completely agree that simplifying the architecture is a worthwhile goal. However, after thoroughly reviewing both codebases, I believe the scope of the changes may be more extensive than initially anticipated. Below are some observations specific to the OSS codebase that I feel warrant further discussion: Architectural Mismatch Currently, the agent-server runs within each Docker sandbox, with one instance dedicated per conversation. In contrast, the app_server operates outside all sandboxes, acting as the orchestrator. The proposal seems to treat these two components as interchangeable, but they each play distinct roles: • Agent-server: Acts as a per-conversation runtime, handling tools, events, bash commands, file operations, skills, and MCP. • App_server: Functions as a cross-conversation orchestrator, managing the sandbox lifecycle, conversation registry, and settings. Identified Gaps 1. Sandbox Lifecycle Management The agent-server is not responsible for creating, pausing, resuming, or destroying its own sandbox; it operates within one. In the OSS app_server, this functionality is managed through concrete implementations: • DockerSandboxService: Manages the full Docker container lifecycle. • ProcessSandboxService: Handles process-based local execution. • RemoteSandboxService: Oversees remote sandbox orchestration. These components are responsible for managing container creation, port exposure, health checks, status tracking, and cleanup. It is important to decide where this responsibility should reside going forward. Question: Will sandbox orchestration now be handled by the agent-server, potentially altering its role, or are we assuming the introduction of a new service to handle this? 2. Conversation List Across Sandboxes Each agent-server instance is aware only of the conversations within its own sandbox. The app_server, on the other hand, maintains a central index (via the

LiveStatusAppConversationService

and

SQLAppConversationInfoService

) that tracks all conversations along with their associated metadata—such as title, status, selected repo/branch, token usage, and cost metrics. This enables listing, searching, and paginating across all conversations. Question: How do we envision conversation listing functioning when conversations are distributed across isolated sandboxes? 3. Settings Persistence The proposal mentions "LLM profiles" as a feature managed by the agent-server; however, the agent-server does not currently handle this. It only provides read-only LLM endpoints, listing available providers/models from LiteLLM. There is no persistent settings storage, and LLM configuration is passed on a per-conversation basis via the

StartConversationRequest

. The OSS app_server includes a

FileSettingsStore

that persists settings to a

settings.json

file, which includes: • LLM API key, model, base URL • MCP server configuration • Git user configuration (name/email) • User preferences (language, max iterations, confirmation mode) Question: Are we considering adding a settings router to the agent-server to handle persistent settings storage? 4. GitHub Repository Listing This gap was acknowledged in the proposal. In the OSS codebase, the

ProviderHandler

component facilitates integration with GitHub, GitLab, Bitbucket, and Azure DevOps. Question: What is the minimum viable scope for this feature—should we focus on GitHub integration initially, or are we aiming for multi-provider support from the start? 5. Pending Message Queue In the OSS app_server, the SQLPendingMessageService queues messages that are sent during the initialization phase of a conversation (e.g., while the sandbox is starting or the repository is being cloned), ensuring they are delivered once the system is ready. --- Clarifying Questions: 1. Deployment Model: Will this solution be strictly local/single-user (with no Docker sandboxes, and the agent-server running directly on the host), or should it support sandboxed execution as well? 2. Goal Clarity: Is the primary objective to eliminate the app_server entirely, or to simplify the overall architecture? If simplification is the goal, we could consider a thinner app_server that delegates more tasks to the agent-server, which might reduce complexity with fewer risks. Recommendation • If the scope is limited to local/single-user use without Docker sandboxes (with the agent-server running directly on the host), the gaps become more manageable, focusing primarily on settings persistence and GitHub repository listing—both of which are achievable. • If Docker sandboxes are to remain in use, the challenge of rebuilding sandbox orchestration and a conversation registry is significant, as much of this functionality is already handled by the app_server. Thank you very much! thankyou

Very good points - this Conversations FE would work on a single agent-server. 🤔 Just to note here • technically agent-server supports multiple conversations 🤔 • but being local, with no worktree handling... it's very limited. Re: @millions-afternoon-47582 question 3: • I believe we already have a PR adding settings to agent-server interface • we will expose LLM profiles too.

I also want to underscore Hiep's "goal clarity" point. I think that's where this should all start. The benefits I picture are around removing coupling that makes OSS and enterprise web brittle and difficult to contribute to, but I'm having to fill in the blanks to guess that's the motivation.

Two major goals from me here: • Enterprise web server and OSS web server interactions are a huge pain • "Local GUI" is a pain to set up and support To address the first point: we make agent-server the backend for "Local GUI" mode. The Enterprise web server just becomes its own project, with no OSS dependencies To address the second point: In Local GUI mode, instead of having a backend that manages container lifecycles, now the end user is expected to start an agent-server (sandboxed or not), and then start a frontend that points to that agent-server. I have been doing this as my primary workflow for ~2 months and it works great.

Hello @wooden-umbrella-84098, My apologies for the delayed response, and thank you for your patience. From my perspective, the front end should be able to support this direction. That said, it would require us to adjust how the local GUI creates and manages conversations. Would it be helpful to gather feedback from the community—perhaps through a short survey—before moving forward with this approach? I’ll also loop in @straight-sundown-84319, as he has deeper familiarity with the agent server and may have additional insights or considerations to share. Thank you very much! thankyou

I think the proposed Conversations FE should not be in the same repository, it could have its own, right?

nod yeah I think it'd go into its own repo

Sorry for nitpicking, I'm not sure the first step is v0 cleanup. Maybe if the prerequisite is so obvious that we don't even count it as a step: finalizing the repos layout. 😅 https://github.com/OpenHands/OpenHands-Web 1. We now made the OpenHands-Web repo simply a git remote, and the staging validation run for issues/PRs forwarding looks good. 2. I remade a merge of the SDK with the legacy history and it went smoothly. I think I can extract a simple prompt for when we flip the switch. 3. I understand we may need to build a release from OpenHands-Web, to validate?

Hey all, Engel asked me to share my 2 cents here 🙂 In general, I agree with the pain points Robert shared: 1. Enterprise web server and OSS web server interactions are a huge pain 2. "Local GUI" is a pain to set up and support re: #1 - Enterprise web server and OSS web server interactions are a huge pain Personally, I don't contribute much code to OpenHands, but my understanding is there's a lot of logic to manage differences between Local OSS and Enterprise. I don't have strong opinions or much else to add on the target architecture here, but it seems like we want a way to 1) continue supporting OSS contributions against the Local OSS Web Server, and 2) simplify development of Enterprise web server. re: #2 - Local GUI is a pain to setup I hear OSS users like the fact that OpenHands can run the agent in sandboxes like Docker containers, however I think our current Docker setup is not flexible enough for the community / creates friction with first time users. For example, some users want DinD setups, others aren't finding success with initial Docker installs, etc. I think Robert's recommendation here makes sense, potentially to help with the first-time user experience of OpenHands: > now the end user is expected to start an agent-server (sandboxed or not), and then start a frontend that points to that agent-server. We could then provide various reference implementations/documentation on how to use OpenHands with sandboxes like Docker etc.