Skip to content

quickstart-docker.md

Latest commit

 

History

History
236 lines (168 loc) · 7.09 KB

quickstart-docker.md

File metadata and controls

236 lines (168 loc) · 7.09 KB
Raw

Quick Start: Docker Appliance

Wright's Docker appliance is the mandatory turnkey path for a working API, web UI, Hermes integration, and engineering MCP catalog with no source build. It is published for every production release independently of the primary native Hermes path.

Wright is bring-your-own-AI. The image does not bundle an LLM, model weights, API key, hosted provider, or paid engineering backend. Configure an OpenAI-compatible endpoint with LLM_API_URL, LLM_API_KEY, and LLM_API_MODEL.

The base image also does not bundle MCP-specific host software such as FreeCAD, OpenSCAD, CalculiX, Blender, vendor CAD systems, license managers, or hardware drivers. Install and validate those only for the selected MCP server, following the clean-container process in MCP server testing process.

For deeper Hermes setup and provider configuration, see the official Hermes Agent docs and Hermes Desktop docs.

Published Image Path

For tagged alpha releases, Docker Hub and GHCR images use:

burhop/wright:<tag>
ghcr.io/burhop/wright:<tag>

Run a published image with your env file:

docker run --rm -p 127.0.0.1:8080:8000 --env-file docker/.env burhop/wright:<tag>

Source-build Compose commands below are for contributors. Third-party users should use a published immutable release tag.

Choose a Compose File

Path Command Host URL Notes
Minimal alpha appliance docker compose -f docker-compose.minimal.yml up -d --build http://localhost:8080 Recommended first run; Wright only.
MCP appliance flavor docker compose -f docker-compose.mcp.yml up -d --build http://localhost:8080 Experimental MCP bundle with separate volumes; see MCP Docker quickstart.
Full local stack docker compose up -d --build http://localhost:8000 Adds Jaeger tracing on localhost.
Test/dev stack docker compose -f docker-compose.test.yml up -d --build http://localhost:8080 Bind-mounts source for iteration.

See Docker image family for the managed standard, Linux amd64 MCP, Linux arm64 MCP, and Windows MCP runtime image profiles.

All checked-in compose files bind host ports to 127.0.0.1 by default. That is the safe local-first setting.

Configure Your LLM

Copy the template:

cp docker/.env.example docker/.env

Generate a unique Wright control-plane token and replace the placeholder in docker/.env:

openssl rand -hex 32

Set the values for your provider:

LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-key
LLM_API_MODEL=gpt-4.1-mini
UI_THEME=dark
WRIGHT_AUTH_MODE=enforced
WRIGHT_API_TOKEN=<generated-value>

Local OpenAI-compatible server example:

LLM_API_URL=http://host.docker.internal:8000/v1
LLM_API_KEY=not-needed
LLM_API_MODEL=local-model-name

On Linux, host.docker.internal may require:

docker run --add-host=host.docker.internal:host-gateway ...

or a compose extra_hosts entry if you create a local override file.

Hosted API style example:

LLM_API_URL=https://your-provider.example.com/v1
LLM_API_KEY=provider-token
LLM_API_MODEL=provider-model-id

Run the Appliance

Recommended first run:

docker compose -f docker-compose.minimal.yml up -d --build

Open:

http://localhost:8080

Check API health:

curl http://localhost:8080/api/health

Health is public. Other API routes require the token:

curl -H "Authorization: Bearer ${WRIGHT_API_TOKEN}" \
  http://localhost:8080/api/settings

See Local control-plane security for browser session cookies, origin configuration, remote binding, and compatibility rollback.

Check Hermes connection state through Wright:

curl http://localhost:8080/api/agent/health

The LLM status may be degraded until your configured endpoint is reachable from inside the container.

LAN Access

The committed compose files bind to localhost. For LAN demos, create a local override file that is not committed:

services:
  agent:
    ports:
      - "0.0.0.0:8080:8000"

Then run:

docker compose -f docker-compose.minimal.yml -f docker-compose.lan.yml up -d --build

Only expose Wright on trusted networks. Put it behind a reverse proxy with TLS and authentication for anything beyond a private demo network.

Persistent Data

The compose files use named volumes for:

  • /home/agent/workspace: user workspaces.
  • /home/agent/.local/share/wright: Wright SQLite and application state.
  • /home/agent/.config/wright: owner-only Wright configuration and fallback secrets.
  • /home/agent/.hermes: Hermes profiles and sessions.
  • /var/log: startup, supervisor, and application logs.

The image sets WRIGHT_WORKSPACES_DIR=/home/agent/workspace so newly created workspaces land in the mounted workspace volume.

The image root filesystem is read-only, Linux capabilities are dropped, and privilege escalation is disabled. System paths such as /etc, /opt, and /usr/local come from each new image rather than persisted volumes. Existing installations using the old broad volumes must follow Container hardening and migration.

Use docker compose down to stop containers while keeping data. Use docker compose down -v only when you want to delete the named volumes.

GB10, DGX Spark, and GPU Notes

The current public-alpha appliance is documented as a Linux container path, with linux/amd64 as the CI-smoked build target. linux/arm64, CUDA-enabled local AI workstations, NVIDIA Container Toolkit, and --gpus all are alpha follow-up work until the release workflow builds and smokes those variants.

If you run an LLM on the host GPU, keep the model server outside the Wright container and point LLM_API_URL at it. If a selected MCP server needs GPU passthrough, validate that server in a clean container and record the exact driver/toolkit assumptions in the MCP setup recipe.

MCP Validation Smoke

Use the catalog validation process for selected servers:

  1. Start from a clean Wright container.
  2. Read the selected MCP metadata and blocked/dependency status.
  3. Install only the selected server's package and testable free/open host dependencies.
  4. Do not add unsafe, proprietary, license-bound, hardware-bound, or credential-bound software to the base image just to make validation pass.
  5. Run initialize, notifications/initialized, tools/list, and one safe backend-touching probe before marking a server fully tested.

Problem logs belong in docs/mcp-catalog/testing-problem-log.md; reusable setup recipes belong in docs/mcp-catalog/mcp-server-setup-recipes.md.

Cleanup

Stop the minimal appliance:

docker compose -f docker-compose.minimal.yml down

Remove the appliance and its named volumes:

docker compose -f docker-compose.minimal.yml down -v

Remove the built local image when you no longer need it:

docker image rm wright:latest