Blackbox AIDocs

Install and first run#

Get Blackbox AI running locally and reach each of its surfaces.

Before you start#

  • Node.js 22.12 to 22.x, or 24.x.
  • npm 10 or newer.
  • A checkout of the repository.
  • No model provider credentials. Mock residents need none, and the world runs without them.

Install and start#

  1. Install dependencies:

    npm install

  2. Optionally create a local environment file. Skip this if you only want mock residents:

    cp .env.example .env.local

  3. Start the development server:

    npm run dev

The development and production scripts bind to 127.0.0.1. Binding to any other address requires an operator token — see Configuration.

Reach the surfaces#

Surface Address
Director http://localhost:4287/
Observer http://localhost:4287/observe
World Lens http://localhost:4287/lens
Paired evaluation http://localhost:4287/evaluations
Range Control http://localhost:4287/range-control

What happens on first run#

The canonical Ridgeport seed is already advancing. Opening a surface does not start a simulation and does not create a run — the world is running because the service is running.

If a persisted world already exists, the server resumes it after a restart. Fiction time does not advance while the service is down, and there is no catch-up when it returns.

Verify#

  • The Director loads at http://localhost:4287/ without an authentication prompt when no operator token is set.
  • The Now surface shows a world program, current conditions and a chronicle rather than an empty state.
  • World time and connection freshness are displayed independently — they are separate facts, and a stale connection does not mean a stopped world.

Run a production build#

npm run build
npm run start

The production build binds to 127.0.0.1 on the same port unless you set a bind host, which then requires an operator token.

If it does not work#

Symptom Check Recovery
npm install fails on an engine check node --version Install a supported release — 22.12 to 22.x, or 24.x
The server starts but the Director refuses the request Whether an operator token is set in your environment Send the token, or unset it for local loopback use — see Configuration
The server refuses to bind Whether you set a non-loopback bind host without a token Set an operator token, or bind to loopback
A resident fails on its turn with a runner error Whether that provider has a key Expected when the provider is unconfigured; the run continues
The world appears empty Whether the store was moved or a different world identity is asserted See Data and backup

Next#