Skip to main content

Bot Lifecycle

Understanding how bots transition between states is the difference between a clean operational recovery and accidentally closing every open position at the wrong moment. This page documents every state, every transition, and what each control button actually does to a running container.

Bots list — every bot begins its lifecycle in the stopped state after creation

State Machine​

State Descriptions​

stopped​

The bot is inactive. No container is running. The bot can be started at any time.

Actions available: Start

creating​

VolatiCloud is spinning up the bot container on the runner. This involves:

  • Pulling the Freqtrade Docker image
  • Configuring the strategy and exchange credentials
  • Starting the container

This typically takes 30–60 seconds.

Actions available: None (wait for completion)

running​

The bot is active and monitoring the markets. It will execute trades according to the configured strategy.

Actions available: Stop, Restart, Pause Entry, Force Exit All, Force Exit Trade

error​

The bot encountered an unrecoverable error and stopped. Common causes:

  • Invalid exchange API credentials
  • Exchange API rate limit exceeded
  • Strategy code error
  • Network connectivity issue

Check: The bot detail page will show error logs. Fix the underlying issue before restarting.

Actions available: Start (retry)

unhealthy​

The bot container is running but health checks are failing. This often means:

  • The bot is running but can't connect to the exchange
  • The strategy is throwing exceptions

Actions available: Restart

backtesting​

The bot is temporarily in backtesting mode. This status appears when a backtest is triggered through a bot's context. The bot returns to stopped after the backtest completes.

Actions available: None (wait for completion)

hyperopt​

The bot is running Freqtrade's hyperparameter optimization. This is a resource-intensive operation that tunes strategy parameters against historical data. The bot returns to stopped when complete.

Actions available: None (wait for completion)

Lifecycle Operations​

Starting a Bot​

When you click Start:

  1. VolatiCloud validates the bot configuration
  2. Sends a start command to the runner
  3. The runner creates and starts the Freqtrade container
  4. The bot begins downloading historical data
  5. The bot starts monitoring the market and trading

Stopping a Bot​

When you click Stop:

  1. VolatiCloud sends a graceful stop command
  2. The bot completes any in-progress operations
  3. Open trades are left open — they will NOT be closed automatically
  4. The container is removed from the runner
important

Stopping a bot does NOT close your open positions. If you need to close all positions first, use Force Exit All before stopping.

Force Exit All​

Use this when you want to immediately close all open positions and stop the bot:

  1. Sends a force-exit command to Freqtrade
  2. All open trades are closed at current market price
  3. The bot then stops

Pause Entry​

Use this when you want the bot to continue managing existing positions but not open new ones:

  1. The bot stops opening new trades
  2. Existing open trades continue to be managed (exits still work)
  3. The bot remains in running state

To resume normal operation, restart the bot.

Automatic Status Monitoring​

VolatiCloud monitors your bots using a hybrid WebSocket + REST approach:

  • WebSocket (default): Trade events, warnings, and status changes arrive in real-time (sub-second). REST polling is reduced to every 10 minutes for reconciliation when WebSocket is connected.
  • REST-only fallback: If WebSocket is unavailable, REST polling handles all monitoring.
  • CPU and memory usage are tracked
  • Health checks are performed
  • Status changes are detected and published via WebSocket subscriptions
  • Alert rules are evaluated against new bot events