cli

install

install bun and python 3.10 or newer, then:

git clone https://github.com/b44ken/botblocks
cd botblocks
bun install
bun link
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e 'client/py[rl]'

keep the virtual environment active when running the cli: the host launches python3 from your path. omit [rl] if you do not need GymEnv, Policy, or the training demos. robot definitions and project assets are fetched from botblocks, so loading them needs a network connection.

run locally

botblocks run script.py
botblocks run script.py --port 6676
botblocks run script.py --headless

run starts a local host, uploads the script, and opens its workspace. the default port is 6675. browser opening currently uses macos open; on linux, use --headless and open http://localhost:6675/workspace yourself. --headless skips opening the browser; it does not change your python environment's view setting.

press ctrl-c to stop the run. browser-backed runs record a replay automatically and print its link when the run ends, including on ctrl-c.

to run just the host, use botblocks serve --port 6675. serve and run execute scripts locally.

cameras without a workspace browser

install chrome or chromium and enable the host renderer:

BOTBLOCKS_RENDER=1 botblocks run script.py --headless

this supplies simulated camera images even when no workspace viewer is open. the hosted containers enable it automatically.

deploy a script

botblocks login
botblocks deploy script.py
botblocks deploy train.py --size medium
botblocks deploy train.py --size gpu
botblocks deploy script.py --host http://localhost:6675

deploy sends the script's text to the host and prints its workspace url. it does not upload neighboring files or install extra dependencies. use project assets for shared meshes and policies; local paths such as /tmp/policy.zip refer to the machine running the script.

the default host is https://botblocks.dev. anonymous deploys use a small container. signed-in users can select small, medium, or gpu, and find their runs on their profile. the hosted images include the python client and rl dependencies.

process cleanup is based on activity, with a default 60-second idle timeout; there is no fixed two-minute or 30-minute run limit. an open workspace or a connected agent counts as activity; a script nobody is watching is stopped, even mid-run. stop a run from the workspace when finished. a local host can set BOTBLOCKS_TTL in milliseconds to change its idle timeout.

develop and ship

from the repository root:

bun run dev
bun run test
botblocks ship

dev watches the local host. test runs the integration suite. ship publishes the website to cloudflare pages, rebuilds the small, medium, and gpu daytona images, then checks a real production workspace. it requires the project's cloudflare/daytona credentials and adminsdk.json for the gallery build.