nb serve

nb serve 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

nb serve [flags]

Flags

Flag	Description	Default
--port <number>	Server port	27247
--config <path>	Config file path	Auto-resolved (see config resolution)
--workdir <dir>	Working directory	~/.nimblebrain
--model <name>	Override default model	From config
--debug	Verbose logging	Off

Starting the server

nb serve

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

The server listens on port 27247 by default. Override with --port:

nb serve --port 8080

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

PORT=8080 nb serve

Note

The PORT environment variable takes precedence over the default but is overridden by --port.

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 nb serve:

export ANTHROPIC_API_KEY=sk-ant-api03-...
export NB_API_KEY=your-secret-api-key-here
export ALLOWED_ORIGINS=https://app.example.com

nb serve --port 27247

The NB_API_KEY protects the API with Bearer token authentication. The ALLOWED_ORIGINS controls CORS. See the Authentication and Security docs for details.

Debug mode

Enable verbose logging to see every event the runtime processes:

nb serve --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:

nb serve --config /etc/nimblebrain/nimblebrain.json

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

nb serve --workdir /opt/nimblebrain

Related commands

• nb dev — development mode with file watching and HMR
• nb status — check workspace health
• nb reload — hot-reload config on a running server
• CLI Overview — global flags and config resolution