writing-streamlit-apps

Writing Streamlit apps for the PostHog sandbox

The source you write becomes app.py at the root of a sandboxed Streamlit 1.31 runtime. Deployment mechanics (create/start/share) are the managing-streamlit-apps skill; this one is about the code.

Reading PostHog data: posthog_apps.query()

The one and only data door is the in-sandbox bridge:

import posthog_apps

df = posthog_apps.query("SELECT event, count() FROM events GROUP BY event LIMIT 10")

• Takes a HogQL string, returns a pandas DataFrame.
• Raises RuntimeError on failure. The message is deliberately generic ("Query execution failed") — the bridge does not return query internals to the sandbox, so you cannot diagnose a bad query from inside the app. Catch it and render with st.error(str(e)) so viewers get a message instead of a stack trace, and test queries in the SQL editor where real errors are visible.
• import posthog does NOT exist in the sandbox — the module is posthog_apps, deliberately distinct from the posthog-python SDK's name.
• The bridge is pre-authenticated to the app's project; user code never sees a token, and there is nothing to configure.
• Queries run with server-side caps (30 s execution, 256 MB memory) that don't scale with sandbox sizing — so bound time ranges, LIMIT results, and aggregate in HogQL rather than pulling raw events into pandas.

Design for Streamlit's rerun model

Streamlit reruns the whole script top to bottom on every widget interaction. Two consequences:

1. Cache every bridge call — uncached, one slider drag re-fires every query:

   @st.cache_data(ttl=300, show_spinner="Running query...")
   def run_query(hogql: str) -> pd.DataFrame:
       return posthog_apps.query(hogql)
   

2. Use st.session_state for anything that must survive reruns — accumulated selections, pagination cursors, "last refreshed" stamps. Module-level variables reset on every interaction.

Widgets drive parameters naturally, but never interpolate a free-text widget value into HogQL. The bridge runs your query with the version author's data access, and anyone who can view the app drives those widgets — a raw st.text_input spliced into a query hands viewers the author's access to write their own. Constrain the input instead: pick from a fixed list you control (st.selectbox over known values), or coerce to a type that can't carry SQL (int(days), a date from st.date_input), and validate before it reaches the query.

Layout and charts

• st.set_page_config(page_title=..., layout="wide") first — the default narrow layout wastes most of the screen for data apps.
• Structure with st.columns for side-by-side metrics, st.tabs for alternate views, st.expander for detail sections; st.metric for headline numbers.
• Charts: st.plotly_chart(fig, use_container_width=True) with plotly express is the reliable default; st.dataframe(df, use_container_width=True) for tables. matplotlib/seaborn also work via st.pyplot.

What's installed

The image ships Python 3.11 with: streamlit 1.31, pandas, numpy, polars, plotly, matplotlib, seaborn, scipy, scikit-learn, pyarrow, duckdb, requests, beautifulsoup4, lxml, sqlalchemy, aiohttp. There is no way to add dependencies: the sandbox never runs pip (a deliberate security posture — no arbitrary package code at boot), and a requirements.txt in an uploaded zip is tolerated but dropped. Only import what's listed above.

Structure and runtime constraints

• app.py is the entry point. Via the MCP set-source flow your source IS app.py. Helper modules and data files can ship next to it through the files (text) and assets (base64) maps; import utils works because Streamlit puts the app directory on sys.path, but the process does not run inside that directory, so open data files via Path(__file__).parent / "data/events.parquet", never a bare relative path. Keep bundled data small: it is sent inline as JSON on every set-source call.
• The sandbox is ephemeral: anything written to disk disappears on stop/restart. Don't build state on files; recompute from queries (with caching) or hold it in st.session_state.
• Your code runs as an unprivileged user; there's no posthog SDK, no way to pass your own environment variables or secrets to the app, and no expectation of general network egress. Don't read from os.environ — anything there belongs to the sandbox runtime, not your app. Design around posthog_apps.query() as the data source.

A minimal well-shaped app

import pandas as pd
import plotly.express as px
import posthog_apps
import streamlit as st

st.set_page_config(page_title="Events overview", layout="wide")
st.title("Events overview")


@st.cache_data(ttl=300, show_spinner="Running query...")
def run_query(hogql: str) -> pd.DataFrame:
    return posthog_apps.query(hogql)


# A slider is bounded and coerced to int, so it is safe to interpolate.
days = int(st.slider("Days to show", 1, 30, 7))
try:
    daily = run_query(
        f"""
        SELECT toDate(timestamp) AS day, count() AS events
        FROM events
        WHERE timestamp >= now() - INTERVAL {days} DAY
        GROUP BY day ORDER BY day
        """
    )
    st.plotly_chart(px.bar(daily, x="day", y="events"), use_container_width=True)
except RuntimeError as e:
    st.error(str(e))