Getting Started with OpenHands

OpenHands (Agent Canvas) is a self-hosted developer control centre for coding agents. You run a local browser UI that talks to an agent backend; the agent can work in workspaces you open, while you stay responsible for what it can reach. Official setup docs cover npm (npm install -g @openhands/agent-canvas), npx @openhands/agent-canvas, Docker with mounted projects, and a from-source path. Prerequisites for the npm/npx path include Node.js 22.12+ and uv. Docs: docs.openhands.dev. Product home historically pointed at all-hands.dev; follow the current OpenHands docs for install commands.

This guide is for after-work learners who want a browser-based agent stack on their laptop—not a cloud sales tour. One evening: start Agent Canvas locally, configure an LLM, open a practice workspace, and run one small conversation. Treat the agent as untrusted: it can run shell commands with the permissions of its backend.

Surveying tools? See top AI agent tools for after-work Python. Tonight you only need a working local Canvas.

Who this is for

• People comfortable installing Node tooling and opening localhost in a browser
• Learners who prefer a UI over a pure terminal agent—but still review every action
• Anyone with 60–90 minutes and a practice folder that holds no work secrets

If Node 22+ or Docker feels like a whole weekend, pick a lighter CLI agent tonight and return later.

Steps (one evening)

1. Check prerequisites

node --version
npm --version
uv --version

You want Node.js 22.12 or later. If uv / uvx is missing, install uv before starting Agent Canvas—the local agent server runtime uses it (per official setup docs).

2. Start Agent Canvas the simple way

Try without a global install:

npx @openhands/agent-canvas

Or install once, then run:

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

Open http://localhost:8000 if the browser does not open itself. Prefer this local path on night one. Docker sandboxing is documented when you specifically want clearer file boundaries; skip it until the plain local UI works.

3. Connect the backend and configure an LLM

Confirm the default local backend shows as connected. Open Settings → LLM and configure a model/provider you already pay for. Do not paste keys into the conversation pane; use the settings UI. If the page is blank, check the terminal for a busy port (agent-canvas --port 3000 is documented) or a missing prerequisite.

4. Open a practice workspace

Create ~/openhands-practice with a tiny Python file you own. In Canvas, choose Open Workspace (or the equivalent workspace picker) pointed at that folder—not at Documents full of client exports. Official docs warn that without a container/VM boundary, the agent can act with your user permissions.

5. Start one small conversation and stop

Ask for something verifiable: “Add hello_len.py that prints the length of a hard-coded list of three strings.” Watch the proposed actions. When the file exists, run it yourself in a normal terminal. End the session while it is still small.

Tiny exercise (10 minutes)

Ask the agent to add greet.py with input() and a greeting print. Run it twice. Then edit the string by hand. Quit Agent Canvas with Ctrl+C in the terminal that launched it.

Pitfalls

• Assuming the UI isolates the agent. Agent Canvas is the client; isolation needs Docker/VM as documented. Local backends share your user permissions.
• Pointing at a real work tree on night one. Mount or open only practice folders.
• Skipping uv. Missing uv is a common startup failure on the npm/npx path.
• Exposing --public or remote backends casually. Keep the first run on localhost.
• Letting the agent replace learning Python. Use it to draft; read and run the files yourself.

Next step

When the local stack feels calm, put the next evenings into Python fundamentals. Start with Introduction to Python Programming—short after-work lessons, not a three-day workshop you cannot attend.