Get started

ui

Open the lesson UI in your browser – the lesson, an editor, the tests and the sensei together.

npx dojofoo [options]

Run in a terminal, npx dojofoo starts a local server for the UI and opens it. In a folder that isn't set up yet, it first runs install. Stopping the command stops the server; your courses and sessions stay indexed in ~/.dojofoo/dojofoo.db. This is how you learn with dojofoo.

Without a terminal – in a script, CI or a pipe – npx dojofoo prints its help instead. Scripts and agents open the UI with npx dojofoo ui [options], which takes the same options and never runs the setup.

Options

OptionDescription
--backgroundKeep the server running after the command exits
--no-openPrint the URL without opening a browser
--authoringOpen the authoring UI for the course in this folder
--port <port>The localhost port (default 4567)
--no-portlessSkip Portless and use localhost
--name <name>The Portless subdomain (default dojo)
--tld <tld>The UI hostname suffix (default localhost), e.g. test
VariableSame as
DOJO_UI_PORT--port. A PORT variable takes precedence over it.
DOJO_UI_DISABLE_PORTLESS=1--no-portless
DOJO_UI_NAME--name

Examples

npx dojofoo                            # open the UI
npx dojofoo --background --no-open     # keep it running, quietly
npx dojofoo --no-portless --port 4570  # localhost, on another port

Agent controls

Agents drive the open UI through the ui command:

CommandDoes
npx dojofoo ui [options]Open the UI from a script or agent, with the options above
npx dojofoo ui promptShow a structured prompt in the current lesson UI
npx dojofoo ui --skillPrint the agent instructions for controlling the UI

The address

With Portless installed, the UI uses dojo.localhost, even when your shared proxy uses another domain for other applications. The address follows the proxy's HTTP or HTTPS configuration; with its default HTTPS configuration:

https://dojo.localhost

Without it, or when it fails, the UI runs at http://localhost:4567. Both serve the same courses, progress and sessions. To set Portless up:

npm install -g portless

Portless handles proxy startup. Dojofoo does not run a certificate-trust step during package installation. To use plain HTTP, start Portless with portless proxy start --no-tls before launching the UI. Changing an already running shared proxy affects its other applications.

If the address stops working:

portless doctor      # check its health
portless hosts sync  # repair .localhost resolution, e.g. in Safari
portless prune       # clear routes left by crashed processes

From this repository, build once with pnpm ui:build, then use pnpm ui. The script launches the same CLI and hostname as npx dojofoo.

The sensei's agent

In the UI the sensei runs on OpenCode by default. To use Codex, Cursor, Grok or FX instead, set it for one project in .dojo/runtimes.json, or for all of them in ~/.dojofoo/runtimes.json:

{ "lesson": "codex" }

The DOJOFOO_LESSON_HARNESS variable overrides both for one run. Pick the model in the UI.

Edit on GitHub