Add guide: app-server + custom agent integration

[enyst]

This PR adds a new guide that explains how to:

1. Run the OpenHands V1 app-server while spawning a local agent-server process from software-agent-sdk (no Docker, no remote runtime)
2. Build a custom agent using the SDK and integrate it with the app-server running locally

The guide is grounded in source code with inline links to the relevant modules and functions.
Key references include:

• app-server V1 routing and enablement
• process-based sandbox that launches python -m openhands.agent_server
• AsyncRemoteWorkspace used by the app-server to talk to the agent-server
• agent-server health endpoints and bootstrap
• building Agent for StartConversationRequest in the V1 service

Co-authored-by: openhands openhands@all-hands.dev

@enyst can click here to continue refining the PR

[mamoodi]

I really don't know how to review this. Can you add someone that you think would be better to review this please?

[enyst]

@OpenHands This is a markdown doc!

• add it to the json so we can see it on the left side when mintlify deploys
• review and fix formatting with some styles, headings, section bold, that stuff so that it is more readable. Like other docs nearby are.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Summary of changes pushed to branch docs/v1-local-agent-server-guide (updates PR #194)

What I changed

• Navigation: Added the new page to Mintlify sidebar
  • docs.json: Added openhands/usage/developers/v1-local-agent-server under Web → Developers so it appears in the left nav when deployed.
• Formatting: Polished the guide for readability and consistency
  • openhands/usage/developers/v1-local-agent-server.mdx:
    • Title Case headings and clear H2/H3 structure
    • Added a top Note for quick context
    • Applied inline code styling for env vars, paths, and endpoints
    • Added descriptive labels to code blocks (e.g., “Build”, “Full App (Backend + Frontend)”, “Separate Servers”, “Skill: security_expert.md”)
    • Emphasized key sections (“Example: Add a User Skill”, “Advanced: Add a New Agent Type to OpenHands”)
    • Kept authoritative GitHub links and absolute internal links

Checklist against request

• Add it to the json so we can see it on the left side when mintlify deploys: Done
• Review and fix formatting with styles, headings, section bold: Done (aligned with DOC_STYLE_GUIDE and nearby docs)

Conciseness

• Only two files changed, focused strictly on the requested updates:
  • docs/docs.json
  • openhands/usage/developers/v1-local-agent-server.mdx

Commit

• Message: docs: add developers guide to docs.json nav and polish formatting for readability
• Includes: Co-authored-by: openhands openhands@all-hands.dev
• Pushed to: docs/v1-local-agent-server-guide

Notes

• Mintlify’s CI “Check Broken Links” will validate link integrity on the PR. If anything fails, I can follow up with fixes immediately.

_{View full conversation}

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Check Broken Links

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #194 at branch `docs/v1-local-agent-server-guide`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[enyst]

@OpenHands read this PR. It's actually attempting to talk about 2 different things. Separate them:

• running fully local with Web GUI
• customizing an agent in the SDK and loading it in GUI

Split them. Look around and decide if any of them is redundant, then drop it. If both are useful, figure out where they fit, maybe the second belongs in the SDK, and fix the json for them. When you are done, push and wait for CI, see if it's green. We have the habit to break mintlify :P

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev