Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(tasks): document 16 GiB self-driving sandboxes, raise tsgo floor (#122640)

Alessandro Pogliaghi2b945f7b5d95
diff --git a/docs/internal/cloud-task-sandbox.md b/docs/internal/cloud-task-sandbox.md
index dbf3d945d7bc..c23c21b066e4 100644
--- a/docs/internal/cloud-task-sandbox.md
+++ b/docs/internal/cloud-task-sandbox.md
@@ -4,14 +4,18 @@ Applies only inside a PostHog Tasks cloud run, on the prebaked `posthog-dev-stac
Local developers and CI are unaffected by everything on this page.
`POSTHOG_TASK_RUN_ID` is set in that environment.
-Sandboxes using this image receive at least 32 GiB of RAM, including when automatic preview startup is disabled.
-Memory overrides above 32 GiB are preserved; lower overrides are raised to 32 GiB.
+User-created runs on this image receive at least 64 GiB of RAM.
+Self-driving runs, such as signal reports and scouts, receive 16 GiB.
## Booting the stack
Run `bootstrap-dev-stack` first — it restores the compose host aliases and starts dockerd.
Then `uv sync`, `source .venv/bin/activate`, `hogli start -y -d`, and `hogli wait`.
+On a 16 GiB VM the full `hogli start` stack takes about 12 GiB and leaves no room for tsgo, Jest, or pytest.
+Unless the task needs the running app, start only the datastores after `bootstrap-dev-stack`:
+`docker compose -f docker-compose.dev.yml up -d --no-build db redis7 zookeeper kafka clickhouse objectstorage`, then `bin/wait-for-docker objectstorage`.
+
Always detached. The sandbox has no TTY, and phrocs under a pseudo-TTY grows in memory until the OOM killer takes it.
The detached start returns while the stack is still booting, so `hogli wait` is what blocks until every process is ready.
diff --git a/docs/published/handbook/engineering/ai/sandboxed-agents.md b/docs/published/handbook/engineering/ai/sandboxed-agents.md
index e4cb38d79f06..bd72346c422c 100644
--- a/docs/published/handbook/engineering/ai/sandboxed-agents.md
+++ b/docs/published/handbook/engineering/ai/sandboxed-agents.md
@@ -520,6 +520,9 @@ at boot and dockerd does not autostart. Run the baked `bootstrap-dev-stack` help
required — the sandbox has no TTY, and running phrocs under a pseudo-TTY makes it balloon in
memory until it is OOM-killed — and the detached start returns while the stack is still booting,
so `hogli wait` is what blocks until every process reports ready.
+On a 16 GiB self-driving run the full stack takes about 12 GiB and leaves no room for tests,
+so the agent should start only the datastores unless the task needs the running app
+(see `docs/internal/cloud-task-sandbox.md`).
Provisioning also fires that helper detached as soon as the sandbox is up (best-effort, only on
runs that booted the PostHog-published `posthog-dev-stack` image itself — never a user-authored
diff --git a/frontend/bin/typescriptCheckPlan.mjs b/frontend/bin/typescriptCheckPlan.mjs
index b069497bb881..a7c07d593dcf 100644
--- a/frontend/bin/typescriptCheckPlan.mjs
+++ b/frontend/bin/typescriptCheckPlan.mjs
@@ -1,7 +1,7 @@
const GIB = 1024 ** 3
const UNTUNED_MIN_HEADROOM_GIB = 24
const MIN_GOMEMLIMIT_GIB = 6
-const HEADROOM_AT_MIN_GOMEMLIMIT_GIB = 9
+const HEADROOM_AT_MIN_GOMEMLIMIT_GIB = 12
export function tsgoPlan(headroom) {
if (headroom === null || headroom >= UNTUNED_MIN_HEADROOM_GIB * GIB) {
diff --git a/frontend/bin/typescriptCheckPlan.test.ts b/frontend/bin/typescriptCheckPlan.test.ts
index a074aae7e31c..f69064067723 100644
--- a/frontend/bin/typescriptCheckPlan.test.ts
+++ b/frontend/bin/typescriptCheckPlan.test.ts
@@ -7,8 +7,8 @@ describe('tsgoPlan', () => {
['unknown headroom', null, { mode: 'full' }],
['24 GiB of headroom', 24 * GIB, { mode: 'full' }],
['20 GiB of headroom', 20 * GIB, { mode: 'constrained', goMemLimit: '10GiB', headroomGib: '20.0' }],
- ['9 GiB of headroom', 9 * GIB, { mode: 'constrained', goMemLimit: '6GiB', headroomGib: '9.0' }],
- ['8 GiB of headroom', 8 * GIB, { mode: 'refuse', message: expect.stringContaining('Only 8.0 GiB') }],
+ ['12 GiB of headroom', 12 * GIB, { mode: 'constrained', goMemLimit: '6GiB', headroomGib: '12.0' }],
+ ['11 GiB of headroom', 11 * GIB, { mode: 'refuse', message: expect.stringContaining('Only 11.0 GiB') }],
['negative headroom', -1 * GIB, { mode: 'refuse', message: expect.stringContaining('Only 0.0 GiB') }],
])('with %s', (_, headroom, expected) => {
expect(tsgoPlan(headroom)).toEqual(expected)
diff --git a/frontend/src/AGENTS.md b/frontend/src/AGENTS.md
index 2cfa894b2f91..5be7cb0fa07b 100644
--- a/frontend/src/AGENTS.md
+++ b/frontend/src/AGENTS.md
@@ -120,7 +120,7 @@ A whole subtree of machine data (an event feed, an ID column) opts out at its co
These are slow; run them at the right moment, not after every edit.
-- **TypeScript check** — `pnpm --filter=@posthog/frontend typescript:check` (runs `tsgo --noEmit` over the whole app; with under 24 GiB of memory headroom below the sandbox watchdog threshold it runs one checker under a Go heap limit, about three times slower, and under 9 GiB it refuses to start and tells you which background processes to stop). Rely on the editor/LSP while editing; run the full check **once before you call the work done**, not per-edit.
+- **TypeScript check** — `pnpm --filter=@posthog/frontend typescript:check` (runs `tsgo --noEmit` over the whole app; with under 24 GiB of memory headroom below the sandbox watchdog threshold it runs one checker under a Go heap limit, about three times slower, and under 12 GiB it refuses to start and tells you which background processes to stop). Rely on the editor/LSP while editing; run the full check **once before you call the work done**, not per-edit.
- **kea typegen** (inline types) — regenerates automatically via `typegen:watch` while the dev server runs (`./bin/start` / `hogli start`). If you must regen one logic without the server, use `pnpm --filter=@posthog/frontend typegen:file <path>`. **Don't routinely run the full `typegen:write`** — it's a heavy whole-repo pass (multi-GB heap).
All logic files use **inline types** by default: a generated `MakeLogicType` block sits above each `kea()` call, marked "Generated by kea-typegen". Agents may update those blocks (typegen reconciles them anyway); humans should let the typegen commands keep them updated. Connected values/actions carry a `// sourceLogic` comment and sort first, grouped by source logic.
- **`hogli build:openapi`** — only needed when you changed a **backend serializer/viewset**. A pure `.tsx`/`.ts` change never needs it. Don't run it speculatively.
diff --git a/products/tasks/backend/sandbox/images/hogli-shim.sh b/products/tasks/backend/sandbox/images/hogli-shim.sh
index 1397d107edda..e170183aea64 100644
--- a/products/tasks/backend/sandbox/images/hogli-shim.sh
+++ b/products/tasks/backend/sandbox/images/hogli-shim.sh
@@ -15,8 +15,12 @@ while [ "$dir" != "/" ]; do
" source .venv/bin/activate" \
"" \
"This image already ships a migrated Postgres and ClickHouse, plus a seeded" \
- "test_posthog database. Start them with 'hogli start -y -d && hogli wait' when" \
- "a test needs one. Never hand-roll a database container: it takes the ports the" \
+ "test_posthog database. When a test needs them and the task does not need the" \
+ "running app, start only the datastores:" \
+ " docker compose -f docker-compose.dev.yml up -d --no-build db redis7 zookeeper kafka clickhouse objectstorage" \
+ " bin/wait-for-docker objectstorage" \
+ "The full 'hogli start -y -d && hogli wait' stack takes about 12 GiB, too much" \
+ "for a 16 GiB VM. Never hand-roll a database container: it takes the ports the" \
"baked stack needs, and pytest then replays the whole migration history." \
"" \
"See docs/internal/cloud-task-sandbox.md."