Skip to content
gemba

Beads-only Docker quickstart

Beads-only Docker quickstart

Use these containers when you want to explore Gemba as a Beads viewer and manager without setting up a project, GitHub, or agent orchestration. The containers run the browser UI, the Go server, and the Beads adaptor together.

What you get

ModeImageBest forWrites
Quickstart sample projectsoflo1/gemba-core-quickstart:latestFirst look, demos, screenshots, learning the UIWritable by default
Beads-onlysoflo1/gemba-core:latestMounting your own project worktree or using a Dolt URLWritable unless the source denies writes
Beads-read-onlyEither image with GEMBA_BEADS_READ_ONLY=trueReview, audits, sharing a safe UI over real workBlocked by Gemba before the adaptor

The UI starts in Beads-only mode with Beads surfaces enabled: the Board status columns, Refine table / hierarchy / swimlane views, sort controls, milestone / epic / bead wrappers, details in the right-hand panel, Beads health, Beads history, and the Graph view. Board state comes directly from Beads without dispatching agents. Agent sessions, dispatch, review, and escalation surfaces are hidden because no orchestration plane is active.

Major functions

Beads-only mode keeps the surfaces that are useful for viewing and managing Beads, and hides the surfaces that require agent orchestration.

SurfaceWhat it does in Beads-only mode
BoardStarts as a status board with Ready / In Progress / Done columns from Beads state. Use the Order control for modified/created/edited/ID sorting and the Milestone / Epic selectors to focus on a wrapper’s children. In writable mode you can create, edit, delete, and drag beads between states without dispatching agents.
RefineShows parked Deferred work in a dense table for grooming. Switch to Hierarchy for milestone -> epic -> bead structure or Swimlanes for grouped planning. Use it to improve titles, descriptions, priority, wrappers, labels, and other planning fields before work is staged or reviewed elsewhere.
GraphShows dependency and relationship structure. Use the funnel menu to filter by milestone, epic scope, search, state, or kind; switch between item and epic aggregation; and inspect cycles or critical path signals.
Right-hand panel detailsOpens bead, epic, milestone, and decision details without leaving the current view. Writable mode exposes edit controls; read-only mode keeps inspection available and blocks mutations.
StatusShows the active Beads mode, current database/source, remote health, read-only posture, and repair/setup actions when the source supports them.
Beads historyRenders the JSONL session manifest in plain English so users can see create, edit, delete, and state-change events from the current session.

Authentication

The containers bind 0.0.0.0:7666 inside Docker, so token auth is on by default.

On startup Gemba prints two credentials to the container log:

  • A primary bearer token. It is printed only when the token is first created and is persisted as a hash in the /data volume.
  • A one-time browser login URL on every server start:
Open:   http://127.0.0.1:7666/#gemba-bootstrap=...

Use the one-time URL first. The browser exchanges the fragment token for a session cookie and removes the fragment from the address bar. If the link expires, open http://127.0.0.1:7666 and paste the primary token into the unlock prompt.

If you change the host port mapping, for example -p 7777:7666, edit the printed URL to use the host port: http://127.0.0.1:7777/....

Quickstart sample project

This is the fastest way to see a populated board.

  1. Pull the image:

    Terminal window
    docker pull soflo1/gemba-core-quickstart:latest

  2. Start the container:

    Terminal window
    docker run --rm -it \
      --name gemba-beads-demo \
      -p 7666:7666 \
      -v gemba-quickstart-data:/data \
      soflo1/gemba-core-quickstart:latest

  3. Copy the printed Open: URL from the terminal and open it in your browser.

  4. Explore the UI:

    • Start on the Board to see Ready / In Progress / Done state columns.
    • Open a bead, epic, or milestone to inspect its right-hand details.
    • Open Refine to groom the seeded Deferred items in a dense table.
    • Switch Refine to Hierarchy to see milestone -> epic -> bead structure.
    • Switch Refine to Swimlanes when grouped planning is more useful.
    • Click Graph in the sidebar to inspect relationships and dependencies; use the funnel menu to filter by milestone, epic scope, search, state, or kind.
    • Open the Status tab to verify Beads health and current mode.
    • Create or edit a bead; the Beads history tab records the action.

The seeded project is stored in the gemba-quickstart-data Docker volume. Reusing the same volume keeps your edits. To reset the demo:

Terminal window
docker volume rm gemba-quickstart-data

Beads-only with your own local project worktree

Use the standard image when you already have a directory containing a .beads database.

  1. Pull the image:

    Terminal window
    docker pull soflo1/gemba-core:latest

  2. Start from the project worktree directory:

    Terminal window
    cd /path/to/your/beads-worktree
    

    docker run --rm -it \
      --name gemba-beads \
      -p 7666:7666 \
      -v gemba-data:/data \
      -v "$PWD:/work" \
      -e GEMBA_BEADS_ONLY=true \
      -e GEMBA_PROJECT_DIR=/work \
      soflo1/gemba-core:latest

  3. Open the printed Open: URL.

This mode is writable by default. Creating, editing, deleting, and moving beads writes to the mounted Beads database and appends entries to the Beads history ledger.

Beads-only with a Dolt URL

If your Beads database is served by Dolt/MySQL, point Gemba at the URL. On Docker Desktop, host.docker.internal reaches a service running on the host machine.

Terminal window
docker run --rm -it \
  --name gemba-beads-url \
  -p 7666:7666 \
  -v gemba-data:/data \
  -e GEMBA_BEADS_ONLY=true \
  -e GEMBA_BEADS_URL='mysql://root@host.docker.internal:3307/gemba' \
  soflo1/gemba-core:latest

URL mode is not automatically read-only. It is writable when the Dolt server and credentials allow writes.

Beads-read-only mode

Add GEMBA_BEADS_READ_ONLY=true when you want a safe inspection UI. Gemba shows a Beads-read-only status pill, hides write affordances where applicable, and rejects mutation requests before they reach Beads or Dolt.

Read-only quickstart sample:

Terminal window
docker run --rm -it \
  --name gemba-beads-demo-ro \
  -p 7666:7666 \
  -v gemba-quickstart-data:/data \
  -e GEMBA_BEADS_READ_ONLY=true \
  soflo1/gemba-core-quickstart:latest

Read-only mounted worktree:

Terminal window
cd /path/to/your/beads-worktree


docker run --rm -it \
  --name gemba-beads-ro \
  -p 7666:7666 \
  -v gemba-data:/data \
  -v "$PWD:/work" \
  -e GEMBA_BEADS_ONLY=true \
  -e GEMBA_BEADS_READ_ONLY=true \
  -e GEMBA_PROJECT_DIR=/work \
  soflo1/gemba-core:latest

Read-only Dolt URL:

Terminal window
docker run --rm -it \
  --name gemba-beads-url-ro \
  -p 7666:7666 \
  -v gemba-data:/data \
  -e GEMBA_BEADS_ONLY=true \
  -e GEMBA_BEADS_READ_ONLY=true \
  -e GEMBA_BEADS_URL='mysql://reader@host.docker.internal:3307/gemba' \
  soflo1/gemba-core:latest

For defense in depth, prefer read-only Dolt credentials for shared review deployments. Gemba still enforces read-only mode even if the URL credentials could write.

Useful commands

Show the one-time URL again after starting in detached mode:

Terminal window
docker logs gemba-beads-demo

Run detached:

Terminal window
docker run -d \
  --name gemba-beads-demo \
  -p 7666:7666 \
  -v gemba-quickstart-data:/data \
  soflo1/gemba-core-quickstart:latest
docker logs gemba-beads-demo

Stop a detached container:

Terminal window
docker stop gemba-beads-demo

Use a different host port:

Terminal window
docker run --rm -it \
  -p 7777:7666 \
  -v gemba-quickstart-data:/data \
  soflo1/gemba-core-quickstart:latest

Then open http://127.0.0.1:7777 or replace :7666 with :7777 in the printed one-time URL.

Troubleshooting

  • 401 in the browser: use the printed Open: URL or paste the primary token at the unlock prompt. If the container is detached, run docker logs <container-name>.
  • No sample data: remove the demo volume and restart: docker volume rm gemba-quickstart-data.
  • Mounted worktree is empty: make sure you started Docker from the directory that contains .beads, or set GEMBA_PROJECT_DIR to the container path where that directory is mounted.
  • Dolt URL cannot connect: from Docker Desktop use host.docker.internal for host services; on Linux use the host IP or run the Dolt server on a Docker network shared with Gemba.
  • Edits unexpectedly succeed in URL mode: URL mode is writable by default. Set GEMBA_BEADS_READ_ONLY=true or use read-only Dolt credentials.