Getting Started

Sign in, point BTS at a GitHub repo, open a pull request, share the preview URL. The whole loop runs in about five minutes.

Skip the setup — let Claude Code do it

The BTS Claude Code skill maps your services, writes a Dockerfile.bts per service and nexos.yaml, creates the project, walks you through the GitHub App, opens your first preview PR, and fixes the deploy until it's live. It works for monorepos and for apps split across several repos.

curl -fsSL https://test.buildingswell.com/install-skill.sh | sh
# then, in Claude Code inside your repo:
> Set this repo up on BTS

Details on the Claude Code Skill page. Using another assistant? Paste it the AI Agent Spec. The manual flow below works too.

What you need

A GitHub repo you can deploy, and permission to install a GitHub App on it (or an org owner who will approve it).
A Dockerfile whose container listens on 0.0.0.0:$PORT. If you don't have one, the skill above writes a Dockerfile.bts for you, or you can start from this minimal Node example:

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Step 1 — Sign in

Open https://app.test.buildingswell.com and click Sign in with GitHub.

Step 2 — Create a project

Click New Project and pick a repo. Defaults are sensible — you can change them later, or commit a nexos.yaml to version-control the whole config.

Step 3 — Install the GitHub App

Install the BTS GitHub App on the repo. The project's Repositories settings card links straight to an install screen for just that repo. That's how BTS hears about pull requests, clones private repos and posts the preview link back. You don't need to add a webhook by hand. For a private repo, BTS uses the App once someone in your workspace has shown it can read the repo: sign in with (or connect) a GitHub account that can see it, then click Verify access on that card if it asks.

Step 4 — Add secrets (if you have them)

Under Environment Variables, add any API keys or third-party credentials your app needs. Values are encrypted with AES-256-GCM. DATABASE_URL, REDIS_URL, and PORT are injected automatically — don't set them yourself.

Step 5 — Open a pull request

git checkout -b try-bts
git commit --allow-empty -m "first preview"
git push origin try-bts
# then open a pull request for try-bts (not a draft)

Previews are created by non-draft pull requests; a push without a PR doesn't create one. BTS builds your image, provisions the services you enabled, starts the containers, and wires up a preview URL. Watch logs stream live in the dashboard.

Step 6 — Open the URL

It's posted on the PR and shown on the environment page, and looks like try-bts-my-app-x7k2qd.test.buildingswell.com.

Next pushes

The next push to the same branch is an incremental deploy: only your app container rebuilds. The database, cache, and other services persist — your test data and sessions survive. Use Reset Database on the environment page when you want a clean slate.

Where to go next

nexos.yaml — the single config file that controls your environment.
Deployments — what happens between push and live URL.
Environment Variables — secrets, auto-injected vars, bulk import.
Resource Limits — set vCPU, vRAM, build timeouts; check your quota.
API Reference — automate with an API key.

Running BTS yourself

BTS is open source. To self-host the control plane and run your own nodes, follow the README at BuildingSwell/bswl-test. docker compose up -d brings up Postgres and Redis; then pnpm dev in apps/api and apps/web.