Beamable Docs

Beamable C# SDK Monorepo

This repository contains the Beamable Unity SDK, the Beamable CLI, microservice runtime code, templates, and developer tooling. The repo is intended for reference and internal development workflows. However, this is not an open-source distribution. Use of this code in products is only permitted through approved Beamable distributions such as the Unity SDK, the CLI NuGet tool, the Web SDK NuGet package, or the Unreal SDK.

What lives here

Unity SDK Code

The Unity SDK code is available under the /client/Packages folder. The SDK is distributed as a single UPM package, com.beamable. The /client folder is a Unity project used for internal testing, but nothing in /client/Assets is included in any Unity SDK release.

How to test changes in this project

To test any changes to the Unity SDK, you can open the /client Unity project in Unity 2021 or greater.

Dotnet Code (CLI, Microservices, Common)

The CLI, Microservice runtime, and shared common types all live under the /cli folder and are developed using the /cli/cli.sln solution. The solution references .csproj files throughout the codebase. The CLI-specific commands and tooling live under /cli/cli, while the microservice runtime and related projects live under /microservice. Both reference the shared common project.

How to test changes in this project

To test changed made to this project you can run the dev.sh script and use it in your local environment by setting the .config/dotnet-tools.json to use the version generated from the script, usually starts with 0.0.123.

Beamable.Common NuGet Package

The canonical source for the shared common project lives in /cli/beamable.common. This .NET Standard 2.0 project contains most of the Beamable base types (dependency injection, promise library, core components) used across the CLI, Microservice runtime, and Unity SDK. It is published as Beamable.Common on NuGet. The folder client/Packages/com.beamable/Common is a copy of this project used for Unity package consumption.

Unity SDK Installer Code

The Unity SDK Installer is available under the /client_installer directory. This directory contains a Unity project with code for the Beamable Installer and code for packaging that installer into a .unitypackage.

Web SDK

The Web SDK is a TypeScript library under the /web folder, built for both Node.js and browser environments. It is distributed as @beamable/sdk on npm and includes samples (e.g., the WordWiz Telegram Mini App demo). See the Web SDK README for installation and usage.

Terraform

The /terraform folder contains Terraform manifests for infrastructure managed by CI workflows. It includes reusable modules (e.g., S3) and environment configurations. The CI workflow at .github/workflows/runTerraform.yml runs terraform init/plan/apply against the selected environment. See the Terraform README for local usage instructions and prerequisites.

Notes:

• The CLI-specific commands and tooling live under cli/cli and reference the shared Common project.
• When developing locally you can either consume the published NuGet package or reference the local project directly (see cli/beamable.common/DOTNET-CODE-README.md and cli/DOTNET-CODE-README.md for details).

Quickstart — developer flow

Prereqs: dotnet (8+), and a POSIX shell for the provided scripts (or use WSL on Windows). docker is only required when you plan to deploy, run microservice integration/unit tests, or run containerized flows for microservice development.

• Repo-level dev scripts
• ./setup.sh (run once) — prepares the local dev environment and builds helper tooling such as the OTEL collector used by microservices during development.
• ./dev.sh — builds and publishes local packages into a local NuGet feed consumed by downstream projects (used for fast iteration across CLI, microservices, and Unity SDK).
• Run the repo-level scripts from the repository root. See cli/ README for how to run CLI-specific projects after running the scripts.

Web local dev (Portal Toolkit & Web SDK)

Prereqs: Node.js 22+, pnpm, and Docker. Run from the portal workspace (agentic-portal):

beam local run csharp-portal:web   # any stack with the :web variant
beam local run web-dev             # just the package loop, the portal and its extensions, against dev
beam local stop                    # extensions go back to the versions their lockfiles pin

The :web steps build @beamable/sdk and @beamable/portal-toolkit where they changed, publish them to a local Verdaccio registry (portal-localdev/) under a version of their own (<next minor>-0.<yyyymmddHHMMSS>, never reused), and install them into the stack's extensions without saving them, so no package.json or lockfile changes. web: watch rebuilds on every save in web/src or beam-portal-toolkit/src and restarts the extensions. The portal loads the SDK from the local CDN (VITE_SDK_CDN_BASE=/local-unpkg, set by the stack). Building by hand and releasing both packages: web/LOCAL_DEV.md.

If the Portal's .env.local has VITE_INJECT_HOST_SDK=true, comment it out — that's a different approach and it takes precedence over the local CDN.

Running the full local stack on a fresh machine

beam local setup provisions everything beam local run needs — a private, pinned toolchain (JDK 8, Maven, the .NET SDK, Node, pnpm), the settings file with its step catalogue, the gitignored BeamableBackend config files, and a check of the AWS prerequisites. It works the same on macOS, Windows and Linux, and installs nothing system-wide.

On a machine that has never run the stack:

1. Install the .NET SDK, then dotnet tool install -g Beamable.Tools.
2. Install Docker Desktop and start it — setup cannot install Docker, because it needs administrator rights.
3. Clone BeamableAPI, BeamableBackend, BeamableProduct and the portal as siblings.
4. Then:

beam local setup                     # the toolchain, the settings, the backend config, the AWS checks
beam local run                       # lists the stacks: full, backend, csharp-portal, ...
beam local run full --dry-run        # what a stack would run: steps, folders, ports, variables, checks
beam local run full                  # builds what's missing and starts it; Ctrl+C stops it
beam local run full --detach         # or keep it running and manage it from any terminal:
beam local ps                        # the live board (restart, stop or start a step from it)
beam local logs "scala: auth" -f     # a step's log; with logs forwarded, Grafana at http://localhost:3001
beam local stop

A stack name picks what runs and against which backend: full:no-build, csharp-portal:web, backend:lan, portal-extensions:local. beam local create and edit make your own stacks; teams commit theirs to .beamable/shared/stacks/.

AWS access is required; there is no LocalStack in this stack. The Scala auth service reads its JWT signing key from AWS Secrets Manager at runtime, so without credentials the stack comes up healthy and nothing can log in. beam local setup --only aws checks this and prints what an AWS administrator needs to do.

Full reference for agents and people: the beam-local-stacks skill, which beam local setup writes into the workspace's .claude/skills/ from the installed CLI (beam local setup --only skill refreshes it); its template is cli/cli/Docs/LocalStack/beam-local-stacks.md.scriban.

Documentation and help

• Unity SDK docs: https://help.beamable.com/Unity-Latest/
• CLI docs: https://help.beamable.com/CLI-Latest/
• Web SDK docs: https://help.beamable.com/WebSDK-Latest/

Contributing

This repository is not open for external code contributions. We welcome feedback via GitHub Discussions or Issues:

• Discussions: https://github.com/beamable/BeamableProduct/discussions
• Issues: https://github.com/beamable/BeamableProduct/issues/new

License

All source in this repository is licensed under the MS-RSL license: https://referencesource.microsoft.com/license.html

You may use the code for reference only; to ship a product use Beamable's official distributions (UPM, NuGet, Dockerhub).