Contribute / Development

Clone Agent Canvas, run it from source, and use the developer workflows.

This page is for contributors and advanced users who want to run Agent Canvas from a local checkout. If you only want to use Agent Canvas, follow the Setup guide instead.

Clone the Repository

git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install

Recommended Local Workflow

The standard development flow runs the full local stack with live frontend updates:

npm run dev

That workflow uses uvx to start the agent server and automation backend, then fronts them with the Vite dev server and ingress proxy.

That workflow starts:

• the Agent Canvas frontend
• the OpenHands agent server
• the automation backend
• the ingress proxy that ties them together

Other Useful Development Modes

Command	When to Use It
npm run dev	Full local development stack
npm run dev:static	Serve a static frontend build instead of the Vite dev server
npm run dev:minimal	Run only the agent server and Vite, without automation or ingress
npm run dev:extra-backend	Start an additional local backend that shares the main dev stack’s persistence
npm run dev:frontend	Point the frontend at a separately managed backend
npm run dev:mock	Work on the UI without a live backend

npm run dev:minimal serves the frontend directly on http://localhost:3001.

npm run dev:frontend expects a separately managed backend at 127.0.0.1:8000 unless you override the frontend proxy settings.

Verification Commands

Use the repo’s built-in checks before sending a change upstream:

npm run test
npm run build

Development Environment Variables

You can place frontend overrides in a local .env file based on .env.sample.

These variables are mainly useful when you are running Agent Canvas from a local checkout.

Launcher Variables

Variable	Purpose
PORT	Ingress port for the bundled development stack
OH_AUTOMATION_GIT_REF	Git ref used for the automation backend
OH_CANVAS_SAFE_BACKEND_PORT	Backend port for the isolated local agent server
OH_CANVAS_SAFE_VSCODE_PORT	VS Code sidecar port for the isolated local agent server
OH_CANVAS_SAFE_STATE_DIR	Base directory for isolated local state

Frontend Variables

Variable	Purpose
VITE_BACKEND_BASE_URL	Base URL used by browser-side requests
VITE_BACKEND_HOST	Backend target for the Vite dev proxy
VITE_SESSION_API_KEY	Session API key to send when the backend requires one
VITE_WORKING_DIR	Workspace path used for new conversations; defaults to the current checkout
VITE_WORKER_URLS	Optional worker URLs for Browser integrations
VITE_ENABLE_BROWSER_TOOLS	Disable browser tools for new conversations when set to false
VITE_LOAD_PUBLIC_SKILLS	Enable loading public skills when set to true
VITE_FRONTEND_PORT	Frontend dev server port
VITE_USE_TLS	Use HTTPS or WSS for the dev proxy
VITE_INSECURE_SKIP_VERIFY	Skip TLS verification for proxied backend requests
VITE_MOCK_API	Enable mock API responses

Advanced Source Overrides

The development stack also supports source and version overrides for the agent server:

• OH_AGENT_SERVER_LOCAL_PATH
• OH_AGENT_SERVER_GIT_REF
• OH_AGENT_SERVER_VERSION

When more than one is set, the effective precedence is local source path, then git ref, then pinned version.

These are useful when you are developing Agent Canvas alongside a local software-agent-sdk checkout.

Learn More

• Agent Canvas Repository
• Self-Hosting Agent Canvas