Dashboard / HUB

Maintained by BIPRO

Required for every automation

The Dashboard / HUB API is a required integration, in addition to the Bambou AI API. Your site automation is not finished until it is connected and verified in the HUB.

The HUB coordinates worker health, start/stop/restart, configuration and proxies, statistics, telemetry, and backups. It does not implement your site's automation, AI generation, or captcha solving.

Public dashboard / API origin: https://bamboubot.duckdns.org
Agent API base: https://bamboubot.duckdns.org/api/agent

Use the public HTTPS origin, not localhost. Set HUB_URL to the origin only — the client adds /api/agent. The full written reference is published below; the backend does not expose Swagger/OpenAPI documentation.

Setup and starter downloads

  1. Ask BIPRO/Bambou to create or assign your site in the dashboard and provide its one-time site-scoped agent token. Each site has a different token. Rotation invalidates the previous token immediately.
  2. Download the documentation + VPS starter package. It includes the Python, Node.js, and Go starters, shared Python agent/ modules, and systemd service examples. Choose one implementation; these are infrastructure starters, not completed site automations.
  3. Follow the common starter instructions and your language's README: Python, Node.js, or Go. Preserve the package directory layout, especially for Python's shared imports.
  4. Implement your worker hooks and real measurement/reporting. The sample hooks do not perform site automation or invent task/statistics activity.
  5. Configure the private environment below, select the locally installed worker command or hook, and run the supervisor as a persistent systemd service. See the included service example. Keep runtime/state directories private and persistent across restarts.
  6. In the dashboard, configure the AI key, preset, worker count, proxies, and assigned backup destination. Press Start; verify the acceptance checks below before handoff.
HUB_URL=https://bamboubot.duckdns.org
HUB_AGENT_TOKEN=replace-with-your-site-scoped-agent-token
HUB_RUNTIME_DIR=/opt/your-script/runtime
HUB_STATE_DIR=/var/lib/your-script-hub
HUB_BACKUP_DIR=/opt/your-script

These are example paths and a placeholder token, not credentials. Ask for the real token privately. Python loads its adjacent .env; Node requires node --env-file=.env main.mjs; Go uses shell or service exports. Follow the language README for requirements and exact commands.

Run only one supervisor per site token. Do not run a template and a separate direct integration for the same pool: heartbeats replace the whole site's worker snapshot. Use separate sites/tokens for independent pools.

What you must wire up

Read custom integration, local-sync contract, statistics, telemetry, and backups for the complete semantics.

Agent API quick reference

All paths below are relative to https://bamboubot.duckdns.org. Authenticate with Authorization: Bearer <site-agent-token>. Do not use the administrator password/token for agent routes.

Method / pathPurpose
GET /api/agent/configLoad runtime settings, secrets, proxy pool, revision, and enrollment state.
POST /api/agent/local-syncRevision-checked first enrollment; HUB becomes authoritative afterward.
POST /api/agent/heartbeatComplete worker snapshot every 15 seconds.
GET /api/agent/commandsPoll pending/delivered lifecycle commands every 5 seconds.
POST /api/agent/commands/{id}/ackAcknowledge completed/failed local action.
POST /api/agent/errorsSanitized error/status event; optional worker/proxy attribution.
POST /api/agent/statisticsAbsolute whole-site statistics snapshot.
POST /api/agent/chatsMeasured chat-completion summary, no transcripts.
POST /api/agent/ai-usageMeasured AI usage batch with nonsecret key alias.
GET /api/agent/backup-configRead backup schedule/destination IDs.
POST /api/agent/backup-statusReport backup capability/next scheduled time.
GET /api/agent/backup-requestsPoll pending/delivered on-demand backup requests.
POST /api/agent/backup-requests/{id}/ackAcknowledge a definite backup failure; upload marks success automatically.
POST /api/agent/backups/uploadStream raw bytes as application/octet-stream; not multipart.

Public connectivity check (no credentials):

curl --fail https://bamboubot.duckdns.org/api/health
# Expected: {"status":"ok"}

Full payloads, responses, administrator endpoints, and limits: API contract, backend reference, and backup contract.

Verify before handoff

Credentials, retries, and limits

Keep tokens in private environment/service files (mode 0600) and runtime directories private. Never commit tokens, print config responses, or expose HUB credentials to worker processes. Keep TLS verification enabled and avoid redirects carrying credentials.

Lifecycle delivery is at least once, not exactly once. Preserve state, implement idempotent hooks, and acknowledge superseded commands correctly. Heartbeats allow up to 100 unique workers. Retry network/5xx errors with bounded backoff; fix 401 enrollment failures rather than substituting an admin credential.

Chat/AI event receipts have a bounded deduplication window (seven days by default). Reuse event IDs/payloads and stop retrying before their receipt expires. Storage limits may return 429; follow the documented retry policy. Error events are not idempotent.

Report counts and pseudonymous internal IDs, never transcripts, prompts, AI replies, participant identifiers, actual links, or secrets. Backups are separate from telemetry: whole-codebase archives may contain .env and other private files. Keep secret environment files outside the backup source or protect/encrypt backups. Cloud credentials belong only on the HUB.

Complete documentation library

These are published copies of all 19 Markdown documents in HubDashboard/, plus the shared-agent and language starters in the download. Production HUB origin examples use https://bamboubot.duckdns.org. Local-development server/bind instructions in the reference documents are not the production API address.

Download docs + all three starters (.zip) ↓

Getting started

Language starters

API and synchronization contracts

Reporting, proxies, and backups

Architecture and operator reference

Source snapshot: d7e9d4da17f8 · 19 documents · Download includes 81 allowlisted source files. No production credentials or runtime data.