Platform sandbox

​

Channels

​

The web chat

pnpm build
pnpm sandbox
# → open http://127.0.0.1:4610

• API requests: every call the provider made, with its status and any difference from the documented request shape.
• Webhooks: every delivery to the bot, with its HTTP status and retry attempt.
• Faults & user: make the next send fail with a platform error (rate limit, invalid recipient, outside the 24 h window, media too large, authentication, server error). Here you can also change the simulated user’s id and name.

pnpm --filter @botmesh/sandbox start -- --help
pnpm --filter @botmesh/sandbox start -- --channels whatsapp,telegram --port 4620
pnpm --filter @botmesh/sandbox start -- --bot bakery      # examples/bakery-ai with a scripted model
pnpm --filter @botmesh/sandbox start -- --telegram webhook --no-status

​

Local-only API

• It binds to 127.0.0.1 by default. --host changes that, and the CLI warns when the address is not loopback. --host only moves the hub: the simulators always stay on 127.0.0.1, because like the provider APIs they imitate they check neither Host nor a token.
• Every request must carry a loopback Host header on the hub’s port (127.0.0.1, localhost or [::1], plus the names in --allow-host/allowedHosts). That defeats DNS rebinding, where a hostile domain is re-pointed at 127.0.0.1. When the browser sends an Origin or Sec-Fetch-Site header, it must be the hub’s own origin.
• State-changing calls (POST /api/<channel>/send|fault|status|reset) also need the per-run token in the x-sandbox-token header. The CLI prints the token at start and the hub embeds it in the page it serves. --token (or startSandbox({ token })) fixes it for scripts, and sandbox.token returns it from code.
• Bodies are bounded (32 MiB for send, 64 KiB otherwise). Malformed JSON, unknown fields, wrong types and unknown channels get a 4xx with { "error": "..." } that names the problem, and a simulator that cannot express an input (a location on Discord) answers 422.
• Media uploaded through the page is served with nosniff, a sandbox CSP and, except for plain images, audio and video, as a download.

import { startSandbox } from '@botmesh/sandbox'

const sandbox = await startSandbox({
  bot: 'none',
  setup: (bot, channel) => {
    bot.when('hi', (ctx) => ctx.reply(`Hi from ${channel}`))
  },
})
console.log(sandbox.url)

​

In tests

import { CloudAPIProvider } from '@botmesh/meta'
import { WhatsAppSimulator, startHarness } from '@botmesh/sandbox'

const h = await startHarness(
  new WhatsAppSimulator(),
  (sim) => new CloudAPIProvider(sim.providerConfig()),
  (bot) => {
    bot.when('menu', (ctx) => ctx.buttons('Pick one', [{ id: 'bread', title: 'Bread' }]))
    bot.when('bread', (ctx) => ctx.reply('Good choice'))
  },
)

await h.sim.sendText('menu')                                   // signed webhook → bot
const menu = await h.sim.waitForOutbound((r) => r.kind === 'buttons')
await h.sim.send({ reply: { kind: 'button', id: 'bread', messageId: menu.id } })
await h.sim.waitForOutbound((r) => r.text === 'Good choice')
expect(h.sim.issues()).toEqual([])                             // every request matched the docs

h.sim.fail('rateLimit', { retryAfterSec: 30 })                 // next send: 429 + Retry-After
await h.stop()

​

Spec checks

​

Scenarios

• webhookRetries / webhookRetryDelayMs: redeliver when the bot answers non-2xx.
• mediaTtlMs: inbound media URLs expire.
• autoStatus: 'read': receipts after each bot message.
• strict: answer invalid requests with the platform’s validation error (default true).

​

Errors

​

Self-hosted platforms in Docker

docker compose -f packages/sandbox/docker/compose.yml up -d
docker compose -f packages/sandbox/docker/compose.yml run --rm chatwoot-init   # first time
node packages/sandbox/docker/chatwoot-token.mjs                                # prints the Chatwoot variables

BOTWA_TEST_EVOLUTION_URL=http://127.0.0.1:47811 BOTWA_TEST_EVOLUTION_KEY=sandbox-evolution-key \
BOTWA_TEST_WPPCONNECT_URL=http://127.0.0.1:47812 BOTWA_TEST_WPPCONNECT_SECRET=sandbox-wppconnect-secret \
BOTWA_TEST_MAILPIT_URL=http://127.0.0.1:47814 \
BOTWA_TEST_CHATWOOT_URL=… BOTWA_TEST_CHATWOOT_TOKEN=… BOTWA_TEST_CHATWOOT_ACCOUNT_ID=… \
  pnpm --filter @botmesh/sandbox exec vitest run tests/docker

​

What stays manual

1. Start the stack and run start() on the provider (or create the instance from the Evolution manager at http://127.0.0.1:47811/manager).
2. Scan the QR from WhatsApp → Linked devices on a test phone.
3. Re-run the suites. Once the instance is open, sending works too. The suites only need the instance to exist.