Skip to main content

MesoLive Agent Setup - CLI

The MesoLive Agent CLI is the headless version of MesoLive-Agent.

It is typically used on servers (Linux or Windows), or environments where the App Stores are not available. It is a low-resource command-line application that can run on any OS with Docker support.

Requirements​

  • Docker Desktop
  • A valid Agent Key from the Agents page
  • At least one enabled integration:
    • IBKR TWS (host + port + client id), and/or
    • TastyTrade (client secret + refresh token)

Create an Agent Key​

  1. Open the MesoLive Agents page
  2. Click New Agent Key
    Agent key
  3. Copy and save the key value (it is shown once) in a safe place.
    Important

    Treat Agent Keys like passwords. If a key expires or is revoked, generate a new one and update the Agent configuration.

License acceptance​

You must accept the Terms and Conditions:

  • Pass --accept-license command line parameter, or
  • Set ACCEPT_LICENSE=yes environment variable.

In Docker, using the env var is recommended:

docker run -it --name mesolive-agent -e ACCEPT_LICENSE=yes deltarayio/mesolive-agent:VERSION -- --help

CLI options​

IBKR / TWS​

  • --tws-host: TWS host name or IP (example: host.docker.internal)
  • --tws-port: TWS API port (typically 7496 live, 7497 paper)
  • --tws-client-id: TWS client id (must be unique per TWS API client)
  • --no-tws: disable TWS even if env vars are set
Docker host TWS networking notes
  • macOS/Windows: use host.docker.internal for TWS Host.
  • Linux: host.docker.internal may not exist.
    • Option A (recommended): add --add-host=host.docker.internal:host-gateway (Docker 20.10+).
    • Option B: use your host’s LAN IP address.
    • Option C: use --network host (only if it fits your security model).

TastyTrade​

  • --tasty-client-secret: OAuth client secret
  • --tasty-refresh-token: OAuth refresh token
  • --no-tasty: disable TastyTrade even if env vars are set

MesoLive​

  • --agent-key: the Agent Key JWT (treat it like a password)
  • --accept-license: accept the Terms and Conditions for this run

Logging​

  • --verbose: debug logging
  • --trace: trace logging (most verbose)

Environment variables​

The CLI supports env var configuration. CLI flags override env vars when both are present.

VariableMeaning
MESOLIVE_AGENT_KEYAgent Key (JWT)
MESOLIVE_BASE_URLAdvanced: override Portal base URL (default: https://mesolive.io; change only if instructed by support)
MESOLIVE_TWS_HOSTTWS host
MESOLIVE_TWS_PORTTWS port
MESOLIVE_TWS_CLIENT_IDTWS client id
MESOLIVE_TASTY_CLIENT_SECRETTastyTrade OAuth client secret
MESOLIVE_TASTY_REFRESH_TOKENTastyTrade OAuth refresh token
ACCEPT_LICENSEMust be set to yes to accept Terms and Conditions

Docker examples​

warning

Avoid placing secrets (Agent Key, refresh token) directly on the command line in production. They can leak via shell history and can be visible via process inspection. If this is a shared machine, avoid using account credentials directly in terminal history.

IBKR / TWS only​

docker run -it --name mesolive-agent \
  -e ACCEPT_LICENSE=yes \
  -e MESOLIVE_AGENT_KEY=eyJra...R4GA \
  -e MESOLIVE_TWS_HOST=host.docker.internal \
  -e MESOLIVE_TWS_PORT=7496 \
  -e MESOLIVE_TWS_CLIENT_ID=132 \
  deltarayio/mesolive-agent:VERSION

TastyTrade only​

docker run -it --name mesolive-agent \
  -e ACCEPT_LICENSE=yes \
  -e MESOLIVE_AGENT_KEY=eyJra...R4GA \
  -e MESOLIVE_TASTY_CLIENT_SECRET=123456 \
  -e MESOLIVE_TASTY_REFRESH_TOKEN=eyJ... \
  deltarayio/mesolive-agent:VERSION

IBKR + TastyTrade​

docker run -it --name mesolive-agent \
  -e ACCEPT_LICENSE=yes \
  -e MESOLIVE_AGENT_KEY=eyJra...R4GA \
  -e MESOLIVE_TWS_HOST=host.docker.internal \
  -e MESOLIVE_TWS_PORT=7496 \
  -e MESOLIVE_TWS_CLIENT_ID=132 \
  -e MESOLIVE_TASTY_CLIENT_SECRET=123456 \
  -e MESOLIVE_TASTY_REFRESH_TOKEN=eyJ... \
  deltarayio/mesolive-agent:VERSION

Running it as a service​

Use one docker run command with the -d flag to create a long-running service. --restart unless-stopped makes it come back after reboot.

docker run -d --restart unless-stopped --name mesolive-agent \
  -e ACCEPT_LICENSE=yes \
  -e MESOLIVE_AGENT_KEY=eyJra...R4GA \
  -e MESOLIVE_TWS_HOST=host.docker.internal \
  -e MESOLIVE_TWS_PORT=7496 \
  -e MESOLIVE_TWS_CLIENT_ID=132 \
  deltarayio/mesolive-agent:VERSION

Basic service commands​

docker logs mesolive-agent
docker restart mesolive-agent
docker stop mesolive-agent
docker start mesolive-agent

Optional debug logging:

docker run ... deltarayio/mesolive-agent:VERSION -- --verbose

Upgrading​

Docker Container are not updating automatically. To see the available versions, check the Docker Hub repository.

Upgrade steps:

  • Identify latest version tag from Docker Hub
  • docker pull deltarayio/mesolive-agent:NEW_VERSION
  • docker stop mesolive-agent
  • docker rm mesolive-agent
  • Re-run the same docker run -d ... command, replacing the image tag
  • docker logs mesolive-agent

If the Agent suddenly can’t connect after a service update, upgrading is the first thing to try: MesoLive may enforce a minimum Agent version for protocol compatibility.

Troubleshooting​

  • “Terms and Conditions were not accepted”: set ACCEPT_LICENSE=yes or pass --accept-license.
  • “Neither TWS nor TastyTrade is configured”: provide TWS and/or Tasty settings (flags or env vars).
  • TWS connection issues:
    • Confirm TWS is running and API access is enabled (see Interactive Brokers).
    • Confirm the port matches TWS settings (7496/7497 by default).
    • Ensure --tws-client-id is unique (conflicts can prevent connection).
    • If Docker can’t reach your host-local TWS, see “Docker → host TWS networking notes” above.

For a deeper symptom → cause → fix playbook, see: Troubleshooting → Agent.