Introduction

AI coding agents have moved quickly from simple chat interfaces to tools that can interact directly with development environments. They can inspect files, write code, execute commands, test applications, and increasingly become part of larger software development workflows.

But this capability raises an important question:

Where should an AI agent actually run?

This is where containers and sandboxes become useful.

OpenHands Agent Canvas provides a browser-based workspace for agentic development, while Docker Sandboxes provide isolated environments where agents can work with tools and project files. Agent Canvas can use different backends, including Docker, and can also work with ACP-based agents such as Claude Code, Codex, and Gemini CLI.

This article explores how the openhands-canvas SBX kit brings these technologies together. It covers what Docker SBX Kits are, how authentication works, how to start the sandbox, how to access Agent Canvas from a browser, and how to troubleshoot common issues.

What Is Docker SBX?

Docker Sandboxes provide isolated environments designed for running AI coding agents. The sbx CLI can create and manage sandboxes, execute commands, manage network policies, publish ports, and manage credentials.

Docker SBX Kits provide a declarative way to package capabilities for a sandbox. A kit can define:

This allows the environment to be described as a reusable configuration instead of requiring developers to manually execute a long list of setup commands. Docker currently classifies Kits as an experimental/Early Access feature, so the kit format and related CLI behavior may change as the feature evolves.

The basic idea is:

Manual Setup
    |
    +-- Install dependencies
    +-- Configure credentials
    +-- Configure networking
    +-- Start the application
    +-- Configure access

        versus

SBX Kit
    |
    +-- Define the environment
    +-- Start the sandbox

For developers experimenting with AI coding agents, this can make environments easier to reproduce and maintain.

What Is OpenHands Agent Canvas?

OpenHands Agent Canvas is an open-source browser-based control surface for agentic work. It provides a workspace for managing conversations, files, terminals, model configuration, backends, and automations.

Agent Canvas can connect to different execution backends, including local environments, Docker, VMs, Modal, and OpenHands Cloud. It can also work with ACP agents such as Claude Code, Codex, and Gemini CLI.

This makes Agent Canvas more than a traditional chatbot interface.

For example, consider an application containing a bug. Instead of copying the error into a chat window and manually applying the suggested changes, an agent running in a development environment can potentially:

  1. Inspect the repository.

  2. Analyze the surrounding code.

  3. Modify the required files.

  4. Execute development commands.

  5. Run tests.

  6. Iterate on the implementation.

The combination of Agent Canvas + Docker Sandbox provides an environment where these activities can take place with explicit boundaries around the agent's workspace and network access.

Introducing the openhands-canvas SBX Kit

The openhands-canvas project packages the Agent Canvas environment as a Docker SBX Kit.

The basic workflow is:

  1. Start a Docker Sandbox using the kit.

  2. Install the required Agent Canvas environment.

  3. Configure model-provider authentication.

  4. Start Agent Canvas.

  5. Publish the required sandbox port.

  6. Access the interface from a browser.

Conceptually, the architecture looks like this:

Your Browser
     |
     | localhost:8000
     v
Docker Sandbox
     |
     +---- OpenHands Agent Canvas
     |
     +---- AI Agent
     |
     +---- Workspace

The purpose of the kit is to package the environment configuration so that developers do not have to manually recreate the same setup every time.

Before Starting: Configure Authentication

The agent needs access to an AI model provider.

Docker SBX supports service secrets for providers such as Anthropic and OpenAI. It also supports custom secrets when a service is not directly built into the CLI.

For a custom Anthropic secret, for example:

sbx secret set-custom -g \
    --host api.anthropic.com \
    --env ANTHROPIC_API_KEY \
    --placeholder "sk-ant-{rand}" \
    --value "$ANTHROPIC_API_KEY"

For OpenAI:

sbx secret set-custom -g \
    --host api.openai.com \
    --env OPENAI_API_KEY \
    --placeholder "sk-{rand}" \
    --value "$OPENAI_API_KEY"

However, current Docker SBX also provides built-in service-secret support, so a simpler approach may be appropriate when using supported providers:

echo "$ANTHROPIC_API_KEY" | sbx secret set anthropic

or:

echo "$OPENAI_API_KEY" | sbx secret set openai

Docker recommends using its secret mechanism instead of placing credentials directly in kit environment variables.

How Authentication Works

One of the useful properties of Docker's sandbox credential system is that the real credential does not need to be exposed directly inside the sandbox.

With custom secrets, the sandbox can receive a placeholder value. When an outbound request is made to the configured host, the sandbox proxy can replace the placeholder with the real credential in the request.

Conceptually:

Agent
  |
  | Request with placeholder
  v
Sandbox Proxy
  |
  | Inject real credential
  v
AI Provider API

This is preferable to embedding an API key directly in a Dockerfile or committing credentials to an environment file.

Docker's kit architecture treats credentials and network permissions as explicit configuration rather than allowing unrestricted outbound access.

Running the OpenHands Canvas Sandbox

Once authentication has been configured, the kit can be started from the Docker community repository.

For example:

sbx run --kit \
"git+https://github.com/docker/sbx-kits-contrib.git#dir=openhands-canvas" \
openhands-canvas

The --kit option allows the sandbox to consume the kit directly from a Git repository.

For local kit development, you can instead clone the repository and run the local kit:

sbx run --kit ./openhands-canvas openhands-canvas

The second approach is useful when you want to inspect or modify the kit configuration.

What Happens During Setup?

The kit prepares the sandbox environment and starts Agent Canvas.

A simplified view of the process is:

Sandbox Creation
       |
       v
Prepare Node.js Environment
       |
       v
Install Agent Canvas
       |
       v
Start Agent Canvas
       |
       v
Listen on Port 8000

The current Agent Canvas documentation lists Node.js 22.12 or later as a prerequisite for the normal local installation path.

The important advantage of the kit approach is that environment preparation can be encoded into the kit rather than being performed manually for every new sandbox.

Accessing the Agent Canvas Interface

Starting Agent Canvas on port 8000 inside the sandbox does not automatically make that port available on the host.

Docker SBX provides port publishing for exposing sandbox services to the host.

For example:

sbx ports openhands-canvas-sbx-kits-contrib --publish 8000:8000

After publishing the port, open:

http://localhost:8000

The workflow can therefore use two terminals.

Terminal 1

sbx run --kit \
"git+https://github.com/docker/sbx-kits-contrib.git#dir=openhands-canvas" \
openhands-canvas

Terminal 2

sbx ports openhands-canvas-sbx-kits-contrib --publish 8000:8000

Then open the application in your browser.

What If Port 8000 Is Already in Use?

You do not necessarily need to change Agent Canvas's internal port.

Instead, map another host port to port 8000 inside the sandbox:

sbx ports openhands-canvas-sbx-kits-contrib --publish 8080:8000

The mapping becomes:

localhost:8080
       |
       v
sandbox:8000

You can then open:

http://localhost:8080

The important distinction is:

Host port ≠ sandbox port

The application can continue listening on port 8000 inside the sandbox while the host exposes it through another port.

Why Use an Agent Kit?

The primary benefit is not simply running OpenHands inside Docker. Containers and isolated environments have been used for development workloads for years.

The more interesting combination is:

AI agent + isolated sandbox + reusable kit

This changes the workflow in several ways.

Isolation

An agent can work inside a controlled environment instead of having unrestricted access to the host development machine.

Repeatability

The environment configuration can be packaged into a kit, reducing the amount of manual setup required when recreating the environment.

Customization

Developers can clone the kit, modify its configuration, validate it, and run their own version.

Network Control

Sandbox policies can explicitly control which network resources the environment can access. Docker provides commands for inspecting and managing these policies.

This is particularly important for AI agents because an agent may interact with multiple external services while completing a task.

A Simple Mental Model

If you are new to Docker SBX, the architecture can be understood as follows:

                 Your Laptop
                      |
                 Web Browser
                      |
                 localhost:8000
                      |
              +-------v-------+
              |  Docker SBX   |
              |               |
              | Agent Canvas  |
              |      |        |
              |      v        |
              |   AI Agent    |
              |      |        |
              |      v        |
              |   Workspace   |
              +---------------+
                      |
                 Proxy / Network
                      |
              AI Provider API

The browser communicates with Agent Canvas.

Agent Canvas runs inside the sandbox.

The agent works inside the sandbox workspace.

Outbound requests are controlled by the sandbox network and credential configuration.

This separation makes the overall architecture easier to understand and manage.

Network Policy

Network access should be treated as an important part of the sandbox configuration.

Docker SBX uses network policies to control which resources sandboxes can access. The sbx policy commands can be used to inspect policies, allow or deny network access, and inspect policy logs.

If an application cannot connect to an external service, do not immediately assume that the application itself is broken.

Check whether the sandbox policy is blocking the required domain.

For example:

sbx policy log

The policy log can help identify blocked outbound requests while developing or troubleshooting a kit. Docker specifically recommends using the policy log when diagnosing kit networking issues.

Troubleshooting Checklist

If Agent Canvas does not work as expected, check the following items.

1. Check Whether the Sandbox Is Running

Use:

sbx ls

Look for the relevant sandbox and confirm that it is running.

2. Check Stored Secrets

Use:

sbx secret list -g

Depending on the installed SBX CLI version, the command may also be available as:

sbx secret ls

Verify that the required provider credential has been configured.

3. Check the Port

Inspect the sandbox's port configuration:

sbx ports openhands-canvas-sbx-kits-contrib

Confirm that the expected port mapping is active.

4. Try Another Host Port

If port 8000 is already in use:

sbx ports openhands-canvas-sbx-kits-contrib --publish 8080:8000

Then open:

http://localhost:8080

5. Check Network Policy

If authentication or API requests fail, inspect the network policy:

sbx policy log

A blocked domain can appear to be an application-level failure even though the underlying problem is network policy.

6. Validate the Kit

If you are developing a local version of the kit, validate it before running it:

sbx kit validate ./openhands-canvas/

Docker provides sbx kit validate specifically for validating a kit directory, ZIP file, or Git repository.

You can also inspect a kit using:

sbx kit inspect ./openhands-canvas/

The inspect command displays details about the kit configuration.

Removing Credentials

If a provider credential is no longer required, remove it from the SBX secret store.

For example:

sbx secret rm -g --host api.anthropic.com

For OpenAI:

sbx secret rm -g --host api.openai.com

Using the SBX secret mechanism makes credential management separate from the application and kit configuration.

Pin the Kit Version for Reproducibility

When experimenting, running a kit from the default branch can be convenient.

For repeatable development or team environments, however, it is better to reference a known Git branch, tag, or commit when supported by the kit reference.

Conceptually:

git+https://github.com/docker/sbx-kits-contrib.git#ref=<version>&dir=openhands-canvas

Pinning a known version reduces the risk of the underlying kit changing unexpectedly between runs.

This becomes especially important when a sandbox environment is part of a repeatable development or testing workflow.

Practical Considerations

Docker's current Kit functionality is still experimental, so developers should expect the CLI commands, kit format, and overall experience to evolve.

For experimentation, this is generally manageable. For team or production workflows, it is worth considering:

These practices make the environment easier to reproduce and troubleshoot.

Overall Takeaway

The most interesting aspect of the openhands-canvas kit is the packaging of the development environment rather than the installation of Agent Canvas itself.

An AI coding agent needs more than a model. It may need:

Docker SBX provides mechanisms for defining these pieces around an isolated agent environment, while Agent Canvas provides a browser-based interface for working with agents and their backends.

The openhands-canvas kit brings these concepts together into a repeatable setup.

Conclusion

AI development tools are evolving beyond simple chat-based assistance. Modern coding agents can inspect repositories, modify files, execute commands, run tests, and interact with external services.

As agents become more capable, the question of where they run and what they are allowed to access becomes increasingly important.

OpenHands Agent Canvas provides the workspace and agent-control experience, while Docker Sandboxes provide an isolated execution environment. SBX Kits add a reusable configuration layer for tools, credentials, network policies, files, and startup commands.

The resulting workflow can be summarized as:

Configure API Credential
        ↓
Start Docker SBX Kit
        ↓
Prepare Agent Canvas
        ↓
Start Agent Canvas
        ↓
Publish Port 8000
        ↓
Open Browser
        ↓
Work With the AI Agent

The key advantage is repeatability. Instead of manually preparing an agent environment each time, developers can package the required configuration into a sandbox kit and recreate the environment when needed.

For developers experimenting with AI coding agents, Docker Sandboxes, and OpenHands, this approach demonstrates how isolated and reusable agent environments can become an important part of modern development workflows.