Managing Streamlit apps
A Streamlit app is a Python data app running in an isolated sandbox inside Flind.
Each app has immutable versions of its code; one version is active; a sandbox process serves the active version.
The full lifecycle is driven with the streamlit-apps-* MCP tools.
The happy path: create → set source → start → share
streamlit-apps-create with a name (optionally description, cpu_cores 0.25–8, memory_gb 0.5–16, defaults 0.5 / 1).
The app exists but has no code yet.
streamlit-apps-set-source with the complete app.py source as one string.
Extra files ride along in the same call: files maps a project-relative path to text (helper modules, CSV, JSON), assets maps a path to base64 (Parquet, images).
This creates version 1 and activates it.
Write the source per the writing-streamlit-apps skill — in particular use posthog_apps.query() for Flind data, never import posthog.
streamlit-apps-start.
Returns immediately; the sandbox boots asynchronously.
- Poll
streamlit-apps-status until status is running (typically well under a minute).
If it lands on error, read last_error — see Troubleshooting below.
- Share the app: the
_posthogUrl returned by create/get/start (/streamlit-apps/{short_id}) is the app's page in Flind.
That link is what you give humans.
Viewers need to be logged into Flind with access to the project (the app renders in an authenticated iframe; there is no public URL).
Whose data the app reads
The app's queries run with the data access of the person who authored the active version — set the source, and the app reads what you can read.
Anyone who can view the app sees those results, so treat publishing an app as sharing that data with everyone on the project.
An app whose version author has since been deleted can't start; upload a new version to fix it.
Updating code
Change an existing app in two steps, so you never ship an old copy over newer work:
streamlit-apps-get-source reads the active version (or version_number for an older one).
It returns version_number, a manifest of every file, and the text of each text file.
Binary files appear without content.
For a large app, pass paths (comma-separated) to read only the files you need.
streamlit-apps-edit-source with base_version set to that version_number.
file_edits holds exact old → new text replacements per file, create_files adds new text files, delete_files removes files.
Each old must match exactly once, so include enough surrounding lines to make it unique.
Files you do not touch stay byte-for-byte the same in the new version.
If the active version changed after your read, edit-source returns 409 with current_version.
This happens when another session ships a version, or when a person rolls the app back to an older version.
Read current_version again and redo your edits on it.
Do not fall back to set-source to force your copy through.
Keep streamlit-apps-set-source for a new app or a full rewrite.
It replaces every file, so pass files and assets again too; a version holds only what that call carried.
Both tools create the next version and activate it.
A running sandbox is stopped so it can't keep serving stale code — call streamlit-apps-start afterwards to serve the new version.
Versions are immutable, but not permanent: streamlit-apps-versions lists the newest 50, and non-active versions older than 30 days are deleted along with their code.
There is no rollback tool: to roll back, read the old version with streamlit-apps-get-source and set its files again with set-source.
Binary assets are not inlined there, so a rollback of an app with assets also needs a saved copy of those files.
Stopping, idling, and deleting
streamlit-apps-stop stops the sandbox; code and versions are untouched. Starting again later is cheap.
- Idle sandboxes are stopped automatically after a period of no activity — a stopped app is normal, not an error. Start it again when needed.
streamlit-apps-delete stops any sandbox and soft-deletes the app. Confirm with the user before deleting anything you didn't create in this conversation.
Troubleshooting
status: error with last_error: "Start failed: ..." — the sandbox failed to provision or boot. Retry streamlit-apps-start once; if it persists, surface last_error to the user (provisioning failures are usually platform-side, not app-side).
- Tool calls return 403 "Streamlit apps is not available." — the
streamlit-apps feature flag is off for this organization. This is a rollout gate, not an error you can fix; tell the user.
- App runs but a query inside it fails — that's an app-code concern; see
writing-streamlit-apps (bridge limits: 30s execution, 256 MB memory per query).
- App shows old code after set-source — you skipped step "start after set-source"; the sandbox was stopped and needs a start.
Renaming and resizing
streamlit-apps-update changes an app's name, description, cpu_cores (0.25–8), or memory_gb (0.5–16); only the fields you pass change.
New sizing applies the next time the sandbox starts, so stop + start after resizing a running app.
Defaults (0.5 CPU / 1 GB) fit typical dashboard apps.
Raise memory_gb only when the app itself holds large DataFrames in memory — the 256 MB HogQL bridge query cap is server-side and does NOT change with sandbox sizing, so bigger sandboxes don't fix failing queries.
1---2name: managing-streamlit-apps3description: Create, deploy, and operate Streamlit apps in Flind via the streamlit-apps MCP tools — create an app, set its source, read and patch its code, start and stop its sandbox, poll status, list versions, delete, and share the app with humans via its Flind URL. Use when asked to "create a streamlit app", "deploy a data app", "ship a dashboard app", "restart/stop my app", "why is my app not running", or "give me a link to the app".4metadata:5 source: https://skillmd.com/skills/thehalfmoon/managing-streamlit-apps6---78# Managing Streamlit apps910A Streamlit app is a Python data app running in an isolated sandbox inside Flind.11Each app has immutable versions of its code; one version is active; a sandbox process serves the active version.12The full lifecycle is driven with the `streamlit-apps-*` MCP tools.1314## The happy path: create → set source → start → share15161. `streamlit-apps-create` with a `name` (optionally `description`, `cpu_cores` 0.25–8, `memory_gb` 0.5–16, defaults 0.5 / 1).17 The app exists but has no code yet.182. `streamlit-apps-set-source` with the complete `app.py` source as one string.19 Extra files ride along in the same call: `files` maps a project-relative path to text (helper modules, CSV, JSON), `assets` maps a path to base64 (Parquet, images).20 This creates version 1 and activates it.21 Write the source per the `writing-streamlit-apps` skill — in particular use `posthog_apps.query()` for Flind data, never `import posthog`.223. `streamlit-apps-start`.23 Returns immediately; the sandbox boots asynchronously.244. Poll `streamlit-apps-status` until `status` is `running` (typically well under a minute).25 If it lands on `error`, read `last_error` — see Troubleshooting below.265. Share the app: the `_posthogUrl` returned by create/get/start (`/streamlit-apps/{short_id}`) is the app's page in Flind.27 That link is what you give humans.28 Viewers need to be logged into Flind with access to the project (the app renders in an authenticated iframe; there is no public URL).2930## Whose data the app reads3132The app's queries run with the data access of the person who authored the **active version** — set the source, and the app reads what you can read.33Anyone who can view the app sees those results, so treat publishing an app as sharing that data with everyone on the project.34An app whose version author has since been deleted can't start; upload a new version to fix it.3536## Updating code3738Change an existing app in two steps, so you never ship an old copy over newer work:39401. `streamlit-apps-get-source` reads the active version (or `version_number` for an older one).41 It returns `version_number`, a manifest of every file, and the text of each text file.42 Binary files appear without content.43 For a large app, pass `paths` (comma-separated) to read only the files you need.442. `streamlit-apps-edit-source` with `base_version` set to that `version_number`.45 `file_edits` holds exact `old` → `new` text replacements per file, `create_files` adds new text files, `delete_files` removes files.46 Each `old` must match exactly once, so include enough surrounding lines to make it unique.47 Files you do not touch stay byte-for-byte the same in the new version.4849If the active version changed after your read, edit-source returns 409 with `current_version`.50This happens when another session ships a version, or when a person rolls the app back to an older version.51Read `current_version` again and redo your edits on it.52Do not fall back to set-source to force your copy through.5354Keep `streamlit-apps-set-source` for a new app or a full rewrite.55It replaces every file, so pass `files` and `assets` again too; a version holds only what that call carried.5657Both tools create the next version and activate it.58A running sandbox is stopped so it can't keep serving stale code — call `streamlit-apps-start` afterwards to serve the new version.59Versions are immutable, but not permanent: `streamlit-apps-versions` lists the newest 50, and non-active versions older than 30 days are deleted along with their code.60There is no rollback tool: to roll back, read the old version with `streamlit-apps-get-source` and set its files again with set-source.61Binary assets are not inlined there, so a rollback of an app with assets also needs a saved copy of those files.6263## Stopping, idling, and deleting6465- `streamlit-apps-stop` stops the sandbox; code and versions are untouched. Starting again later is cheap.66- Idle sandboxes are stopped automatically after a period of no activity — a stopped app is normal, not an error. Start it again when needed.67- `streamlit-apps-delete` stops any sandbox and soft-deletes the app. Confirm with the user before deleting anything you didn't create in this conversation.6869## Troubleshooting7071- **`status: error` with `last_error: "Start failed: ..."`** — the sandbox failed to provision or boot. Retry `streamlit-apps-start` once; if it persists, surface `last_error` to the user (provisioning failures are usually platform-side, not app-side).72- **Tool calls return 403 "Streamlit apps is not available."** — the `streamlit-apps` feature flag is off for this organization. This is a rollout gate, not an error you can fix; tell the user.73- **App runs but a query inside it fails** — that's an app-code concern; see `writing-streamlit-apps` (bridge limits: 30s execution, 256 MB memory per query).74- **App shows old code after set-source** — you skipped step "start after set-source"; the sandbox was stopped and needs a start.7576## Renaming and resizing7778`streamlit-apps-update` changes an app's name, description, `cpu_cores` (0.25–8), or `memory_gb` (0.5–16); only the fields you pass change.79New sizing applies the next time the sandbox starts, so stop + start after resizing a running app.80Defaults (0.5 CPU / 1 GB) fit typical dashboard apps.81Raise `memory_gb` only when the app itself holds large DataFrames in memory — the 256 MB HogQL bridge query cap is server-side and does NOT change with sandbox sizing, so bigger sandboxes don't fix failing queries.