Developer Hub

Give the agent an isolated coding workspace

Optional custom setup: run agent commands in one locked-down Docker container, check real exit codes and review every change.

Optional custom reference setup

This guide continues Connect a raia agent to local tools and uses the same reference starter (ZIP). It is not a built-in raia feature or a production build system. A person reviews every change before it is merged, deployed or used in production.

What you are building

You turn on a /coding/mcp endpoint with three tools that run commands inside one demo Docker container, raia-local-reference-demo, rather than in your PC's own shell:

Tool	What it does
`command_start`	Starts a command in the container and returns a job ID
`command_status`	Shows whether the job is running, the end of its output and, when finished, the real exit code
`command_stop`	Asks a running job to stop; check its status afterwards

text

raia CX integration Local_Coding
  → https://<your-tunnel-host>/coding/mcp
  → starter gateway (key, Origin, tool list)
  → docker exec into container raia-local-reference-demo (non-root)
  → /workspace  ← the starter's workspace/demo folder, the only folder shared

This is an illustration of the local parts, not a raia screen.

The difference between the container shell and your PC's shell is the point of this setup. In this sample, the only folder from your PC shared with the container is workspace/demo, and it is writable, so commands can change or delete those demo files. The container also has network access. A command in your PC's own shell could reach every file and credential you have. Keep credentials out of the demo folder. This sample does not connect to any production system, and a person still reviews every result. These settings are a reasonable starting point, not a certified isolation boundary.

Step 1 — Review and start the demo container

Docker Desktop must be installed and running with Linux containers. Read coding/Dockerfile and coding/compose.yaml in the starter first, then from the starter folder:

powershell

docker compose -f coding/compose.yaml up --build -d
docker compose -f coding/compose.yaml ps

The Compose project is named raia-local-reference, so it does not mix with other Docker projects on your PC. The second command should list raia-local-reference-demo as running. The Compose file sets these protections, described in Docker's Compose services reference:

Setting	Why it matters
`user: "1000:1000"`	Commands do not run as root
`read_only: true`	The container's own system files cannot be changed
`cap_drop: [ALL]`, `no-new-privileges:true`	Removes extra Linux powers and blocks gaining new ones
`mem_limit`, `cpus`, `pids_limit`	Limits how much CPU, memory and process capacity the container can use
`../workspace/demo:/workspace`	The only folder from your PC mounted into the container (writable)
`dependencies`, `home` volumes	Installed packages and caches stay writable without opening more of your PC

There is no Docker socket, no credential folder and no other folder from your PC mounted. The container can still use the network and can change the demo files, so keep only demo content there.

Step 2 — Restart the gateway with the coding endpoint

Stop the gateway with Ctrl+C, then start it with the endpoints you need:

powershell

npm start -- --browser --coding

Leave out --browser if you only want files and coding. Then add a separate integration in the agent's MCP Integrations skill, following the MCP Integrations guide, with a Name such as Local_Coding (no spaces) and a human-readable description such as "Demo coding container on my PC". Use your tunnel address followed by /coding/mcp with Streamable HTTP.

New Integration draft (fictional, unsaved): the MCP endpoint URL and Transport.

Highlight 1: URL — the provider's MCP endpoint. A valid URL reveals Get Available Tools.
Highlight 2: Transport — Streamable HTTP or SSE, as required by the server.

Your address ends in /coding/mcp. Paste the same Bearer … value from npm run copy-key, select Get Available Tools, and tick only command_start, command_status and command_stop.

The Get Available Tools button and its prerequisite note: tools must be loaded before the integration can be created.

Highlight 1: Get Available Tools — appears once the URL is valid.
Highlight 2: Prerequisite note — tools must be loaded before you can create the integration.

The tool names in this screenshot come from a different example integration; your list should show only the three command_… tools.

Step 3 — First tasks: check the tools, then run the tests

Start with a harmless command that shows what is installed in the container:

"Use command_start to run node --version, then call command_status until it reports an exit code, and tell me the output and exit code."

Then ask the same for npm test. The demo contains one small test, so a successful run ends with exit code 0. Any other exit code means the command failed, and the output explains why.

How to read the results:

A job ID only shows the command started.
An active tool connection only shows the gateway answered.
Only an exit code from command_status shows how the command ended. Ask the agent to quote it with the last lines of output.

command_start accepts a timeout from 1 to 900 seconds (120 by default); when it runs out, the command is stopped. The starter runs at most two jobs at a time, and command_status returns only the last 100,000 characters of output. Job IDs are forgotten if the gateway restarts.

Step 4 — Preview the demo app

Ask the agent to start npm run dev exactly as written, as a job with a suitable timeout. In this demo it starts a small custom Node.js web server, not Vite, so do not add --host or other flags. Inside the container the app listens on 0.0.0.0:5173, so Docker can reach it. Docker publishes that port only to 127.0.0.1:8938 on your PC, as explained in the port publishing guide, so other devices cannot reach it.

The browser stays on your PC. Open this address yourself, or ask the dedicated browser to open it, and check that the page shows ACME LOCAL PREVIEW OK:

text

http://127.0.0.1:8938

When you are done, ask for command_stop and check that command_status shows the job ended. These ports are specific to this demo; your own app may use others. Nothing here deploys anything.

Review before anything leaves the workspace

When the agent says it is finished, check the files in workspace/demo yourself, run the tests, and read every change. Only then copy work elsewhere, commit, merge or deploy. A model saying "done" is not proof that a task finished.

For stuck jobs, a stopped container or preview problems, see Check, stop and recover local access.