---
name: busy-setup
description: Set up a self-hosted Busy hub on Vercel from a public clone or fork, with an empty database, private Blob store, own bot image, domains and first bot.
title: busy-setup
canonical_url: https://skilld.dev/gh/matisolina/busy/busy-setup
last_updated: 2026-11-12T03:00:58.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install matisolina/busy/busy-setup`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/busy-setup`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/matisolina/busy/busy-setup) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/busy-setup`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/busy-setup --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/busy-setup --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Set up Busy

Busy runs in the operator's accounts. The Next.js hub deploys each bot as a
separate Vercel project using Eve and Vercel Sandbox. The repository includes
all source, bot instructions and built-in skills; each installation supplies
its own credentials and infrastructure.

Work in order. Run authorized commands where possible. Ask only for unavailable
accounts, credentials or domains. Never put secrets in chat, command arguments
or commits. Use hidden prompts or the provider's UI. Do not source `.env.local`
in a shell: password hashes contain literal `$` separators. Load it through
Node's `--env-file` instead.

## Prerequisites

- Node.js 24.15 or later, Corepack and the pnpm version pinned in `package.json`.
- A Vercel team with access to Sandbox, Queues, Schedules, Blob, Container
  Registry and AI Gateway. These services have their own limits and costs.
- An empty Postgres database, such as one provisioned through Vercel Marketplace.
- Docker with Buildx to publish the bot computer image.
- An HTTPS hub domain, a wildcard bot domain and a separate HTTPS origin for
  MCP Apps. The two HTTPS origins must be different.

## 1. Clone and install

```sh
git clone https://github.com/MatiSolina/busy.git
cd busy
corepack enable
pnpm install --frozen-lockfile
```

Fork first if the operator wants automatic Git deployments or changes to the
source. Use the root README's local setup for a UI-only development instance.
Running bots requires the Vercel resources below.

## 2. Create and link the hub

Import the fork into Vercel. Name the project **busy-hub**: the development
relay validates that name in its OIDC subject. Set the root directory to
`apps/hub` and enable access to source files outside that root so the build can
bundle `templates/bot`. Keep the repository's build command and Node.js 24.

Then link the clone to that project, choosing the operator's own team:

```sh
cd apps/hub
pnpm exec vercel login
pnpm exec vercel link
```

Record the team's ID and slug for `VERCEL_TEAM_ID` and `VERCEL_TEAM_SLUG`.
Inspect `.vercel/project.json` and the selected team before writing variables;
never reuse another installation's project link.

## 3. Provision Postgres and private Blob

Create a new empty Postgres database and connect it to the hub. Configure
`DATABASE_URL` for runtime and `DATABASE_URL_UNPOOLED` for direct migrations.
Create a **private Vercel Blob store** in the same account and connect it to the
hub so `BLOB_READ_WRITE_TOKEN` is supplied. The hub uses it for chat files,
library objects and optional desktop release archives.

Pull the environment into the ignored local file and initialize the database:

```sh
pnpm exec vercel env pull .env.local --environment=development --yes
NODE_OPTIONS=--env-file=.env.local pnpm db:init --dry-run
NODE_OPTIONS=--env-file=.env.local pnpm db:init
```

Use the connection string for the intended new database. If production uses a
separate database, initialize that empty database too, loading its connection
string privately. Do not assume a development database initializes production.

`db:init` refuses existing public tables/views and applies the baseline and all
SQL migrations transactionally. It handles plain Postgres without Supabase's
Data API roles. `pnpm db:validate` validates the same baseline and migrations in
an offline PGlite database. Never use `drizzle-kit push` on an existing
installation: it can remove RLS and SQL-only constraints. Apply reviewed pending
SQL migrations for upgrades instead.

## 4. Store account and signing secrets

From `apps/hub`:

```sh
pnpm exec node scripts/setup-secrets.ts
pnpm exec node scripts/gen-hub-key.ts
```

The first script asks the operator for a username, password of at least 12
characters and a Vercel token scoped to their team. It writes the password hash,
random per-environment session secrets, production cron secret, Vercel token
and optional Token Pass key into the linked project. The signing-key script
creates a sensitive production `HUB_SIGNING_KEY` and prints only its public
half. It refuses to overwrite an existing key. Never copy the production
signing key into a development file or another installation.

## 5. Publish the bot computer image

Follow [the image guide](../../docs/bot-base-image.md). From the repository root,
log in to the intended Container Registry and build/push the included image
using an explicit repository owned by that team. Set `BOT_BASE_IMAGE` on the hub
to the resulting digest-pinned reference. Grant the bot projects read access
as described by the registry for that team. The hub forwards the image setting
to every bot; it has no fallback to the maintainer's private image.

## 6. Set the remaining production variables

Use `pnpm exec vercel env add NAME production` to enter values interactively.
Add development values separately when local work needs them. The full variable
reference is [apps/hub/.env.example](../../apps/hub/.env.example).

| Variable | Meaning |
| --- | --- |
| `HUB_URL` | Hub HTTPS origin, for example `https://busy.example.com` |
| `BOTS_DOMAIN` | Wildcard bot domain, for example `bots.example.com` |
| `VERCEL_TEAM_ID` / `VERCEL_TEAM_SLUG` | Operator's team ID and slug |
| `BOT_BASE_IMAGE` | Own image pinned to `@sha256:` plus its digest |
| `DATABASE_URL` | Own runtime Postgres connection |
| `BLOB_READ_WRITE_TOKEN` | Own private Blob store credential |
| `MCP_APP_SANDBOX_ORIGIN` | A different HTTPS origin serving `/mcp-app-sandbox` from this app |

Make the second sandbox domain an alias of the hub deployment so it serves the
sandbox route on a different origin. Add the hub domain in Vercel and configure
the bots' wildcard domain for the operator's team. Check DNS and ownership
before creating bots.

The default model path uses Vercel AI Gateway with project OIDC. Enable billing
and access in that account. Optional Sign in with Vercel uses the operator's
own `VERCEL_APP_CLIENT_ID`, `VERCEL_APP_CLIENT_SECRET` and `BUSY_VERCEL_USERS`.
Without it, use the username and password configured above. Connect any
additional providers through the hub with the operator's own accounts.

## 7. Deploy and create the first bot

Deploy the configured hub from the linked repository and confirm the deployment
is Ready. For a CLI deployment from the complete monorepo, use the linked hub
project and its configured root directory:

```sh
pnpm exec vercel deploy --prod
```

Open `HUB_URL`, sign in, then choose **Create bot**. The hub deploys the bot to a
new project in the operator's team. Wait for Ready and send a message. Verify
the response and computer rather than treating a completed build as a runtime
check. No end-to-end bot run is implied by the repository's offline tests.

## Desktop client

The source client can target the operator's hub with `BUSY_URL`. Follow
[docs/desktop.md](../../docs/desktop.md) to run it or build the macOS archive.
The hub's `/install` route works only after the operator has published their
archive and configured `BUSY_APP_VERSION` and `BUSY_APP_SHA256`; it is optional
for web use.

## Troubleshooting

- Run `pnpm doctor:vercel` from the repository root and inspect `checks[].status`.
- Missing environment variables identify the configuration step to revisit.
- Missing `BOT_BASE_IMAGE` requires publishing the team's own image first.
- File/library failures need a private Blob store and its own token.
- Database errors need the intended database and successful `db:init`.
- Inspect the bot project's deployment log for a failed build or prewarm.
- Never enable `BUSY_DEV_NO_AUTH=1` on a public deployment.
