Skip to content

Run FCC locally with Docker in 5 minutes

Audience: Beginners who want to try FCC without installing Python, Node, or any dependencies.

Prerequisites: Docker 24+ installed and running.

Step 1: Get the code

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

Step 2: Build the images

make docker-build

This builds four images:

  • fcc-backend — the WebSocket bridge that simulations talk to
  • fcc-frontend — the React UI
  • fcc-streamlit — interactive Streamlit dashboards
  • fcc-jupyter — JupyterLab with all 23 example notebooks

First build takes about 5 minutes; cached rebuilds are seconds.

Step 3: Start the stack

make docker-up

Wait ~30 seconds for the backend to become healthy, then open:

URL What it is
http://localhost:8080 The React frontend
http://localhost:8501 A Streamlit app (persona_explorer.py by default)
http://localhost:8888 JupyterLab with all 23 notebooks
http://localhost:8765/health Backend health endpoint (returns JSON)

Step 4: Try the Streamlit explorer

Open http://localhost:8501. You'll see the Persona Explorer:

  1. Browse all 147 personas grouped by category
  2. Click any persona to see its full R.I.S.C.E.A.R. specification
  3. Filter by tag, type, or champion role

To run a different Streamlit app, restart with the app name:

make docker-down
STREAMLIT_APP=kg_explorer.py make docker-up

Step 5: Try a notebook

Open http://localhost:8888 and click 01_fcc_fundamentals.ipynb. The notebook walks you through:

  • Loading the persona registry
  • Building a simple workflow graph
  • Running a deterministic simulation

By default the simulation uses the mock AI provider so it works without any API keys. To use a real LLM, see the providers docs.

Step 6: Stop the stack

make docker-down

This stops and removes the containers but keeps the images so the next make docker-up is instant.

What's next?

Troubleshooting

docker: command not found
Install Docker from https://docs.docker.com/get-docker/.
port is already allocated
Another process is using port 8080, 8501, 8765, or 8888. Stop it or change the host ports in docker-compose.yml.
make: command not found
Install make (Linux: sudo apt install make, Mac: xcode-select --install, Windows: use WSL2).
Images won't build
Check the build output for the failing layer. Common causes: stale Docker cache (docker builder prune), insufficient disk (need ~3 GB free), or network issues fetching Python/Node packages.
Backend stays unhealthy
Check logs: docker compose logs backend. If you see Python import errors, the [full] optional deps may have failed to install — file an issue at https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/issues.