Skip to main content
Version: Current

Installation

Nussknacker comes as a Docker Compose bundle that runs the Designer and everything it needs on a single host. Streaming scenarios run on a Flink MiniCluster inside the Designer and Request-Response scenarios on the embedded Lite engine, so no Flink cluster or Kubernetes is needed.

What you need​

  • Docker with the Compose plugin, and about 7 GB of memory available to it
  • Linux or macOS; on Windows, run the commands in a WSL terminal
  • the registry credentials and the license key you received from us; if you do not have them yet, contact us

Install​

Log in to our registry, unpack the bundle and start it:

docker login registry.nussknacker.io
docker run --rm --pull always -e NU_LICENSE_KEY='<license key>' registry.nussknacker.io/nussknacker/nussknacker-installation:2.3 | tar -x
cd nussknacker && ./start.sh

Keep the license key in single quotes, so that the shell passes it unchanged. 2.3 is the release line: the tag moves to each new build of 2.3 we publish. To install one exact build, use its full tag instead, for example nussknacker-installation:2.3-20261016-4eda6207.

The Designer is then at http://localhost:8090, with the default admin / admin account.

On a fresh installation started from a terminal, ./start.sh asks whether to import the example scenarios. ./start.sh --with-examples imports them without asking, ./start.sh --no-examples never asks, and ./start.sh --help lists the options.

Example scenarios​

The bundle ships two sets of scenarios. Every scenario carries sticky notes that walk through it on the canvas, descriptions on its nodes, labels and saved test cases with the external calls mocked.

cold-chain - the place to start: a stream, a store and the endpoints that read it, in seven scenarios: simulate-sensors publishes temperature readings of 30 pallets; track-shipments looks each SKU's limit up in a Decision Table, sums the excess per pallet over a rolling hour, keeps the pallet's state in the Key-Value Store shipment_state and, for a fresh reading far over the limit, fetches the pallet's owner and carrier from pallet-details (a Request-Response scenario registered as an OpenAPI enricher) and raises an alert through the send-alert fragment and the cold-chain-alerts topic; check-shipment, assess-shipment (the QA verdict: USE / QUARANTINE / DISCARD) and list-shipments answer from the store without touching the stream. Outcomes: docker compose logs -f designer | grep COLD_CHAIN_ALERT, the cold-chain-alerts topic in the Topics tab, and the endpoints under http://localhost:8191/scenario/<name>.

pharmacovigilance - adverse event triage with an LLM: simulate-ae-reports publishes synthetic reports, stream-triage-adverse-events classifies each one with invokeLLM behind an output schema (seriousness, MedDRA class, expedited rule), routes it to a team with a Decision Table and publishes the triaged case to routed-ae-cases. This set is imported but not deployed: the import registers the LLM integration demo-llm as a placeholder - an OpenAI-compatible server on your machine (Ollama at http://host.docker.internal:11434/v1, model llama3.1, no key). Configure the AI integration you use in the Configurator (Anthropic, OpenAI, Gemini, Mistral, Bedrock, NVIDIA or any OpenAI-compatible server), point the classify node at it, then deploy both scenarios; with Ollama and llama3.1 on the machine the placeholder works as it is. A hosted model bills every classification.

scenarios/import.sh imports every set whose prerequisites are met; EXAMPLE_SETS="cold-chain" scenarios/import.sh picks sets, EXAMPLES_DEPLOY=false imports without deploying, and scenarios/README.md in the bundle describes every scenario.

The CLI and AI agents​

The Designer image carries the Nussknacker CLI, and ./nu-cli in the bundle runs it in the Designer container against this installation - nothing to download or install:

./nu-cli whoami
./nu-cli scenario list

./start.sh signs the CLI in as admin with the password from .env; if whoami answers Not authenticated (401), run ./nu-cli login --basic-user admin --password-env NU_PASSWORD once. The CLI keeps its configuration on the Designer's storage volume, so the sign-in survives a restart or an upgrade. Every command has --help; the CLI manual covers reading, creating, changing and deploying scenarios and sending messages to topics. On Windows run ./nu-cli in a WSL terminal, like ./start.sh.

To let an AI agent work with the Designer, register the CLI as an MCP server with the agent's client:

./nu-cli mcp --allow-write --allow-deploy

Run in a terminal, this prints the entry to register (for Claude Code the claude mcp add command, for clients configured with JSON the server object); the client then starts ./nu-cli mcp itself. The agent gets the Designer's own scenario tools and, through list_skills and get_skill, the Designer's playbooks for building scenarios - have it read those first. Without --allow-write the server is read-only; --allow-deploy also lets it deploy, cancel and send messages.

AGENTS.md in the bundle is written for the agent (and for you): what runs on which port, how to sign in, the CLI and the REST routes, where to start. Point the agent at it, or at the bundle directory, and it has what it needs without the Nussknacker sources.

License key​

The key is stored in the .env file in the nussknacker directory. Without it, the Designer runs with the basic components only and every other component is shown locked. To add or replace the key later, set NU_LICENSE_KEY in .env (copy .env.example if there is no .env yet) and run ./start.sh again.

AI assistant​

The assistant in the Designer needs a model and an API key of an AI provider. Without them it only answers that it is not configured. Set ASSISTANT_API_KEY in .env, and ASSISTANT_LLM_PROVIDER (anthropic, open-ai or mistral) and ASSISTANT_LLM_MODEL (the model's id at that provider, for example claude-sonnet-4-6, gpt-4.1-mini or mistral-medium-latest; it has to support tool calls) when the defaults from .env.example are not what you want, then run ./start.sh again. A key the provider rejects shows in the chat as "The AI provider rejected the request. Check the AI configuration or your AI provider." The full configuration is described in Designer configuration.

Stop and upgrade​

./stop.sh stops the stack and keeps the data, ./stop-and-clean.sh removes the data as well.

The bundle follows its release line. When a newer build of it is published, ./start.sh says so, and ./start.sh --upgrade pulls it and restarts the Designer, which redeploys its scenarios. To stay on one build, or to go back to it, set NUSSKNACKER_VERSION and ASSISTANT_EMBEDDINGS_VERSION in .env; .env.example names the build the bundle came with.

The bundle's own files - docker-compose.yml, start.sh, the configuration, the example scenarios - change only with a new bundle: run the same docker run command in the parent directory of nussknacker, without -e NU_LICENSE_KEY, and then ./start.sh. The data and .env are kept, but the other files are overwritten, so keep a copy of the ones you edited. The CLI's sign-in is kept as well: it lives on the Designer's storage volume.

Configuration​

The bundle runs as it is. .env.example lists the settings worth changing, such as passwords, tokens and host ports, and README.md in the bundle describes the rest. Change the gateway token and the publisher password before you give anyone else access to the stack.