Hyland Connect

angelborroy

Run an AI coding agent against your Alfresco repository (safely, in an isolated micro-VM) with a single command. The new alfresco-mcp kit for Docker Sandboxes wires the AlfrescoLabs MCP server into agents like Claude Code, so they can search, browse, and manage your content through the Alfresco REST API without ever touching your host machine.

This post introduces Docker Sandboxes, explains why they matter for Alfresco developers, and walks you through getting the kit working end‑to‑end, from an empty machine to an agent that can query your repository.

What are Docker Sandboxes?

Docker Sandboxes (the sbx CLI) run AI coding agents inside isolated micro‑VMs. Each sandbox is self‑contained: it has its own Docker daemon, its own filesystem, and its own network. The agent can build images, install packages, edit files, and call out to services: but it does all of that inside the box, not on your laptop.

That isolation is the whole point. When you let an autonomous agent act on a content repository (uploading documents, editing metadata in bulk, deleting nodes, checking files in and out) you want a hard boundary around what it can reach. A sandbox gives you exactly that, and its outbound network policy is an explicit, auditable allow‑list: the agent can only talk to the hosts you declare.

Sandboxes are extended with kits: small, declarative artifacts (a spec.yaml plus optional files) that add a capability to an agent. There are two kinds:

Agent kits define a complete agent with its own runtime and entry point.
Mixin kits layer a single capability (a tool, a config, an MCP server) onto an existing agent such as claude. They are composable, so you can stack several at once.

The Alfresco kit is a mixin: it bolts the Alfresco MCP server onto whatever agent you are already running.

Why this matters for Alfresco developers

Model Context Protocol (MCP) is the emerging standard for giving AI assistants typed, tool‑style access to external systems. The AlfrescoLabs MCP server exposes the Alfresco REST API as a set of MCP tools, so an agent can do real content work: full‑text and CMIS search, repository browsing, document upload and download, PDF renditions, folder creation, metadata read/update, and the full check‑out / check‑in / cancel lifecycle.

The kit packages that server so you do not have to install Python, clone a repo, pin a version, or write an MCP client config by hand. One --kit flag, and your agent has Alfresco tools, running behind the sandbox boundary, talking only to the repository you point it at.

What the kit actually does

When you attach the alfresco-mcp kit, it:

downloads the AlfrescoLabs MCP server, pinned to an exact commit and SHA256‑verified before use (no curl | sh, no moving latest tag);
installs its two Python dependencies (fastmcp and httpx);
registers it as a stdio MCP server named alfresco in the agent's configuration, so the agent discovers it automatically;
points it at the repository at ALFRESCO_HOST (default http://host.docker.internal:8080, i.e. an Alfresco running on your host).

The egress allow‑list is deliberately narrow: only the hosts needed to install the server (raw.githubusercontent.com, pypi.org, files.pythonhosted.org). The repository itself is reached over the Docker bridge, which is exempt from the allow‑list, so the default local setup needs no extra network configuration.

Walk-through: from scratch to a working agent

By the end of these steps you will have an AI agent, inside a sandbox, answering questions about content in your local Alfresco.

Prerequisites

Docker Desktop (or a Docker Engine) installed and running.
12 GB of free RAM if you run Alfresco locally: the full stack (repository, Solr, transform engine, ActiveMQ, PostgreSQL) is JVM‑heavy.
A terminal. The commands below assume macOS or Linux.

Step 1. Install the sbx CLI

On macOS (Homebrew):

brew install docker/tap/sbx

On Windows (winget):

winget install -h Docker.sbx

On Linux (Ubuntu):

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm

Then authenticate:

sbx login

Step 2. Start Alfresco Community locally

If you already have an Alfresco instance reachable on your host at port 8080, skip to Step 3. Otherwise, use the official acs-deployment Docker Compose definition (this example uses Alfresco Community 26.1):

git clone https://github.com/Alfresco/acs-deployment.git
cd acs-deployment/docker-compose
docker compose -f community-compose.yaml up

Give it a few minutes on first start, Solr indexing and several JVMs need to warm up. When it is ready, the front door is at http://localhost:8080:

Repository (REST API): http://localhost:8080/alfresco
Content App: http://localhost:8080/
Share: http://localhost:8080/share

The default administrator credentials are admin / admin. Confirm the repository is up:

curl http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/probes/-ready-

Step 3. Launch an agent with the Alfresco kit

From any project directory, start the claude agent with the kit attached. The kit is published as an OCI artifact on Docker Hub:

sbx run claude --kit docker.io/angelborroy/sbx-alfresco-mcp-kit:1.1.0 .

Prefer to pull straight from source instead of the published image? You can reference the kit's subdirectory in its GitHub repo:

sbx run claude --kit "git+https://github.com/aborroy/sbx-alfresco-mcp-kit.git#dir=alfresco-mcp" .

On first run the sandbox installs the MCP server (verifying its checksum) and registers it with the agent. When the agent starts, the alfresco MCP server is available.

Pointing at a non‑default repository? Override ALFRESCO_HOST. Anything on host.docker.internal or localhost works out of the box; for a remote Alfresco, fork the kit and add that host to the network allow‑list, because the sandbox runs deny‑all.

Step 4. Authenticate to Alfresco

Alfresco uses short‑lived, per‑user tickets rather than a long‑lived API key, so the kit does not bake in a credential. Get a ticket from the authentication API:

curl -s -X POST \
  "http://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/tickets" \
  -H "Content-Type: application/json" \
  -d '{"userId":"admin","password":"admin"}'

The response contains the ticket in entry.id:

{"entry":{"id":"TICKET_abc123...","userId":"admin"}}

Now hand that ticket to the agent — just ask it in natural language, for example:

Call the set_ticket tool with the ticket TICKET_abc123...

(For non‑interactive use you can instead preset the ALFRESCO_TICKET environment variable, and the server picks it up on start.)

Step 5. Put the agent to work

With a ticket registered, try prompts like:

“Show me the repository information.”
“List the children of the Company Home folder.”
“Search for documents that mention ‘invoice’ and summarise what you find.”
“Create a folder called Reports under Shared, then upload this file into it.”
“Check out that document, update its title property, and check it back in.”

Behind the scenes the agent is calling MCP tools such as search_content, advanced_search, cmis_search, browse_repository, upload_document, download_document, get_pdf_rendition, create_folder, get_node_properties, update_node_properties, delete_node, and the check‑out / check‑in / cancel trio: all against your repository, all inside the sandbox.

Explore other Docker Sandboxes kits

The Alfresco kit is one mixin among a growing community catalog. The docker/sbx-kits-contrib repository collects kits you can mix and match with any agent. A few worth knowing:

code-server : runs web‑based VS Code in the sandbox with the Claude Code extension pre‑installed.
trivy : the Aqua vulnerability scanner, sandboxed so a scanner can never compromise the host.
vale : the Vale prose linter, handy for documentation work.
mise : the polyglot dev‑tool version manager, for per‑project runtimes.
task : the Task runner, for executing Taskfile.yml targets.
github-ssh and git-ssh-sign : pre‑populate GitHub SSH host keys and sign commits with a forwarded SSH key.
nanobot and pi : alternative lightweight agents.

Attaching one is the same pattern you used above, pin to a subdirectory of the repo:

sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=code-server" .

You can pass multiple --kit flags to stack capabilities, for example, the Alfresco kit alongside code-server for a browser‑based editor that can also drive your repository.

Get involved

The kit is open source (Apache‑2.0) and the MCP server lives under AlfrescoLabs:

Kit repository: github.com/aborroy/sbx-alfresco-mcp-kit
Published image: docker.io/angelborroy/sbx-alfresco-mcp-kit:1.1.0
MCP server: github.com/AlfrescoLabs/alfresco-mcp-server

Try it against your own repository, file issues, and send pull requests: new tools, a hardened install path, or support for additional agents are all welcome. If you build something interesting on top of it, share it back with the community here on Hyland Connect.

Happy (sandboxed) hacking