GeezerVison

bun run sim start | stop | restart # bring your install up / down / cycle

bun run sim update # pull/rebuild and apply Compose images

bun run sim status # what's installed and healthy

bun run sim logs # follow logs

bun run sim doctor # diagnose configuration problems

{/* TODO(screenshot): New External Client App form with the basic details filled in */}

</Step>

<Step>

In the OAuth settings section, enable OAuth (exact labels vary by Salesforce release)

Open the app's **Edit Settings** → **API (Enable OAuth Settings)** section and turn on **Enable OAuth**

</Step>

<Step>

Enter any placeholder **Callback URL** (e.g. `https://login.salesforce.com/services/oauth2/callback`) — it's required by the form but unused by this flow

Open your app in **External Client App Manager** and edit its **Policies**

</Step>

<Step>

Under **OAuth Policies** → **Client Credentials Flow**, check **Enable Client Credentials Flow** and set **Run As** to the integration user from step 1, then save

Under **OAuth Policies** → **Client Credentials Flow**, set **Run As** to the integration user from step 1, then save. That page holds only the Run As picker — the **Enable Client Credentials Flow** checkbox itself lives in **Edit Settings** → **OAuth Settings**, where you set it in step 2

{/* TODO(screenshot): OAuth Policies with the Run As integration user set under Client Credentials Flow */}

</Step>

```

Keep `server.key` somewhere safe — Sim stores it encrypted and never shows it again.

<Callout type="warn">

Salesforce requires an **RSA** key of at least 2048 bits for this flow; an ECDSA key is rejected. The uploaded certificate must also stay under 4 KB, which a 2048-bit self-signed cert comfortably is.

</Callout>

</Step>

<Step>

In **External Client App Manager** → your app → **Edit Settings** → **OAuth Settings**, enable the **JWT Bearer Flow** toggle and upload `server.crt`. On a legacy Connected App the equivalent is **Use digital signatures** with the same file

In **External Client App Manager** → your app → **Edit Settings** → **OAuth Settings**, turn on **Enable OAuth** (the JWT toggle does not appear until it is on), then **Enable JWT Bearer Flow**, and use **Upload Files** to upload `server.crt`. On a legacy Connected App the equivalent is **Use digital signatures** with the same file

</Step>

<Step>

Edit the app's **Policies** → **OAuth Policies** and set **Permitted Users** to **Admin approved users are pre-authorized**

</Callout>

</Step>

<Step>

Assign the integration user's **profile** or a **permission set** to the app (External Client App Manager → your app → **Policies** → manage profiles/permission sets), so that user is covered by the pre-authorization

Assign the integration user's **profile** or a **permission set** to the app, so that user is covered by the pre-authorization

<Callout type="warn">

Assign it through the **profile**, or through a **second permission set that does _not_ carry the Salesforce API Integration permission set license**. A permission set backed by that license cannot hold an **Assigned Connected Apps** / **Assigned External Client Apps** section at all, so the app can never be assigned from the same permission set that grants the user its object access. Getting this wrong produces exactly the `user hasn't approved this consumer` failure this step exists to prevent.

</Callout>

</Step>

<Step>

Copy the **Consumer Key** as in step 4. There is no consumer secret to copy — the JWT flow doesn't use one

- **Production:** `yourorg.my.salesforce.com`

- **Sandbox:** `yourorg--sandboxname.sandbox.my.salesforce.com`

- **Developer Edition:** `yourorg-dev-ed.develop.my.salesforce.com`

- **Developer Edition:** `yourorg.develop.my.salesforce.com` (Salesforce appends `-dev-ed` only when it generated the name for you)

Sim also accepts other partitioned My Domain hosts (`scratch`, `demo`, `patch`, `trailblaze`, `free`).

A permissions gap surfaces at run time as a Salesforce API error; fix it on the integration user's permission sets — no changes are needed in Sim.

<Callout type="warn">

On the **Salesforce Integration** (API-only) license specifically, SOQL and CRUD on standard objects are well supported, but two areas are not safe to assume:

- **Reports and dashboards** are unverified on this license. Salesforce documents neither a grant nor a prohibition. Test them in a sandbox before depending on them, and remember the user also needs access to the report or dashboard **folder**.

- **Anything Apex-related is blocked** — Apex Class Access is one of the permissions this license cannot hold, so Tooling API calls touching `ApexClass` will fail. Custom field and custom object management is unaffected.

If a workflow must run reports, a standard-seat integration user is the safe choice.

</Callout>

<Steps>

{ question: "Setup → App Manager → New Connected App is greyed out — why?", answer: "Salesforce disabled new Connected App creation by default (new orgs since Summer '25, all orgs since Spring '26); re-enabling it requires a Salesforce Support request. You don't need it — create an External Client App instead (Setup → External Client App Manager), which supports the same Client Credentials Flow and produces the same consumer key and secret." },

{ question: "Why do I have to enter a My Domain host instead of login.salesforce.com?", answer: "Salesforce only supports the Client Credentials Flow at your org's My Domain URL — login.salesforce.com and test.salesforce.com are explicitly rejected for this flow. Find yours under Setup → My Domain." },

{ question: "The credential validates but a specific tool fails with a permission error — why?", answer: "Every call runs as the Run As user, so the failing tool needs a permission that user doesn't have. Common gaps: Customize Application for custom field/object tools, Run Reports plus folder access for report tools, and object or field permissions for the records involved. Fix it on the integration user's permission sets and re-run." },

{ question: "Does this work with sandboxes and Developer Edition orgs?", answer: "Yes — enter the sandbox host (yourorg--sandboxname.sandbox.my.salesforce.com) or Developer Edition host (yourorg-dev-ed.develop.my.salesforce.com) as the My Domain host. Government/military domains (*.my.salesforce.mil) aren't currently supported." },

{ question: "Does this work with sandboxes and Developer Edition orgs?", answer: "Yes — enter the sandbox host (yourorg--sandboxname.sandbox.my.salesforce.com) or Developer Edition host (yourorg.develop.my.salesforce.com, with a -dev-ed suffix only if Salesforce generated the name for you) as the My Domain host. Government/military domains (*.my.salesforce.mil) aren't currently supported." },

{ question: "How do I rotate the credentials?", answer: "For client credentials, rotate the Consumer Secret from the app's OAuth settings (External Client App: Settings → OAuth Settings → Consumer Key and Secret; legacy Connected App: Manage Consumer Details), then update the credential in Sim with the new secret. For JWT bearer, generate a new key pair, upload the new certificate to the app, and paste the new private key into Sim. Either way, reconnecting asks you to restate the authentication method — Sim never returns a stored secret, so it cannot pre-select it for you." },

{ question: "What happens if the integration user is deactivated or frozen?", answer: "All token minting fails with invalid_grant and every workflow using the credential stops. Reactivate the user (or point Run As at a new integration user) and runs resume — no changes needed in Sim." },

]} />

docker compose -f docker-compose.prod.yml logs -f cron

<FAQ items={[

{ question: "How do I back up and restore the database?", answer: "Back up with: docker compose -f docker-compose.prod.yml exec db pg_dump -U postgres simstudio > backup.sql. Restore with: docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql. The database data is persisted in a Docker volume named postgres_data."},

{ question: "Can I customize the PostgreSQL credentials?", answer: "Yes. The docker-compose.prod.yml uses environment variable defaults: POSTGRES_USER (default: postgres), POSTGRES_PASSWORD (default: postgres), POSTGRES_DB (default: simstudio), and POSTGRES_PORT (default: 5432). Set these in your .env file to override them." },

]} />

<Tab value="Docker Compose">

docker compose -f docker-compose.prod.yml pull

docker compose -f docker-compose.prod.yml up -d

bun run sim update

docker compose -f docker-compose.prod.yml logs migrations

`bun run sim update` pulls the versions configured by `SIM_VERSION` (or `latest` when it is

unset), recreates the changed services, and keeps data volumes. It is equivalent to running

`docker compose pull` followed by `docker compose up -d`.

There is a short window where the app is unavailable while containers restart. Compose has no rolling-update mechanism — plan a maintenance window, or run Kubernetes if you need zero-downtime upgrades.

</Tab>

parseLastCredentialTag,

parseLastQuestionTag,

} from '@/app/workspace/[workspaceId]/home/components/message-content/components/special-tags'

import { nextSizerFloor } from '@/app/workspace/[workspaceId]/home/components/mothership-chat/sizer-floor'

import { QueuedMessages } from '@/app/workspace/[workspaceId]/home/components/queued-messages'

import {

UserInput,

const sizerRef = useRef<HTMLDivElement | null>(null)

const scrollerPaddingRef = useRef<{ top: number; bottom: number } | null>(null)

const sizerFloorAppliedRef = useRef(0)

const heldHighWaterRef = useRef(0)

const floorChatRef = useRef<string | undefined>(undefined)

const floorDrainRafRef = useRef(0)

useEffect(() => () => cancelAnimationFrame(floorDrainRafRef.current), [])

const sizer = sizerRef.current

const el = scrollElementRef.current

if (!sizer || !el) return

// A chat switch replaces the entire transcript, so a floor held for the

// previous one is meaningless — and its high-water mark would otherwise

// hand a short chat the tall chat's space for as long as the outgoing

// turn's `lastRowAnimating` keeps the floor engaged. Released outright

// rather than drained: the switch re-lands the viewport anyway, so there

// is no eased settle to preserve. A pending chat adopting its id is the

// SAME conversation, so it must not release mid-turn.

if (floorChatRef.current !== chatId) {

const isPendingPersist = floorChatRef.current === undefined && chatId !== undefined

floorChatRef.current = chatId

if (!isPendingPersist) {

cancelAnimationFrame(floorDrainRafRef.current)

floorDrainRafRef.current = 0

sizerFloorAppliedRef.current = 0

heldHighWaterRef.current = 0

sizer.style.minHeight = ''

}

}

if (!floorActive) {

heldHighWaterRef.current = 0

if (sizerFloorAppliedRef.current === 0) return

// A drain already in flight keeps its own rAF cadence — settle-burst

// commits re-enter this branch and must not add extra steps in layout,

}

}

const padding = scrollerPaddingRef.current

// Math.floor, not the raw float: a fractional min-height can round

// scrollHeight 1px ABOVE the scrolled-to extent, and that phantom 1px gap

// re-derives 1px higher after every chase step — a visible 1px/frame

// upward creep whenever the floor is what's holding scrollHeight.

const floor = Math.max(

0,

Math.floor(el.scrollTop + el.clientHeight - padding.top - padding.bottom)

)

const { floor, highWater } = nextSizerFloor({

previousHighWater: heldHighWaterRef.current,

appliedFloor: sizerFloorAppliedRef.current,

contentHeight: virtualizer.getTotalSize(),

scrollTop: el.scrollTop,

clientHeight: el.clientHeight,

paddingTop: padding.top,

paddingBottom: padding.bottom,

})

heldHighWaterRef.current = highWater

// Dead-band: the floor feeds back into its own inputs (a floored value can

// land a fraction BELOW the extent, the browser clamps scrollTop, and the

// next commit re-derives from the clamped position — a visible ~1px×N

import { describe, expect, it } from 'vitest'

import { nextSizerFloor } from '@/app/workspace/[workspaceId]/home/components/mothership-chat/sizer-floor'

const PADDING = { paddingTop: 16, paddingBottom: 8 }

const PINNED = { scrollTop: 1424, clientHeight: 600, ...PADDING }

describe('nextSizerFloor', () => {

it('follows the scrolled-to extent while it stays under the high-water mark', () => {

const { floor } = nextSizerFloor({

...PINNED,

previousHighWater: 5000,

appliedFloor: 0,

contentHeight: 5000,

})

expect(floor).toBe(2000)

})

it('floors fractional scroll offsets down so the sizer cannot round above the extent', () => {

const { floor } = nextSizerFloor({

scrollTop: 100.7,

clientHeight: 600,

...PADDING,

previousHighWater: 5000,

appliedFloor: 0,

contentHeight: 5000,

})

expect(floor).toBe(676)

})

it('never returns a negative floor for a container smaller than its padding', () => {

const { floor } = nextSizerFloor({

scrollTop: 0,

clientHeight: 8,

...PADDING,

previousHighWater: 500,

appliedFloor: 0,

contentHeight: 500,

})

expect(floor).toBe(0)

})

it('never exceeds the content height when the transcript is shorter than the viewport', () => {

const { floor } = nextSizerFloor({

scrollTop: 0,

clientHeight: 600,

...PADDING,

previousHighWater: 0,

appliedFloor: 0,

contentHeight: 180,

})

expect(floor).toBe(180)

})

it('holds the high-water mark when content re-measures smaller mid-turn', () => {

const { floor, highWater } = nextSizerFloor({

...PINNED,

previousHighWater: 2000,

appliedFloor: 2000,

contentHeight: 1940,

})

expect(highWater).toBe(2000)

expect(floor).toBe(2000)

})

it('carries undrained debt across a turn boundary that interrupts the drain', () => {

const { floor, highWater } = nextSizerFloor({

...PINNED,

previousHighWater: 0,

appliedFloor: 1985,

contentHeight: 1940,

})

expect(highWater).toBe(1985)

expect(floor).toBe(1985)

})

it('raises the high-water mark as content grows', () => {

const { highWater } = nextSizerFloor({

...PINNED,

previousHighWater: 1200,

appliedFloor: 1200,

contentHeight: 1600,

})

expect(highWater).toBe(1600)

})