jina pea


This command is hidden unless you set JINA_FULL_CLI

Start a Jina pea. You should rarely use this directly unless you are doing low-level orchestration

usage: jina pea [-h] [--name] [--description] [--log-config] [--quiet]
                [--quiet-error] [--port-ctrl] [--ctrl-with-ipc]
                [--timeout-ctrl] [--ssh-server] [--ssh-keyfile]
                [--ssh-password] [--uses] [--py-modules [PATH [PATH ...]]]
                [--port-in] [--port-out] [--host-in] [--host-out]
                [--socket-in {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 8 more choices}]
                [--socket-out {PULL_BIND, PULL_CONNECT, PUSH_BIND, PUSH_CONNECT ... 8 more choices}]
                [--load-interval] [--dump-interval] [--read-only]
                [--on-error-strategy {IGNORE, SKIP_EXECUTOR, SKIP_HANDLE, THROW_EARLY}]
                [--uses-internal] [--entrypoint]
                [--docker-kwargs [KEY: VALUE [KEY: VALUE ...]]]
                [--pull-latest] [--volumes [DIR [DIR ...]]] [--host]
                [--port-expose] [--quiet-remote-logs]
                [--upload-files [FILE [FILE ...]]] [--workspace-id] [--daemon]
                [--runtime-backend {THREAD, PROCESS}]
                [--runtime-cls {GRPCRuntime, RESTRuntime, ContainerRuntime, JinadRuntime ... 2 more choices}]
                [--timeout-ready] [--env [KEY=VALUE [KEY=VALUE ...]]]

Essential arguments


The name of this object.

This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - automatics docs UI - …

When not given, then the default naming strategy will apply.


The description of this object. It will be used in automatics docs UI.


The YAML config of the logger used in this object.

Default: “/opt/hostedtoolcache/Python/3.8.9/x64/lib/python3.8/site-packages/jina/resources/logging.default.yml”


If set, then no log will be emitted from this object.

Default: False


If set, then exception stack information will not be added to the log

Default: False

ZMQRuntime arguments


The port for controlling the runtime, default a random port between [49152, 65535]

Default: 48013


If set, use ipc protocol for control socket

Default: False


The timeout in milliseconds of the control request, -1 for waiting forever

Default: 5000


The SSH server through which the tunnel will be created, can actually be a fully specified user@server:port ssh url.


This specifies a key to be used in ssh login, default None. regular default ssh keys will be used without specifying this argument.


The ssh password to the ssh server.

ZEDRuntime arguments


The config of the executor, it could be one of the followings: - an Executor-level YAML file path (.yml, .yaml, .jaml) - a name of a class inherited from jina.Executor - a docker image (must start with docker://) - builtin executors, e.g. _pass, _logforward, _merge - the string literal of a YAML config (must start with !) - the string literal of a JSON config - the string literal of a YAML driver config (must start with - !!)

When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has .read() interface

Default: “_pass”


The customized python modules need to be imported before loading the executor

Note, when importing multiple files and there is a dependency between them, then one has to write the dependencies in reverse order. That is, if __init__.py depends on A.py, which again depends on B.py, then you need to write:

–py-modules __init__.py –py-modules B.py –py-modules A.py


The port for input data, default a random port between [49152, 65535]

Default: 53347


The port for output data, default a random port between [49152, 65535]

Default: 50193


The host address for input, by default it is

Default: “”


The host address for output, by default it is

Default: “”



The socket type for input port

Default: PULL_BIND



The socket type for output port

Default: PUSH_BIND


Reload the Executor in the Pod on every n seconds. -1 or 0 means do not reload.

Default: -1


Serialize the Executor in the Pod every n seconds if model changes. -1 means –read-only.

Default: 240


If set, do not allow the pod to modify the model, dump_interval will be ignored

Default: False


The memory high watermark of this pod in Gigabytes, pod will restart when this is reached. -1 means no restriction

Default: -1



The skip strategy on exceptions.

  • IGNORE: Ignore it, keep running all Drivers & Executors logics in the sequel flow

  • SKIP_EXECUTOR: Skip all Executors in the sequel, but drivers are still called

  • SKIP_HANDLE: Skip all Drivers & Executors in the sequel, only pre_hook and post_hook are called

  • THROW_EARLY: Immediately throw the exception, the sequel flow will not be running at all

Note, IGNORE, SKIP_EXECUTOR and SKIP_HANDLE do not guarantee the success execution in the sequel flow. If something is wrong in the upstream, it is hard to carry this exception and moving forward without any side-effect.

Default: IGNORE

ContainerRuntime arguments


The config runs inside the Docker container.

Syntax and function are the same as –uses. This is designed when –uses=”docker://…” this config is passed to the Docker container.

Default: “BaseExecutor”


The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.


Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container.

More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/


Pull the latest image before running

Default: False


The path on the host to be mounted inside the container.

Note, - If separated by :, then the first part will be considered as the local host path and the second part is the path in the container system. - If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. –volumes=”/user/test/my-workspace” will be mounted into /my-workspace inside the container. - All volumes are mounted with read-write mode.

Expose arguments


The host address of the runtime, by default it is

Default: “”


The port of the host exposed to the public

Default: 38449

Distributed arguments


Do not display the streaming of remote logs on local console

Default: False


The files on the host to be uploaded to the remote workspace. This can be useful when your Pod has more file dependencies beyond a single YAML file, e.g. Python files, data files.

Note, - currently only flatten structure is supported, which means if you upload [./foo/a.py, ./foo/b.pp, ./bar/c.yml], then they will be put under the _same_ workspace on the remote, losing all hierarchies. - by default, –uses YAML file is always uploaded. - uploaded files are by default isolated across the runs. To ensure files are submitted to the same workspace across different runs, use –workspace-id to specify the workspace.


the UUID for identifying the workspace. When not given a random id will be assigned.Multiple Pea/Pod/Flow will work under the same workspace if they share the same workspace-id.

Default: “a5f9a6ff-eff3-453d-b92c-946566f1b2e4”

Pea arguments


The Pea attempts to terminate all of its Runtime child processes/threads on existing. setting it to true basically tell the Pea do not wait on the Runtime when closing

Default: False

--runtime-backend, --runtime

Possible choices: THREAD, PROCESS

The parallel backend of the runtime inside the Pea

Default: PROCESS


Possible choices: GRPCRuntime, RESTRuntime, ContainerRuntime, JinadRuntime, SSHRuntime, ZEDRuntime

The runtime class to run inside the Pea

Default: “ZEDRuntime”


The timeout in milliseconds of a Pea waits for the runtime to be ready, -1 for waiting forever

Default: 60000


The map of environment variables that are available inside runtime


If set, expose the public IP address to remote when necessary, by default it exposesprivate IP address, which only allows accessing under the same network/subnet. Important to set this to true when the Pea will receive input connections from remote Peas

Default: False