Running the server

bun run start launches the NimbleBrain runtime and starts an HTTP API server. This is the production entry point — it boots the agent engine, loads all configured bundles, and listens for HTTP requests.

Usage

bun run start                            # simple case
bun run src/cli/index.ts serve [flags]   # explicit form (config / production)

Flags

Flag	Description	Default
--port <number>	Server port	27247
--config <path>	Config file path	Auto-resolved (see config resolution)
--model <name>	Override default model	From config
--debug	Verbose logging	Off

Starting the server

bun run start

[nimblebrain] Starting runtime...
[nimblebrain] Runtime ready.

The server listens on port 27247 by default. Override with --port (bun forwards args after the script name):

bun run start --port 8080

You can also set the port via the PORT environment variable:

PORT=8080 bun run start

Note

The PORT environment variable takes precedence over --port. If both are set, PORT wins.

What happens at startup

1. The config file is loaded and validated
2. The runtime initializes — loading bundles, skills, and model configuration
3. Structured logging is disabled unless --debug is set (keeps stdout/stderr clean for production)
4. The HTTP server starts listening on the configured port

Production deployment

For production, set the required environment variables and run the explicit serve form:

export ANTHROPIC_API_KEY=sk-ant-api03-...
export ALLOWED_ORIGINS=https://app.example.com

bun run src/cli/index.ts serve --port 27247

The deployed container image runs exactly bun run src/cli/index.ts serve.

Authentication is configured through instance.json (the oidc or workos adapter), not an environment variable — there is no NB_API_KEY. ALLOWED_ORIGINS controls CORS. See Connect via MCP and Security for details.

Debug mode

Enable verbose logging to see every event the runtime processes:

bun run start --debug

In debug mode, each event is dumped as JSON to stderr. Without --debug, the server runs quietly — only startup and shutdown messages are printed.

Using a custom config

Point to a specific config file with the explicit serve form:

bun run src/cli/index.ts serve --config /etc/nimblebrain/nimblebrain.json

Or set a custom working directory with NB_WORK_DIR (the server looks for nimblebrain.json inside it):

NB_WORK_DIR=/opt/nimblebrain bun run src/cli/index.ts serve

Related commands

• Dev mode — development mode with file watching and HMR
• CLI Overview — global flags and config resolution