Train Your Agent (Sandbox)

Sandbox Mode is a per-agent toggle that lets an agent run its full Sense → Reason → Actuate → Reflect loop against synthetic data instead of real data sources. It is designed for demos, training, and pipeline validation, where you want to see the agent behave end-to-end before wiring production credentials.

Sandbox Mode is not the same as local execution. In Sandbox Mode, the agent runs against synthetic data. To run a deployed agent against your real connections on a local orchestrator, see Test an Agent Locally.

What Changes in Sandbox Mode

When Sandbox Mode is on, the agent runtime rewrites the sense stage before it initializes any connections:

  • The runtime replaces Sense substages that read from external sources (MQTT, database, API, CSV) with a synthetic data generator. The generator produces plausible values based on variable-name heuristics. A substage that reads temperature returns values in the 18–30 °C range. One that reads pressure returns values appropriate for an industrial sensor.

  • The runtime does not initialize sense-only connections (brokers, database pools, API auth). The agent makes no connection attempts, so no "broker unreachable" log lines appear.

  • Sandbox cycles are marked as sandboxed so they remain distinguishable from production cycles.

  • Agent-to-agent messages are left untouched. They do not come from an external data source.

What Does Not Change

Everything outside the sense stage runs identically to a non-sandbox agent:

Stage Sandbox Behavior

Reason (analyze, plan, govern, authorize)

Unchanged. Runs against the synthetic observations.

Actuate

Unchanged. Real side effects fire (see warning below).

Reflect

Unchanged.

Human feedback

Unchanged.

Actuations Still Fire

Actuate effects are real in Sandbox Mode. Emails are sent. Slack messages post. MQTT messages are published. Webhook calls fire. Ticket-create actions open real tickets.

This behavior is intentional. Sandbox Mode supports operational walkthroughs where the agent’s downstream effects need to be visible end-to-end. The runtime adds a sandbox disclosure to every outbound message so recipients know the upstream data was simulated.

The runtime attaches the disclosure in the way that suits each handler:

Handler Disclosure Location

email-send / email-template

Footer line appended to both plain-text and HTML body.

slack-message

Context block appended to the Slack payload.

teams-message

Fact section added to the Teams adaptive card.

mqtt-publish

__sandbox: true field added to the published payload.

api-call / webhook-trigger

X-Sandbox-Mode: true request header.

ticket-create

Prefix added to the ticket description.

How to Enable Sandbox Mode

You turn Sandbox Mode on when you deploy the agent. In the deploy wizard’s Set up your agent step, switch on the Sandbox Mode toggle ("Run the agent against synthetic data. Actuations still fire, with a sandbox disclosure."), then deploy. See Deploy an Agent.

You can also toggle Sandbox Mode on an agent that is already deployed. Switch it on or off from the agent and the change takes effect on its next cycle. You can move an agent between synthetic and real data without redeploying it.

Environment variable override: When running an agent runtime directly, set HIVEMQ_SANDBOX_MODE=true (also accepts 1 or yes, case-insensitive) to force Sandbox Mode on, regardless of the agent’s deployed setting. The local-test Docker image sets this variable, so you can run an agent without real data sources. See Test an Agent Locally.

When to Use Sandbox Mode

Scenario Use Sandbox Mode?

Demo to a customer: Show the agent running without their credentials

Yes

New-customer onboarding: Validate the agent shape before pointing at production

Yes

Workshop or training: Each participant needs a running agent quickly

Yes

Pipeline validation: Confirm boot, connect, cycle, and actuate paths work

Yes

Testing agent logic against realistic edge-case data

No: Wire a staging environment with real data

Production-readiness testing

No: Use a staging environment with real data sources

Sandbox Mode is not a substitute for testing against real data. Heuristic-generated values follow predictable patterns; a production environment introduces noise, latency, message ordering, and schema variation that the sandbox cannot reproduce. Validate with real data before going live.

Next Steps