docs: add custom Agent Server image guide for Docker backend#541
Merged
rbren merged 4 commits intoJun 2, 2026
Conversation
Replace the placeholder Docker backend page with a full walkthrough: build a custom Agent Server image (FROM ghcr.io/openhands/agent-server, add JDK + utilities), run it locally with a SESSION_API_KEY, and register it as a backend in Agent Canvas. Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
jpelletier1
added a commit
that referenced
this pull request
Jun 3, 2026
* docs: add Onboarding Agent Canvas section with agent-canvas docs - Rename 'Onboarding OpenHands' group to 'Onboarding Agent Canvas' - Add agent-canvas docs (overview, setup, backends, llm-profiles, customize-and-settings, automations, self-hosting, development, troubleshooting) under Onboarding Agent Canvas - Move Hooks to Product Guides section - Update Quick Start to single 'Install OpenHands Agent Canvas' card with OpenHands Cloud as a bullet item Co-authored-by: openhands <openhands@all-hands.dev> * docs: refine Quick Start card and move Repository Customization - Remove bullet points from Agent Canvas card in Quick Start - Add OpenHands Cloud as a single bullet below the card - Move Repository Customization to Product Guides, after Automations Co-authored-by: openhands <openhands@all-hands.dev> * docs: refine Onboarding Agent Canvas nav and content - Rename 'Setup' page title to 'Install' - Add 'Setup a Pre-built Automation' group with placeholder sub-pages: GitHub PR Review Assistant, GitHub Repository Monitor, Slack Channel Monitor - Remove LLM Profiles and Model Configuration from nav - Add links to Skills and MCP Servers under Customize header in customize-and-settings - Remove stale llm-profiles link from Related Guides Co-authored-by: openhands <openhands@all-hands.dev> * docs: add backend setup sub-pages under Connect and Manage Backends - Convert flat backends entry to a nav group - Add placeholder sub-pages: Local, VM, Docker, OpenHands Cloud Co-authored-by: openhands <openhands@all-hands.dev> * docs: merge automations into prebuilt-automations; add pre-built overview - Move automations.mdx content into prebuilt-automations.mdx - Add intro section at top of prebuilt-automations linking to the three pre-built automation sub-pages (PR review, repo monitor, Slack) - Delete automations.mdx - Remove automations from Onboarding Agent Canvas nav Co-authored-by: openhands <openhands@all-hands.dev> * docs: add First Time Setup page to Onboarding Agent Canvas Co-authored-by: openhands <openhands@all-hands.dev> * Update links to pre-built automations and fill in missing guides * Add first-time setup wizard docs for Agent Canvas Covers all four onboarding steps with screenshots: - Step 1: Choose your agent (OpenHands, Claude Code, Codex, Gemini CLI via ACP) - Step 2: Check your backend (local default, link to backends guide) - Step 3: Set up your LLM (BYOK + OpenHands Cloud link) - Step 4: Start from a proven workflow (GitHub PR Review Copilot + pre-built automations) Co-authored-by: openhands <openhands@all-hands.dev> * add images * Updates to setup and backends * docs: add custom Agent Server image guide for Docker backend (#541) * docs: add custom Agent Server image guide for Docker backend Replace the placeholder Docker backend page with a full walkthrough: build a custom Agent Server image (FROM ghcr.io/openhands/agent-server, add JDK + utilities), run it locally with a SESSION_API_KEY, and register it as a backend in Agent Canvas. Co-authored-by: openhands <openhands@all-hands.dev> * docs: use agent-server-java name, port 8001, add multi-backend section Co-authored-by: openhands <openhands@all-hands.dev> * docs: pin agent server version in FROM example Co-authored-by: openhands <openhands@all-hands.dev> * docs: use 1-python base tag with short pinning tip Co-authored-by: openhands <openhands@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev> * docs: update self-hosting and setup pages for --public mode - self-hosting.mdx: replace clone/npm-run-dev workflow with npx @openhands/agent-canvas --public one-liner. Remove nginx basic auth as the auth layer (--public handles it at the app level). Simplify security checklist and reverse proxy guidance. - setup.mdx: add --public flag to CLI table, add LOCAL_BACKEND_API_KEY to environment variables table. Co-authored-by: openhands <openhands@all-hands.dev> * docs: use agent-canvas CLI command in self-hosting guide Assumes the user has already installed via npm. Links to the install page for prerequisites. Co-authored-by: openhands <openhands@all-hands.dev> * docs: reframe "What Agent Canvas Includes" as "Why Agent Canvas" Replace the technical component list with four user-facing value props: agent flexibility, LLM flexibility, built-in automations, deployment flexibility. Co-authored-by: openhands <openhands@all-hands.dev> * docs: rework Key Concepts in Agent Canvas overview Replace six rows (UI, three backend flavors, Customize, Settings) with four focused concepts: Agent Canvas (UI + BE defined), Backend (any UI connects to any BE), Conversation, and Automation. Co-authored-by: openhands <openhands@all-hands.dev> * docs: rename Setup link to Install in overview for consistency The target page title is already "Install". Co-authored-by: openhands <openhands@all-hands.dev> * docs: rework product descriptions in Agent Canvas overview Co-authored-by: openhands <openhands@all-hands.dev> * docs: restructure Introduction page Reorder products: Agent Canvas first, then Cloud, Enterprise, SDK. Move CLI and Local GUI into a collapsible Legacy section. Co-authored-by: openhands <openhands@all-hands.dev> * docs: add ACP Agents page to Agent Canvas onboarding Ports the ACP_AGENTS guide from the agent-canvas repo into the docs: what ACP agents are, supported providers, authentication (subscription login vs API key), onboarding, switching agent/model, and custom servers. Adds the page to the Onboarding Agent Canvas nav after Customize & Settings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: update Install page CLI flags and env vars Add missing --version and --info flags. Remove developer-only env vars (OH_AGENT_SERVER_GIT_REF, OH_AGENT_SERVER_LOCAL_PATH) — these belong in the Development guide, not the user-facing Install page. Co-authored-by: openhands <openhands@all-hands.dev> * docs: remove redundant "Change the Port" section Already covered by the --port flag in the CLI Flags table. Co-authored-by: openhands <openhands@all-hands.dev> * docs: replace Docker placeholder with real install instructions The all-in-one Docker image (ghcr.io/openhands/agent-canvas) is now available. Document the docker run command with volume mounts for persistence and projects, and show how to provide a custom API key. Co-authored-by: openhands <openhands@all-hands.dev> * docs: trim Docker section for conciseness Co-authored-by: openhands <openhands@all-hands.dev> * docs: restructure Install page with npm/Docker tabs Present npm and Docker as two parallel install paths with their own prerequisites, matching the tab pattern used in the CLI docs. Co-authored-by: openhands <openhands@all-hands.dev> * docs: remove auto-install note for uv prerequisite Co-authored-by: openhands <openhands@all-hands.dev> * docs: move CLI flags and env vars into install tabs npm tab gets CLI flags + env vars (including --public, --version, etc.). Docker tab gets its own env vars section (PORT, LOCAL_BACKEND_API_KEY, OH_SECRET_KEY) since the Docker entrypoint uses env vars, not CLI flags. Co-authored-by: openhands <openhands@all-hands.dev> * docs: move Agent Canvas to its own top-level tab Add a new "Agent Canvas" tab in the nav bar alongside SDK, CLI, Cloud, etc. Remove the "Onboarding Agent Canvas" group from the Documentation tab. Update introduction and quickstart pages to reference the new tab: - Introduction: update link text to "Get started with Agent Canvas" - Quickstart: replace single card with 2-col CardGroup (Agent Canvas + Cloud) Co-authored-by: openhands <openhands@all-hands.dev> * docs: rename Documentation tab to Home Co-authored-by: openhands <openhands@all-hands.dev> * docs: slim down development page to a repo pointer Replace the full Contribute / Development page with a lightweight pointer that shows clone + npm run dev and links to the repo's own DEVELOPMENT.md for everything else. Avoids duplication and staleness. Co-authored-by: openhands <openhands@all-hands.dev> * docs: replace overview intro with tagline in description Drop the redundant opening paragraph. The tagline now lives in the frontmatter description field where Mintlify surfaces it. Co-authored-by: openhands <openhands@all-hands.dev> * docs: rewrite customize-and-settings framing - Clarify Customize: skills give domain knowledge, MCP servers connect to external tools/data - Clarify Settings: configure how the agent runs (LLM, secrets, etc.), not "backend-synced behavior" - Rename "Backend-Synced Behavior" to "Settings Are Per Backend" Co-authored-by: openhands <openhands@all-hands.dev> * docs: per-backend note applies to both Customize and Settings Rename section to "Configuration Is Per Backend" and clarify that skills, MCP servers, secrets, and settings are all per-backend. Co-authored-by: openhands <openhands@all-hands.dev> * docs: move Use Cases from top-level tab into Home Use Cases is content about the products, not a product/interface itself. Move it into the Home tab as a sidebar group after Essential Guidelines. No redirects needed — page file paths are unchanged so URLs stay the same. Co-authored-by: openhands <openhands@all-hands.dev> * docs: fill in backend pages and consolidate self-hosting into VM - local.mdx: auto-created backend, when to use, --public for LAN access - vm.mdx: absorb self-hosting content — full walkthrough with --public, security, nginx + Let's Encrypt, connecting remotely - cloud.mdx: connect Agent Canvas to OpenHands Cloud as a backend - Remove self-hosting.mdx, add redirect to backend-setup/vm - Update all internal links from self-hosting to backend-setup/vm Co-authored-by: openhands <openhands@all-hands.dev> * docs: separate self-hosting (full stack) from VM backend (headless) Self-hosting = deploy the full Agent Canvas stack (UI + backend) on a machine you control. Covers --public, security, nginx + TLS, and connecting from another Agent Canvas instance or --frontend-only. VM Backend = run --backend-only on a remote machine and connect from your local Agent Canvas. Focused on headless backend deployment with SSH tunnel or reverse proxy. Also adds --backend-only and --frontend-only flags to setup.mdx CLI table and documents --frontend-only in local.mdx. Co-authored-by: openhands <openhands@all-hands.dev> * docs: rewrite Docker backend — official image first, custom images secondary The primary use case is running the official ghcr.io/openhands/agent-canvas image. Custom Dockerfiles are an advanced topic, moved to a short section at the end. Co-authored-by: openhands <openhands@all-hands.dev> * docs: remove custom image section from Docker backend page Co-authored-by: openhands <openhands@all-hands.dev> * docs: update Cloud backend flow — Login with OpenHands Cloud + Enterprise Co-authored-by: openhands <openhands@all-hands.dev> * docs: rewrite local backend around --backend-only + --frontend-only Local backend page now focuses on: - Starting one or more backends with --backend-only on different ports - Connecting via --frontend-only and Manage Backends - Tip about running full stack without flags for simple setups Co-authored-by: openhands <openhands@all-hands.dev> * docs: VM backend step 4 uses --frontend-only on local machine Co-authored-by: openhands <openhands@all-hands.dev> * docs: use --frontend-only consistently when connecting to a backend Updated Docker and self-hosting pages to show agent-canvas --frontend-only as the way to start the UI before adding a backend via Manage Backends. Co-authored-by: openhands <openhands@all-hands.dev> * docs: consolidate self-hosting into VM backend page One page covers the full VM/self-hosted workflow: 1. Provision and secure the machine 2. Install prerequisites 3. Start with --backend-only --public (tip: drop --backend-only for full stack) 4. Connect from local machine with --frontend-only 5. Optional nginx + TLS for direct HTTPS access 6. Security checklist Delete self-hosting.mdx, add redirect to backend-setup/vm. Update all internal links. Co-authored-by: openhands <openhands@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: Devin <devinvinson@gmail.com> Co-authored-by: Robert Brennan <accounts@rbren.io> Co-authored-by: Debug Agent <debug@example.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the "Coming soon." placeholder at
openhands/usage/agent-canvas/backend-setup/docker.mdxwith a full walkthrough for building a custom Agent Server image and using it as an Agent Canvas backend.The guide covers:
FROM ghcr.io/openhands/agent-server:latest-python, adding the JDK, Maven, and common utilities on top.docker runwith a generatedSESSION_API_KEY, plus acurlhealth check and safety guidance for exposing the port.Manage Backends → Add Backend, paste the URL + API key, mark it asLocal, and switch to it as the active backend.Includes cross-links to the related guides:
Target
This PR targets the
docs/onboarding-agent-canvasbranch so it stacks onto #533.This PR was created by an AI agent (OpenHands) on behalf of @rbren.