Kroki can be configured using environment variables or Java system properties.

Server Listening

By default, Kroki will bind to all network interfaces ( on port 8000. You can change on which host and port the server will listen for incoming requests using KROKI_LISTEN:

KROKI_LISTEN= java -jar kroki-server.jar
java -DKROKI_LISTEN= -jar kroki-server.jar

With the above configuration, the server will bind to (i.e., loopback address) on port 1234.

If the port is unspecified, the server will listen on port 8000. If the host is unspecified, the server will use [::] (i.e., bind to all network interfaces and accept connections from both IPv6 or IPv4 hosts)

KROKI_LISTEN also accepts IPv6 enclosed within square brackets ([ and ]), for instance: KROKI_LISTEN=[2001:db8:1f70::999:de8:7648:6e8]:1234.

In addition, KROKI_LISTEN supports UNIX domain sockets by prefixing unix:// to a path, for example: KROKI_LISTEN=unix:///var/run/kroki.sock.

KROKI_PORT is deprecated and will be removed in the future.

We are deprecating this option because it conflicts with Kubernetes and Docker built-in environnement variables. For reference, Kubernetes will automatically set the environment variable {SERVICE_NAME}_PORT to tcp:// As you might have guessed, if you use KROKI as a service name, there’s going to be a problem! In fact, Kroki expects the value of KROKI_PORT to be an integer value.
To workaround this issue, until KROKI_PORT is removed, you can explicitly define the environment variable KROKI_PORT=8000.

If you were using a custom port (for instance, KROKI_PORT=1234), you can replace it by KROKI_LISTEN= (which is strictly equivalent).
If you want to bind to IPv4 and IPv6, you can use KROKI_LISTEN=:1234 or the longer form KROKI_LISTEN=[::]:1234.

If you want to learn about this deprecation, you can read:

Safe Mode

Kroki provides security levels that restrict access to files on the file system and on the network. Each level includes the restrictions enabled in the prior security level:

  • UNSAFE: disables any security features.

  • SAFE: Assume the diagram libraries secure mode request sanitization is sufficient.

  • SECURE: prevents attempts to read files from the file system or from the network.

By default, Kroki is running in SECURE mode.

Some diagram libraries allow referencing external entities by URL or accessing resources from the filesystem.

For example PlantUML allows the !import directive to pull fragments from the filesystem or a remote URL or the standard library.

It is the responsibility of the upstream codebases to ensure that they can be safely used without risk. Because Kroki does not perform code review of these services, our default setting is to be paranoid and block imports unless known safe. We encourage anyone running their own Kroki server to review the services security settings and select the security mode appropriate for their use case.

While running in SECURE mode, Kroki will prevent PlantUML from including files using the !include or !includeurl directive.

If you want to enable this feature, you can set the safe mode using the environment variable KROKI_SAFE_MODE:

java -DKROKI_SAFE_MODE=unsafe -jar kroki-server.jar
The value is case-insensitive, so both UNSAFE and unsafe will work.

It’s also possible to restrict the PlantUML !include directive using the following environment variables when running in SAFE mode:


The include path to set for PlantUML.


The name of a file that consists of a list of Java regular expressions for valid includes.


One regex to add to the include whitelist per environment variable. Search will stop at the first empty or undefined integer number.


Either false (default) or true. Determines if PlantUML will fetch !include directives that reference external URLs.For example, PlantUML allows the !import directive to pull fragments from the filesystem or a remote URL or the standard library.

Diagram Binary Paths

Kroki depends on external binaries to generate images. By default, Kroki will locate these binaries in the PATH environment variable.

In case you’ve installed a diagram library in a way where the executable is not in the PATH, you can override its location manually using an environment variable or a Java system property:


Path to svgbob binary


Path to erd binary


Path to dot binary


Path to nomnoml binary


Path to the bytefield-svg binary


Path to vega binary (it supports both Vega and Vega-Lite grammar)


Path to wavedrom binary

For instance, if dot is located at /path/to/dot, you can configure the path using a system property:

java -DKROKI_DOT_BIN_PATH=/path/to/dot -jar kroki-server.jar

Command Timeout

By default, Kroki will wait at most 5 seconds when calling a diagram binary to get a response. In most scenarios, 5 seconds is more than enough but, if needed, you can adjust the timeout using the KROKI_COMMAND_TIMEOUT environment variable.

The expected format is a duration with a time unit:















A few examples:

1 10 seconds
2 1 minute
3 4 seconds in milliseconds

Convert Timeout

By default, Kroki will wait at most 20 seconds when calling a Java library to convert a diagram. In most scenarios, 20 seconds is more than enough but, if needed, you can adjust the timeout using the KROKI_CONVERT_TIMEOUT environment variable.

The expected format is a duration with a time unit:















A few examples:

1 10 seconds
2 1 minute
3 4 seconds in milliseconds

You can also configure a specific timeout for each diagram library. Currently, only PlantUML supports this configuration:


Please note that this specific configuration will override KROKI_CONVERT_TIMEOUT. In other words, diagram library timeouts (for instance, KROKI_PLANTUML_CONVERT_TIMEOUT) have higher precedence than KROKI_CONVERT_TIMEOUT.

Companion Container Host and Port

You can configure the host and port on which every companion container will be listening:


Host of the BlockDiag container (default:


Port of the BlockDiag container (default: 8001).


Host of the Mermaid container (default:


Port of the Mermaid container (default: 8002).


Host of the BPMN container (default:


Port of the BPMN container (default: 8003).


Host of the Excalidraw container (default:


Port of the Excalidraw container (default: 8004).

If you are using the default docker-compose.yaml file you can rely on the default values.

Max URI length

Some diagrams, like Excalidraw, have verbose textual descriptions that will produce long URI. If the URI requested by the client is longer than the server is willing to interpret, the server will return a 414 (Request-URI Too Long) response status code. The default max URI length in Vert.x is 4096. You can update this default value by setting KROKI_MAX_URI_LENGTH environment variable.

Keep in mind that browsers also have a URI limit on <img> tags. Most modern browsers support a URI length greater than 64000 on <img> tags but this value is probably a bit excessive. We recommend to use a maximum length that’s not greater than 8192 and not greater than 5120 if you are supporting IE 11.

Enabling SSL on the server

By default, SSL/TLS is not enabled on the server but you can enable it by setting KROKI_SSL environment variable to true.

When SSL is enabled, you must provide the certificate and the private key values as PEM format using KROKI_SSL_KEY and KROKI_SSL_CERT environment variables.

You can generate a self-signed SSL certificate and private key as PEM format using openssl:

openssl req -nodes -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

The above command will generate two files, cert.pem containing the certificate and key.pem containing the private key.

You can then write the KROKI_SSL_CERT environment variable with the contents of the cert.pem file and the KROKI_SSL_KEY environment variable with the contents of the key.pem to an environment-file:

cat cert.pem | tr -d '\n' | sed 's/^/KROKI_SSL_CERT=/' >> .env
echo >> .env
cat key.pem | tr -d '\n' | sed 's/^/KROKI_SSL_KEY=/' >> .env

The container can then be started with the environment variables set accordingly:

Using docker
docker run -p8000:8000 -e KROKI_SSL=true --env-file=.env yuzutech/kroki
Using podman
podman run -p8000:8000 -e KROKI_SSL=true --env-file=.env yuzutech/kroki

If SSL is enabled, both KROKI_SSL_KEY and KROKI_SSL_CERT must be configured.