You opened Agent Canvas, but you are unsure whether the desktop preview, Docker, or a remote server should run the actual agent.

Choose the desktop preview or npx for a fast personal trial, Docker when the agent needs a clear local file boundary, and a remote backend when you need continuous operation, team access, or stronger compute. The desktop app lowers startup effort; it does not automatically provide a security sandbox.

Last updated September 6, 2026. Installation paths, preview status, backend behavior, and release details were checked against the official Agent Canvas setup documentation, architecture guide, backend guides, and the 1.16.0 release notes.

This guide is for individual developers who want a first successful task without learning the full Node.js and uv toolchain first, users who need to restrict an agent’s project access, and platform engineers preparing a persistent backend for a team.

The installation decision

Use the following conditions before you install anything:

  • If you only need to test Agent Canvas on one computer, choose the desktop preview first. If the preview is unavailable or unsuitable for your operating system, use the official npx path.
  • If you want a temporary local run without a packaged app, choose npx. Use npm when you need a local installation that you can manage as part of a project or development environment.
  • If the agent must edit a local repository but should only see a deliberately selected directory, choose Docker and mount only that directory.
  • If the process must continue after your laptop sleeps, the terminal closes, or your network changes, move the active backend to an independent VM or remote host.
  • If several people need access, separate the shared Canvas client from the shared backend and the execution environment. A common interface does not automatically create a safe shared workspace.
  • If the task requires Xcode, Apple SDKs, signing tools, or other macOS-only tooling, route execution to a suitable remote Mac instead of assuming that a Linux backend can reproduce the environment.

The official architecture separates the Canvas client, the active backend, and the environment where the agent actually executes work. That separation is the key to a correct OpenHands Agent Canvas installation decision, because the window you see is not necessarily where commands run or files are stored. Review the Agent Canvas architecture model before connecting a backend.

What each installation path really changes

Desktop preview

The Agent Canvas Desktop App is the shortest path for a first trial. It packages the client experience so you can avoid making Node.js, npm, npx, and local frontend dependencies your first troubleshooting task. The official documentation still identifies the macOS, Windows, and Linux desktop applications as early preview software, so treat the application as a convenient entry point rather than a mature isolation boundary.

The desktop preview changes how you start the client. It does not, by itself, prove that the agent runs in a sandbox, that your project stays inside a protected directory, or that an interrupted task will resume after the computer sleeps. Those properties depend on the connected backend and execution environment.

Does the Agent Canvas desktop app require Node.js?

For a packaged desktop preview, Node.js is not normally the first dependency you need to install. For npx or npm installation, Node.js becomes part of the local toolchain. Confirm the current supported installation method on the official setup page before choosing a version, because the supported command and packaging behavior can change between releases. The Node.js package-manager documentation explains how to install Node.js through supported package-manager workflows.

The desktop path is a good fit when the agent will work on a disposable example, your computer will remain available, and you are evaluating the interaction rather than building a persistent service. If dependency or access questions remain after the first launch, SSHMac’s help center is a useful place to review remote-environment requirements before moving the workload off your workstation.

npx and npm

npx is useful when you want to invoke the published package without maintaining a permanent global installation. It is a reasonable fallback if you want the current command from the official setup page but do not need to build a reusable local service around the client.

npm is more appropriate when you want the package recorded in a project environment, controlled through a package manifest, or updated as part of a deliberate maintenance process. Neither choice automatically changes the permissions available to the agent. If the client connects to a backend that can access your home directory or a broad workspace, the package manager choice does not narrow that access.

The operational difference is also visible when the process stops:

  • A desktop preview stops when its backend or local execution process stops.
  • An npx process normally depends on the terminal session unless you deliberately run it under a suitable process manager.
  • An npm-managed installation is easier to reproduce, but it still needs a running process and a defined workspace.
  • A remote backend can continue independently, provided the host, process supervision, storage, and access controls are configured correctly.

Docker

Docker is the stronger local choice when you need a repeatable start command and a deliberate project boundary. The official Docker backend guide for Agent Canvas should be treated as the source of the current image, environment variables, connection settings, and startup procedure.

Docker does not mean that the agent can see nothing. It can access whatever you mount, whatever credentials you pass into the container, and whatever network services the container can reach. A container with your entire home directory mounted is not meaningfully restricted to one repository.

Use a named volume or another explicit persistent storage method for configuration that must survive container replacement. Docker’s volume documentation explains why container-local writable data should not be treated as durable storage. The container’s filesystem and the mounted project directory are different persistence decisions.

A Docker boundary is a process and filesystem boundary, not automatically a complete tenant-isolation model. Review mounted paths, environment variables, credentials, network access, and host permissions before exposing it to other users.

The local project boundary

The most important security question is not whether the interface looks polished. It is where the agent runs and which identity it inherits.

When the agent runs directly on your computer, it may inherit the permissions of the local user or of the process that launched the backend. That can include access to more files than the current repository, local configuration files, SSH material, package caches, and credentials. The exact exposure depends on your operating system permissions, launch method, environment variables, and selected workspace.

A direct local run is acceptable when all of the following are true:

  • The repository is non-sensitive or safely backed up.
  • The agent only needs the permissions of your normal development account.
  • You can inspect and revert changes through version control.
  • You are not passing production credentials or broad cloud credentials into the process.
  • You understand that stopping the interface may not stop a separately running backend.

Docker is preferable when you can define the boundary before the task starts. Mount the project directory rather than the entire home directory. Keep configuration in a persistent location that is separate from disposable container layers. Pass only the credentials required for the task, and check whether the container can reach internal services that it does not need.

Is local OpenHands installation safe?

It can be made safer, but “local” is not the same as “isolated.” Review the files visible to the process, the user identity under which it runs, the mounted directories, the network routes, and the credentials available to commands. The official Docker security guidance is useful for understanding the limits of container-based isolation. For sensitive repositories, start with a disposable copy and a narrowly mounted workspace instead of granting access to your primary development home.

A five-step first-run validation

Do not judge an installation only by whether the Canvas window opens. Validate the agent, backend, workspace, and recovery behavior separately.

1. Select the execution location

Write down where the agent will execute:

  • On the local host for a direct desktop, npx, or npm run.
  • Inside a Docker container for a mounted local project.
  • On a VM or remote host for an independent backend.
  • On a remote Mac when the task requires Apple-specific tooling.

If you cannot answer this clearly, do not connect a sensitive repository yet.

2. Follow the matching official setup path

Use the current command and dependency instructions from the official Agent Canvas installation page. Avoid copying an old command from a forum post or assuming that the desktop preview and npm client use the same update process.

For a desktop preview, open the application and check whether it asks you to start or connect to a backend. For npx or npm, verify that the required Node.js installation is available before launching the client. For Docker, record the image reference, mounted paths, environment variables, and network settings used to start the backend.

3. Run a harmless workspace task

Create a disposable test directory or use a throwaway branch. Ask the agent to list the workspace, create a small text file, and report its path. This confirms where it can read and write.

Do not begin with a request that edits authentication code, deployment files, or production configuration. The first task should produce observable evidence, not a large code change.

4. Verify the boundary from both sides

Check the host and the execution environment:

  • Can the agent read a file outside the intended project?
  • Can it write outside the intended project?
  • Does the container see only the mounted directory and required configuration?
  • Which user owns files created by the agent?
  • Are credentials present in the environment?
  • Can the backend reach internal or public network services?

A successful task proves execution. It does not prove containment.

5. Stop, restart, and reconnect

Close the Canvas client, stop the terminal process or container, and reconnect. Confirm which task state, configuration, and workspace changes remain.

For Docker, recreate the container and verify that the persistent volume still contains the expected configuration. For a remote backend, disconnect the client and reconnect from another device or network that is permitted by your policy. Then verify whether a running task remains visible and whether its workspace is still available.

This test distinguishes a real persistent backend from a local process that only appeared to be persistent while your terminal remained open.

Team sharing and heterogeneous toolchains

A team deployment has three separate sharing decisions:

  1. Shared interface: multiple users connect to the same Canvas service.
  2. Shared backend: multiple users use the same agent service or host.
  3. Shared execution environment: multiple tasks run with access to the same files, credentials, tools, or operating-system identity.

These should not be treated as one setting. A shared interface can still connect each user to a separate backend. A shared backend can still isolate workspaces. A shared execution host can still create unacceptable cross-project exposure if permissions and storage are poorly separated.

For Linux-compatible tasks, a Linux VM or container pool may be easier to reproduce. Tasks that require Xcode, Apple SDKs, macOS signing, or other Apple tooling need a macOS execution pool instead. Moving the Canvas client to a Mac does not make a Linux backend capable of running macOS-only tools.

Use these conditions for team planning:

  • If tasks are independent and short-lived, separate workspaces and short-lived execution environments may be enough.
  • If tasks must survive user disconnects, use an independently managed backend with process recovery and persistent storage.
  • If multiple users handle sensitive repositories, separate credentials, workspaces, and access policies instead of sharing one broad host identity.
  • If environments must be reproduced, define the image, mounted paths, configuration storage, and recovery procedure as deployment assets.
  • If a task needs Apple tooling, route it to a controlled remote Mac and keep Linux and macOS workloads in separate pools.

Desktop-to-remote migration

A sensible migration path avoids moving every user to a remote server on the first day.

Start with the desktop preview or npx for a harmless personal task. Once the task needs to continue while your computer is offline, move the backend to a VM or remote host. Keep the Canvas client local if that is convenient, but document the backend address, authentication method, workspace location, and recovery process.

Before switching users, test four events:

  • The local client disconnects.
  • The terminal or client process closes.
  • The host restarts.
  • The user reconnects from an approved device.

A backend that passes only the first connection test is not ready for team use. You also need to know whether the agent process restarts, whether the workspace survives, whether partial changes remain visible, and whether another user can accidentally reach the same files.

The Agent Canvas release notes for version 1.16.0 are relevant when checking release-specific behavior. Record the client version, backend version, installation method, and connection mode in your deployment notes. Preview software can change its supported architectures, commands, or connection flow.

Current setup versus a remote Mac

A desktop preview is the fastest way to see whether Agent Canvas fits your workflow, but it becomes a weak long-term execution platform when your laptop must stay awake, local storage must remain available, or several users need the same backend. Direct local execution also makes permission review harder because the agent may inherit a broad user identity. Docker improves repeatability and file boundaries, but it still depends on the host and does not reproduce macOS tooling.

For a temporary development environment, a remote Mac can provide a cleaner separation from your daily workstation, preserve access to Apple-specific tools, and keep the active backend independent from laptop sleep. SSHMac can be relevant when you need a remote Mac environment for testing or short-lived execution; review the available Mac access options against your task duration, toolchain, storage, and access requirements before choosing it.

If you are still validating Agent Canvas, stay with the smallest path that proves your task: desktop preview or npx first, Docker when the local file boundary matters, and a remote backend when persistence or team access becomes a requirement. When Apple tooling or independent uptime is the deciding factor, move the execution environment rather than forcing the desktop client to solve a backend problem.