CodeCombat: self-hosting the open source coding game

What CodeCombat solves, and who the repository is actually for

CodeCombat is a game in which the player writes code to control a character, and the README describes it as "a multiplayer programming game for learning how to code." The repository is the source of that game, not a library you import into another application. That distinction decides who should care about it. If you are an engineer who wants to embed a coding exercise into your own product, the game engine is not packaged for that; the README points instead to a partner API for SSO, user management and progress data, with docs at api-docs.codecombat.com and SDKs in a separate repository. The self-hosted code is for people who want to run or modify the game itself.

The README frames the project as "both a startup and a community project," and package.json names four contributors. That matters because the same repository serves a commercial service and an open source community, and the two do not have the same rights over content. The code is MIT. The art and music are CC-BY. The levels are neither. Anyone evaluating this project for a school, a bootcamp or a product should read LICENSE-LEVELS.md before assuming that a clone of the repository is a clone of the course.

The architecture visible in the repository layout

The top level shows a Node server with a separate client build. index.js and server.js sit next to server_config.js and server_setup.js, and there is a dedicated nodemon.json for development restarts. The client is bundled by webpack, and the repository does not hide that: webpack.config.js, webpack.base.config.js, webpack.development.config.js, webpack.production.config.js, webpack.dev_container.config.js, webpack.karma.config.js and webpack.analyzer.config.js all exist as separate files. runWebpack.js is the entry point the build script calls.

Two directories, app/ and ozaria/, are worth noting. Ozaria appears to be a second product built from the same codebase, and the Makefile confirms it with parallel targets: dev and dev-ozaria, proxy and proxy-ozaria, and a find-coco-ozar-diffs target that ranks .coco and .ozar file pairs by how much they differ. That is an unusual amount of tooling for a fork, and it tells you the two products share source rather than diverging cleanly.

Testing is browser-based. package.json runs Karma with a single run and dot reporters, and the test-ubuntu script starts Xvfb on display :99 and runs Karma against Firefox. The test command passes NODE_OPTIONS with a 4096 MB heap, which is a signal about how much memory the build expects. There is also a bower.json and a bower install step in the build script, so the dependency story is not purely npm.

Installing CodeCombat with Docker Compose

The repository ships a docker-compose.yml with one service named proxy. It builds from development/docker/Dockerfile, mounts the repository at /coco, keeps node_modules out of the bind mount with an anonymous volume, and maps host port 7777 to container port 3000. The container command runs npm install, then npm run build, then npm run proxy.

The compose file itself is short enough to read in full. The port mapping is the part to notice: 7777 on your machine, 3000 inside the container.

services:
  proxy:
    build:
      context: .
      dockerfile: ./development/docker/Dockerfile
    command: bash -c "npm install && npm run build && npm run proxy"
    volumes:
      - .:/coco
      - /coco/node_modules
    environment:
      DEV_CONTAINER: 1
    ports:
      - 7777:3000

Because the build runs inside the container on first start, expect a long first boot. The build script in package.json is bower install, then npm run build-aether, then node ./runWebpack.js with NODE_OPTIONS set to an 8192 MB heap. setup-aether.js is what build-aether invokes. If the container exits during the build, memory is the first thing to check, since the script explicitly raises the heap limit.

Once the proxy is up, the README directs developers to the Archmage developer wiki for the setup guide and further documentation. That wiki, not the README, is where the dev setup detail lives. The README's own install guidance is essentially that pointer.

The Makefile targets you will actually use

The Makefile is the clearest map of day-to-day work. Running make with no arguments prints the help target, which greps the file for targets carrying a ## comment and formats them. The development targets are dev and dev-ozaria for webpack watch mode, proxy and proxy-ozaria for the local proxy server, and build for the full production build.

make help
make dev
make proxy

The Makefile documents the proxy ports in its own comments: port 3000 for CodeCombat and port 3001 for Ozaria. That is worth flagging because the Docker Compose service maps container port 3000 to host port 7777, so the port you open depends on whether you are running through Compose or through make directly.

There is also a set of internationalization targets that most projects do not have. copy-i18n runs scripts/copy-i18n-tags.js to rewrite locale files to match the structure of en.js and propagate change markers. check-i18n runs scripts/check-long-i18n.js to flag translations that are suspiciously longer than the English originals. generate-rot13 runs scripts/generateRot13Locale.js to produce a ROT13 locale for debugging. If you plan to add a language, check-i18n is the target that will catch a layout problem before a player does.

Where CodeCombat is the wrong tool

The licence boundary is the first limitation, and it is not a subtle one. LICENSE-LEVELS.md is a top-level file whose purpose is to state that the levels on codecombat.com are not open source. Cloning the repository gives you the engine, the client, the build system and the art under CC-BY. It does not give you the levels under an open source licence. A team that wants a self-hosted coding course cannot assume the content comes with open terms.

The second constraint is operational. This is a large JavaScript application with a bower install in the build path, multiple webpack configurations, a browser test suite that needs Xvfb and Firefox on Linux, and build steps that request 8 GB of heap. That is a heavy footprint for anyone who just wants to try the game. The README's own answer to "how do I run this" is a pointer to a wiki page, which means the repository is not designed as a five-minute local install.

Third, the multiplayer and account features imply a backend and data store that the README does not describe. The README documents an API for SSO, user management and progress data, and notes that client credentials are required and that you should get in touch with the team for a use case. That is a gated integration, not a self-service one. If your plan depends on pulling progress data programmatically, the simplest documented path is fetching a user stats URL, and anything beyond that goes through the partner process.

Alternatives and how the approach differs

CodinGame is the closest comparison in kind: a game where you write code to solve puzzles and compete. The difference in approach is that CodeCombat wraps the exercise in a character-driven campaign with levels, progression and a story, while CodinGame is organized around standalone challenges and ranked contests. If you want a structured course that a beginner follows from start to finish, the campaign shape matters. If you want short competitive problems, the challenge shape matters. The repository question is separate: CodeCombat publishes its game source, so you can read and modify the engine, which is a different level of access than using a hosted platform.

For a team that only wants to embed exercises rather than run a game, the partner API is the relevant surface, and the README points to api-docs.codecombat.com and the codecombat-api SDK repository. That is a narrower commitment than self-hosting the full application, and it avoids the bower and webpack build entirely. The trade-off is that it depends on the hosted service and on obtaining client credentials.

Licence, maintenance and upgrade cost

The repository is MIT for the code and CC-BY for the art and music, per the README and the LICENSE file. Contributors are asked to sign a contributor license agreement at codecombat.com/cla before pull requests can be accepted, which is a normal arrangement for a project that also runs a commercial service. The levels are carved out separately in LICENSE-LEVELS.md. None of this is legal advice; if you plan to redistribute art, music or content, read the licence files and the legal page yourself.

The repository is not archived, and the last push was on 2026-11-02, so this is a codebase receiving changes. That does not tell you anything about release cadence: the repository has no published releases, and package.json pins the version at 1.0.0, which is not a meaningful signal about stability in a project of this age. Upgrades are the real cost. With bower still in the build path, several webpack configurations, a separate aether build step, and two products sharing one tree, tracking upstream means re-running a build that already asks for 8 GB of heap. Budget for that rather than treating it as a git pull.

Editorial conclusion

Adopt the repository if you want to run the CodeCombat game engine yourself, study how a large JavaScript game is structured, or build a partner integration through the documented API. Do not adopt it if your goal is to reuse the level content: LICENSE-LEVELS.md states the levels on codecombat.com are not open source, so a self-hosted instance does not give you the curriculum under open terms. Verify first that npm install, npm run build and the proxy at port 7777 complete on your machine, and read LICENSE-LEVELS.md alongside LICENSE before you plan anything around the content.

Frequently asked questions

Official sources

1. codecombat/codecombat on GitHub
2. Issues
3. License: MIT
4. Project website
5. README