Croupier is a Server / Agent / SDK platform for game operations and control, intended by default for multiple games and multiple environments within a single game company. The architecture has converged on a unified session transport:
Agent <-> Server: TCP session by default; TLS is opt-in viaserver.toAgentTLS(server side) /server+outboundTLS(agent side), and the bundled development templates default to plaintextSDK <-> Agent: TCP session by default, TLS off by default and enabled on demand- Both links share the same session transport foundation and differ only in the first handshake message and business semantics
| Role | Responsibility | Delivery status |
|---|---|---|
| sidecar | Game function gateway, task forwarding and game-side observation | croupier-agent; supervisor wiring, schedule/update lifecycle and function plugins shipped |
| devops | Allowlisted internal remote access with audit | devops-agent; SSH sessions with replay archive shipped; RDP/VNC pending |
| capture | Database CDC, change rules and alerts | capture-agent; MySQL/Mongo/PostgreSQL connectors and checkpoint/alert reliability shipped; source schema history pending |
| synthetics | External game/service checks with developer plugins | synthetics-agent; HTTP/TCP/ICMP probes with Go/Python/JS plugin SDKs and credential boundary shipped |
Each instance explicitly belongs to one gameId/env. See the Agent guide for roles, deployment and individual nightly packages, and runtime layout for shared code and remaining migrations. New assets require a successful release run; ARMv7 supports sidecar/devops only.
URL: https://croupier.cuihairu.site/
| Account | Password |
|---|---|
admin |
admin123 |
[Demo environment: all data is fake and is reset from time to time. Do not enter any real information.]
The
admin/admin123credentials above are for the hosted demo only (the demo compose stack opts in viaCROUPIER_BOOTSTRAP_ALLOW_DEFAULT=1). On a self-installed instance the server never seeds the factory default password: on first bootstrap it generates a random password for accounts configured withadmin123, prints it once in the startup log, and you should change it after signing in. To provision fresh credentials before first start, runscripts/gen-bootstrap-auth.sh <config-dir>; the demo/e2e configs opt back in viaauth.allowDefaultCredentials: true.
- Single-company, multi-game, multi-environment scope model: the standard business boundary is
gameId + env - Separation of business scope and run target:
scopeexpresses ownership,targetexpresses deployment and execution location - Unified function registration, dispatch, invocation, and job model
- Lightweight session transport: single connection, bidirectional requests, reconnect, backpressure, stream detach
- JSON payload + protobuf envelope: cross-language consistency at a reasonable integration cost
- JSON Schema capability contracts + a generated console UI driven by Ant Design Pro/ProComponents
| Database | Driver | Typical use |
|---|---|---|
| SQLite | glebarez/sqlite |
Development, testing, small setups |
| MySQL | gorm.io/driver/mysql |
Production (recommended) |
| PostgreSQL | gorm.io/driver/postgres |
Production |
| SQL Server | gorm.io/driver/sqlserver |
Enterprise environments |
DSN configuration examples for each database are in the server configuration guide.
All official SDKs are maintained together in the sdks/ directory of this monorepo.
| Language | Directory | Build | Coverage | Docs |
|---|---|---|---|---|
| Go | sdks/go/ |
README | ||
| C# | sdks/csharp/ |
README | ||
| Java | sdks/java/ |
README | ||
| C++ | sdks/cpp/ |
README | ||
| Python | sdks/python/ |
README | ||
| JS/TS | sdks/js/ |
README |
| Module | Directory | Build | Coverage |
|---|---|---|---|
| Dashboard | web/ |
croupier-server mcp exposes the control plane to AI agents over the Model Context Protocol (stdio): read-only list_sessions / query_jobs plus sync invoke_function, scoped to one game and audited under the operator's identity. Game-side write tools (bans/compensation/orders) are deliberately absent until the GAME-009/010 credential protocol lands. See MCP server guide.
Current game-operations readiness: high-risk production writes are not approved. Code/TODO review records governance, policy-failure, duplicate-scheduling and receipt gaps.
Full SVG / 完整 SVG · Runtime evidence / 运行依据
Primary execution path: Console (Web) → Server (control plane, capable of multi-instance HA) → Agent (proxy inside the game VPC) → Game Server / SDK.
Entry points are separated by audience: the web console uses L7 (HTTP API / SSE), while agents use internal L4 (long-lived TCP connections).
The health-probe system is layered the same way for every runtime — one shared kernel (core/healthprobe), protocol checkers (HTTP/TCP/process/DB plus a declarative game-protocol skeleton), and execution placed wherever the network perspective matters, extensible via external probe adapters (see agent-health-recovery-review.md).
See the architecture overview and the load balancing guide for details.
Croupier is not a fork. It is a control-plane business layer, and everything underneath is built on open-source components (versions as pinned in go.mod / web/package.json):
- Server: Go 1.27, Gin for HTTP, GORM as the ORM (MySQL / PostgreSQL / SQL Server / glebarez SQLite drivers), Casbin for authorization decisions, goose for numbered migrations
- Transport: the TCP session for Agent↔Server and SDK↔Agent is implemented on the Go standard library
net+crypto/tls(length-prefix framing, protobuf envelope). These links do not use gRPC; plugin children separately use local go-plugin gRPC. The transport decision record is in adr/0001-transport.md - Observability: OpenTelemetry Go SDK with OTLP HTTP exporter
- Console: built on Umi Max and Ant Design / ProComponents; JSON Schema forms are driven by RJSF, and the editor is Monaco
- Protocol and tooling: protobuf (fully local protoc generation) + buf lint
- The six SDKs (go / js / python / java / csharp / cpp) are built on each language's standard library; the wire contract is in sdk-wire-protocol.md
The core transport abstraction in Croupier is not a "message history" model but a lightweight application-layer session:
- One reliable long connection
- The first message negotiates identity and capabilities
- New requests can be initiated in both directions on the same connection
- Multiple concurrent in-flight requests are multiplexed
- heartbeat / reconnect / drain / backpressure
This is why two terms appear in the documentation:
shared session runtime- The shared transport foundation:
tcp/tls + framing + mux + reconnect + heartbeat + drain
- The shared transport foundation:
subprotocol- A protocol variant running on top of that foundation, for example:
sdk-agent subprotocolagent-server subprotocol
- A protocol variant running on top of that foundation, for example:
A subprotocol is not "custom configuration"; it is an application-layer protocol variant that shares the same session runtime but differs in handshake message, registration content, and routing semantics.
See the transport glossary for the full term set (session runtime, subprotocols, frames, handshake, and the L1–L4 SDK capability layers).
Croupier does not adopt a SaaS multi-tenant abstraction. The standard business scope is:
gameId: the game identifier. Layered forms: contract keygameIdin REST/SDK, HTTP headerX-Game-ID, proto field and DB columngame_idenv: logical environment identifier, such asdev,staging,prod
env here expresses a lifecycle stage and is not equal to a specific database, cluster, or node. Physical deployment and runtime location should be expressed through separate target, node, and agent abstractions, not mixed into env.
- Roadmap: ROADMAP.md
- Architecture overview: docs/architecture/index.md
- Game and environment scope: docs/architecture/game-environment-scope.md
- SDK-Agent design: docs/architecture/sdk-agent-transport-redesign.md
- Agent-Server design: docs/architecture/agent-server-session-transport-redesign.md
- Wire protocol: docs/architecture/sdk-wire-protocol.md
- Unified SDK documentation: docs/sdks/index.md
- SDK capability matrix: docs/sdks/sdk-parity-matrix.md
- SDK code entry point: sdks/README.md
- Server / Agent release tags use
v*, for examplev0.2.0 - SDK release tags use a language-prefixed format:
sdk-js-v0.1.0sdk-python-v0.1.0sdk-go-v0.1.0sdk-java-v0.1.0sdk-cpp-v0.1.0
- This prevents one tag in the monorepo from accidentally triggering every release workflow
| Component | Location | Description |
|---|---|---|
| Server / Agent | cmd/, internal/ |
Control plane, proxy, dispatch, audit, registry, and jobs |
| Proto | proto/ |
Protobuf definitions and generation entry point (single source) |
| SDKs | sdks/ |
Multi-language SDKs (go, js, python, java, csharp, cpp) |
| Dashboard | web/ |
Web console (React + Ant Design) |
| Examples / Tools | examples/, tools/ |
Examples and helper tools |
| Mobile | mobile/ |
Flutter mobile app (Android/iOS) |
| Docs | docs/ |
Architecture, guides, API, and SDK documentation |
Install croupier-agent on a game server with a single command (detects OS and CPU architecture automatically, downloads the artifact anonymously, and rerunning upgrades in place):
Linux (x86_64 / ARM64 / ARMv7):
curl -fsSL https://raw.githubusercontent.com/cuihairu/croupier/main/scripts/install.sh | bash -s --macOS (Intel / Apple Silicon):
curl -fsSL https://raw.githubusercontent.com/cuihairu/croupier/main/scripts/install.sh | bash -s --Windows (PowerShell 5.1+, x64):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/cuihairu/croupier/main/scripts/install.ps1)))The default is the latest stable release; --version nightly installs the daily build, --with-service registers autostart on boot (systemd / launchd / Windows service), and --uninstall removes the agent. Full usage is in agent install.
Pre-built images bring up a minimal stack with one command (server + agent + dashboard + postgres/redis; no local build required):
cd docker
docker compose -f docker-compose.quickstart.yml up -dCommon operations:
docker compose -f docker-compose.quickstart.yml logs -f server # follow logs
docker compose -f docker-compose.quickstart.yml down # stop
docker compose -f docker-compose.quickstart.yml pull && \
docker compose -f docker-compose.quickstart.yml up -d # upgrade
docker compose -f docker-compose.quickstart.yml down -v # ⚠️ wipe data (removes volumes too)Optional components (six-language SDK examples / analytics pipeline) are started with --profile and are not part of the default stack; secrets, ports, multi-game vs. single-database switching, and the pitfall that "a --profile pull cascades into rebuilding the full stack" are described in the header comments of
docker-compose.quickstart.yml
and the Docker deployment guide.
The source-build stack (docker/docker-compose.yml, used for local development) also runs a capture-agent service by default for CDC capture: it registers against server:19090 and subscribes to the local postgres logical replication stream. Disable it with CAPTURE_AGENT_REPLICAS=0 docker compose up -d capture-agent; prerequisites (wal_level=logical, a pre-created publication) and the verification steps are in the Docker deployment guide.
- Clone the repository
git clone https://github.com/cuihairu/croupier.git
cd croupier- Install the toolchain
- Go 1.27.4+
- Node.js 24+ / pnpm
bufprotoc
- Install the pre-commit hook (recommended)
cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit- Build
make proto && make build- Start
./bin/croupier-server --config configs/server.yaml
./bin/croupier-agent --config configs/agent.yaml- View the dashboard
cd web
pnpm install
pnpm devSome historical documents in this repository still reference gRPC, the historical REQ/REP, LocalControl, rpc_addr, or the SDK local-listener model.
These are being cleaned up step by step under the unified "TCP session + subprotocol" design and should no longer be treated as the basis for new implementations.
