OpenHands vs SWE-agent

Agent Canvas

The self-hosted developer control center for coding agents and automations.

Run OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, or any ACP-compatible agent across local, remote, and cloud backends.

OpenHands Agent Canvas turns your coding agents into a self-hosted, always-on engineering team. It's a developer control center for starting conversations and automating everyday tasks — like generating reports that publish to Slack or automatically decomposing GitHub issues into tasks.

It runs locally on your machine by default, but can connect to multiple “agent backends”, e.g. running agents in Docker containers, on VMs, or within your company infrastructure. You can optionally choose to run agents on OpenHands Cloud or OpenHands Enterprise infrastructure.

Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use third-party agents such as Claude Code, Codex, Gemini CLI, Pi, and OpenCode.

If you have questions or feedback, please open a GitHub issue or join the #proj-agent-canvas channel in Slack.

Quickstart

You can install OpenHands to run agents on any machine: on your laptop, on a dedicated computer like a Mac Mini,
or on a server in the cloud.

The most powerful way to run OpenHands is on a server in the cloud. This allows your agents to continue running
even when your laptop is shut, and makes it easier to trigger your agents through third-party services
like Slack, GitHub, and Datadog. See SELF_HOSTING.md for details, especially with respect to security hardening.

Notably, you can run the backend in multiple different environments, and switch between
them from the same Agent Canvas frontend. E.g. you can share an Agent Server with your team for agents doing
code review and dependency updates, then have your personal agents running on your laptop.

Option 1: Without a Sandbox

[!WARNING]
This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!

Prerequisites: Node.js 24 or later, uv

npm install -g @openhands/agent-canvas
agent-canvas

The agent-canvas command starts the full local stack by default. You can also split it when you want to run pieces separately:

agent-canvas --frontend-only  # static frontend + ingress only
agent-canvas --backend-only   # agent server + automation backend + ingress only

Option 2: With a Docker Sandbox

Install Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux.
Windows users can follow the PowerShell quickstart.

The steps below are for macOS and Linux. A named Docker volume stores settings,
secrets, and conversations; projects are mounted at /projects.

1. Prepare a workspace

export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
mkdir -p "$PROJECTS_PATH"

On Linux Docker Engine, uid 10001 inside the container must be able to read
and write the workspace and its existing files. Grant that user access using
appropriate ownership or ACLs for your system. For a dedicated workspace you are
comfortable sharing with all local users, the following is another option:

find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} +
find "$PROJECTS_PATH" -type f -exec chmod a+rw {} +

These commands grant all host users access to the workspace. Keep it separate
from ~/.openhands and other sensitive data. Docker Desktop on macOS/Windows
handles bind-mount permissions, so those commands are normally unnecessary.

2. Start Agent Canvas

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v openhands-state:/home/openhands/.openhands \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.39.0 # x-release-please-version

Open http://localhost:8000/canvas. Reuse
openhands-state to retain state across container removals. A fresh volume does
not contain existing ~/.openhands data; inspect or back it up with
docker volume inspect openhands-state.

[!NOTE]
The entrypoint stops the container with exit code 1 when the Agent Server stops answering
its /alive check for about 30 seconds, so a crash or hang fails visibly instead of leaving
a container that returns 502 for every request.
Automatic recovery needs a restart policy: use --restart unless-stopped instead of
--rm, or restart: unless-stopped in Docker Compose.

The agent will be able to access any project under PROJECTS_PATH.

Option 3: With Multiple Docker Sandboxes

Run each new conversation in its own Docker container, with its own Agent Server and tools. This is useful for running several agents concurrently. Canvas and the outer Agent Server run on your host and route conversation requests to the containers.

Prerequisites: Node.js 24 or later, uv, and a running Docker Desktop (macOS) or Docker Engine/Desktop (Linux). The user starting Canvas must be able to run docker commands.

macOS / Linux:

npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas

Open http://localhost:8000 and start a new conversation. Existing local conversations are not converted. Each container mounts its conversation's workspace and persisted state, so workspace files and conversation history survive container replacement. Conversations using the same host workspace still share those files; choose separate directories or worktrees to avoid conflicting edits.

This setting isolates conversation execution; it does not move the entire Canvas or automation service into a sandbox. For Windows, see README.windows.md.

Option 4: From Source

[!WARNING]
This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!

Prerequisites: Node.js 24 or later, npm 11.12.1 (the repository pin), uv (for running the agent server via uvx)

Check npm --version before resolving dependencies. The seven-day release-age
filter (npm install --min-release-age=7) requires npm >=11.10; older versions
do not enforce it. Use npm ci to replay the committed lockfile. This npm
requirement is for contributor dependency resolution, not for installing the
published Canvas package.

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm ci
npm run dev

Access the UI at http://localhost:8000 for the npm/source launchers, or http://localhost:8000/canvas for the Docker image. You can add additional backends directly from the UI.

Local (npx / npm run dev) listeners bind loopback only (127.0.0.1) so the auto-injected session key is not reachable from other machines on the network. To listen on all interfaces, pass --host 0.0.0.0 (or set OH_BIND_HOST); the session key is then not injected and the UI uses the same API-key entry screen as --public.

Docker listens on all container interfaces so port publishing works, but does not inject its session key into HTML by default. The quickstart above explicitly enables injection while publishing the host port on 127.0.0.1 only. If you publish Docker on a LAN or public interface, omit AGENT_CANVAS_ALLOW_LAN_SESSION_KEY and enter the API key in the UI. Set LOCAL_BACKEND_API_KEY to a strong value, or retrieve the generated value with docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"'. For internet-facing installs, follow self-hosting.

Architecture

Agent Canvas is powered by the OpenHands Agent Server, a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.

You can run an Agent Server anywhere:

• Directly on your laptop (be careful!)
• On a dedicated machine like a Mac Mini
• On a virtual machine in the cloud
• Inside OpenHands Cloud (our commercial offering)

The Agent Server is often paired with an Automation Server, which lets you set up agents that run on a schedule or in response to events.

Repository boundaries

Agent Canvas is part of a multi-repository OpenHands system. Changes should go to the repository that owns the behavior:

The Agent Server API is implemented by the SDK and consumed through the TypeScript client by Agent Canvas. The automation service decides when work runs and dispatches conversations to the Agent Server/SDK, which decides what runs. See AGENTS.md for contributor-specific boundaries and the required custom code-review guide.

More documentation

• Documentation index
• Architecture overview
• Development guide, including embedding Canvas components in a host app (load @openhands/agent-canvas/styles.css once next to the component imports)
• Self-hosting guide

[!warning]
Most of our current development effort is on mini-swe-agent,
which has superseded SWE-agent. It matches the performance performance of SWE-agent, while being
much simpler.
See the FAQ for more details about the differences.
Our general recommendation is to use mini-SWE-agent instead of SWE-agent going forward.

SWE-agent enables your language model of choice (e.g. GPT-4o or Claude Sonnet 4) to autonomously use tools to
fix issues in real GitHub repositories,
find cybersecurity vulnerabilities, or
perform any custom task.

• ✅ State of the art on SWE-bench among open-source projects
• ✅ Free-flowing & generalizable: Leaves maximal agency to the LM
• ✅ Configurable & fully documented: Governed by a single yaml file
• ✅ Made for research: Simple & hackable by design

SWE-agent is built and maintained by researchers from Princeton University and Stanford University.

📣 News

• July 24: Mini-SWE-Agent achieves 65% on SWE-bench verified in 100 lines of python!
• May 2: SWE-agent-LM-32b achieves open-weights SOTA on SWE-bench
• Feb 28: SWE-agent 1.0 + Claude 3.7 is SoTA on SWE-Bench full
• Feb 25: SWE-agent 1.0 + Claude 3.7 is SoTA on SWE-bench verified
• Feb 13: Releasing SWE-agent 1.0: SoTA on SWE-bench light & tons of new features
• Dec 7: An interview with the SWE-agent & SWE-bench team

🚀 Get started!

👉 Try SWE-agent in your browser: (more information)

Read our documentation to learn more:

• Installation
• Hello world from the command line
• Benchmarking on SWE-bench
• Frequently Asked Questions

SWE-agent for offensive cybersecurity (EnIGMA)

SWE-agent: EnIGMA is a mode for solving offensive cybersecurity (capture the flag) challenges.
EnIGMA achieves state-of-the-art results on multiple cybersecurity benchmarks (see leaderboard).
Please use SWE-agent 0.7 while we update EnIGMA for 1.0.

In addition, you might be interested in our other projects:

Contributions

If you'd like to contribute to the codebase, we welcome issues and pull requests! For larger code changes, we always encourage discussion in issues first.

Citation & contact

SWE-agent is an academic project started at Princeton University by John Yang*, Carlos E. Jimenez*, Alexander Wettig, Kilian Lieret, Shunyu Yao, Karthik Narasimhan, and Ofir Press.
Contact person: John Yang, Carlos E. Jimenez, and Kilian Lieret (Email: johnby@stanford.edu, carlosej@cs.princeton.edu, kl5675@princeton.edu).

If you found this work helpful, please consider citing it using the following:

@inproceedings{yang2024sweagent,
  title={{SWE}-agent: Agent-Computer Interfaces Enable Automated Software Engineering},
  author={John Yang and Carlos E Jimenez and Alexander Wettig and Kilian Lieret and Shunyu Yao and Karthik R Narasimhan and Ofir Press},
  booktitle={The Thirty-eighth Annual Conference on Neural Information Processing Systems},
  year={2024},
  url={https://arxiv.org/abs/2405.15793}
}

If you used the summarizer, interactive commands or the offensive cybersecurity capabilities in SWE-agent, please also consider citing:

@misc{abramovich2024enigmaenhancedinteractivegenerative,
      title={EnIGMA: Enhanced Interactive Generative Model Agent for CTF Challenges},
      author={Talor Abramovich and Meet Udeshi and Minghao Shao and Kilian Lieret and Haoran Xi and Kimberly Milner and Sofija Jancheska and John Yang and Carlos E. Jimenez and Farshad Khorrami and Prashanth Krishnamurthy and Brendan Dolan-Gavitt and Muhammad Shafique and Karthik Narasimhan and Ramesh Karri and Ofir Press},
      year={2024},
      eprint={2409.16165},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2409.16165},
}

🪪 License

MIT. Check LICENSE.