Configuration

Accounts and connections (database)

Accounts (the Instagram profiles and YouTube channels Bongsu publishes to) and connections (how it reaches each platform) live in the database, per workspace. The dashboard doesn't manage every kind yet; add them with SQL (pnpm exec wrangler d1 execute bongsu --remote --command "…" in apps/cloudflare):

-- An Instagram account posted through Instagram's own API, its token in a secret named IG_TOKEN_TRAVEL
-- (site/docs/instagram-graph.md: creating the Meta app and getting the token)
INSERT INTO connections (id, workspace_id, provider, kind, secret_name, created_at, updated_at)
  VALUES ('ig_travel', 'default', 'instagram', 'oauth', 'IG_TOKEN_TRAVEL', unixepoch(), unixepoch());
INSERT INTO accounts (id, workspace_id, platform, handle, external_id, connection_id, capabilities, created_at, updated_at)
  VALUES ('demo_travel', 'default', 'instagram', 'demo_travel', '<Instagram user id>', 'ig_travel',
          '{"trialReels": true}', unixepoch(), unixepoch());

-- Or through Composio
INSERT INTO connections (id, workspace_id, provider, kind, external_ref, created_at, updated_at)
  VALUES ('c_travel', 'default', 'composio', 'composio', '<Composio connected-account id>', unixepoch(), unixepoch());
INSERT INTO accounts (id, workspace_id, platform, handle, external_id, connection_id, capabilities, created_at, updated_at)
  VALUES ('demo_running', 'default', 'instagram', 'demo_running', '<Instagram user id>', 'c_travel',
          '{}', unixepoch(), unixepoch());

-- A YouTube channel for Shorts comments, its OAuth JSON kept in a secret named YT_MAIN_OAUTH
INSERT INTO connections (id, workspace_id, provider, kind, secret_name, created_at, updated_at)
  VALUES ('c_main', 'default', 'youtube', 'oauth', 'YT_MAIN_OAUTH', unixepoch(), unixepoch());
INSERT INTO accounts (id, workspace_id, platform, handle, display_name, connection_id, created_at, updated_at)
  VALUES ('main', 'default', 'youtube', 'main', 'Main channel', 'c_main', unixepoch(), unixepoch());

An Instagram account without a working connection and user id is skipped: nothing is queued for it.

Caption rules

The caption check (packages/core/src/formats/caption-lint.ts) judges every caption against its platform's rules: Instagram's are a cap of 5 hashtags (a FAIL blocks approval), a first line that fits before the feed's fold at about 125 characters, and two language-bound heuristics (a concrete hook, one call to action) written for English, Spanish and Korean. An admin can change them per account in the dashboard's Accounts page, under Caption checks: Hashtags max (0–30), First line chars (50–500) and the Language checks switch. The values live in accounts.settings.captionRules, e.g. {"hashtagMax": 10, "languageChecks": false}; a missing field means the platform's default, and a field of the wrong type is ignored. POST /admin-api/accounts/:id with captionRules changes only the fields sent (null puts one back to the default). The PWA, the CLI's approve and the agent API all show the same checks.

Branding

One instance is one brand. The app's name and theme colour are read by the browser before anyone signs in (the install name, the tab title, the manifest, the browser bar), so they are inputs to the app build, not database settings. Nothing else changes: the design, the accent and the dashboard keep Bongsu's.

The icons are the seven files in packages/web/public: favicon.svg, favicon.ico, icon-192.png, icon-512.png, icon-maskable-192.png, icon-maskable-512.png and apple-touch-icon.png. pnpm brand makes all of them from one square SVG of your mark, so a fork rebrands in three steps:

1. Set BONGSU_APP_NAME and BONGSU_THEME_COLOR (below, for Cloudflare or Docker).
2. Make the icons: BONGSU_APP_NAME="Lighthouse" BONGSU_THEME_COLOR="#112233" pnpm brand your-mark.svg (from a subfolder, pnpm -w brand). The mark goes on the theme colour, inside the maskable icons' safe zone, and is used at tab sizes too. It needs Python 3 and the Cairo library (libcairo2 on Debian and Ubuntu, brew install cairo on macOS); the Python packages install once into a cache folder, not the repository. Commit the seven files.
3. Build the app (or the Docker image) with the same two variables.

The app's build checks the seven files and stops with the name of any one that is missing or at the wrong size, so a forgotten file can't ship a broken install icon. You can also replace them by hand, same names and sizes (keep the mark inside the central 80% of the maskable ones).

The project site (site/, pnpm site) takes its brand files from BRAND_DIR (default docs/assets/brand): mark.svg, mark-small.svg, lockup.svg, social-card.png, apple-touch-icon-180.png and favicon.ico.

What stays Bongsu's: the design's colours (tokens.css), which carry meaning (green means approved and running), and the dashboard's mark.

• Cloudflare: set the variables in the environment of the app build: BONGSU_APP_NAME="Lighthouse" BONGSU_THEME_COLOR="#112233" pnpm --filter @bongsu/web build (or pnpm build), and also in CI's variables if CI deploys.
• Docker: put both in .env (docker compose passes them as build arguments), or docker build --build-arg BONGSU_APP_NAME="Lighthouse" --build-arg BONGSU_THEME_COLOR="#112233" .; rebuild the image to apply.

Variables (wrangler files)

Secrets

Set on both Workers with wrangler secret put (never in the wrangler files).

/health lists missing secrets by name: the ones every instance needs, plus those its connections and media stores need. It also lists the media stores and their status, and isn't ok until at least one is set up and none is broken.

The media stores themselves (Google Drive, an S3-compatible bucket, the server's disk) aren't configured here: they're set up in the dashboard's Media page and kept in the database, their keys and grants encrypted with ENCRYPTION_KEY (Google Drive, S3-compatible buckets).

On Node and Docker

The same names, from the environment (.env with docker-compose; self-hosting.md), plus:

How many go out at once

Every 5 minutes the scheduler advances at most JOBS_PER_TICK publishing jobs, all accounts and workspaces together, the oldest due first. A video takes a few runs (Instagram processes it, then Bongsu publishes it) and holds its place until it's out, so items due at the same minute beyond that number go out over the next runs. Nothing is dropped, but a job more than 6 hours late waits for you instead (CATCH_UP_S).

• Cloudflare: 4. Each job costs a few subrequests and the free plan allows 50 per invocation. On the paid plan (1,000 subrequests) you can raise it: set JOBS_PER_TICK in [vars] of wrangler.cron.toml, the Worker that runs the schedules.
• Node and Docker: 20. No such limit there; set JOBS_PER_TICK in .env to change it.

Bongsu has no limit of its own per account. Instagram allows 100 posts per account per 24 hours through the API (Instagram); YouTube releases scheduled videos itself, so any number go public together.

The media stores' layout

The same in every store: a Drive's top folders, a bucket's key prefixes (under its folder, if it has one), the server's media directory.

<folder> is the workspace's media folder: a name made from the workspace's name (UPLOADS for a workspace kept from before this release), editable by its admins in Settings → Media. Bongsu never moves files when it changes.

Tunable limits (packages/core/src/constants.ts)

They are constants, not environment variables: change one and redeploy.

Time zones and digest

The database stores every time in UTC (unix seconds: plan_items.due_at, approvals.due_at, posted.published_at, jobs.due_at). Time zones only apply when a person or an agent enters or reads a time:

• The workspace's zone (an IANA name such as Asia/Seoul or Europe/Madrid) is the default for everyone in it, and the zone of its agent keys, notifications and daily digest. The digest goes out once a day from the workspace's digest hour.
• A user's own zone (users.timezone, NULL = the workspace's) changes only what that user sees and enters in the app: Settings → Time zone. Nothing planned moves when either zone changes.

"18:00" entered in a zone with daylight saving is 18:00 on that day's clock, before or after the change. A new instance starts on UTC at 08:00; change the workspace's zone with SQL until the dashboard has a setting:

UPDATE workspace_settings SET timezone = 'Europe/Madrid', digest_hour = 8, updated_at = unixepoch()
  WHERE workspace_id = 'default';