How to deploy a Streamlit app without Docker

Streamlit is the fastest way to put a UI on a Python script, and it is genuinely good at it. It is also opinionated in ways that only become visible when you move it off your laptop: it binds to localhost by default, it holds a WebSocket open for the entire session, and it keeps all state in the process's memory.

None of those are problems. They are just facts you need to know before the first deploy, because each one produces a distinctive and confusing failure if you do not. Here is the whole path, in order.

Step 1: the start command, which is where most deploys fail

Streamlit defaults to binding on localhost and picking port 8501. Behind any hosting platform, both of those are wrong: the platform gives you a port to listen on, and it needs you reachable from outside your own loopback interface.

# The command that works. Both flags matter.
streamlit run app.py \
  --server.port $PORT \
  --server.address 0.0.0.0 \
  --server.headless true

# --server.address 0.0.0.0  : listen on all interfaces, not just loopback.
#                             Without it, the health check cannot reach you
#                             and the deploy fails as "app never came up".
# --server.port $PORT       : use the port the platform assigned.
# --server.headless true    : do not try to open a browser or print the
#                             "collecting usage stats" prompt on a server.

Step 2: deploy from the repo

Python apps are commands-first: the dependency install is inferred from your repository — requirements.txt, a Poetry or uv lockfile, a Pipfile — but the start command is never guessed, because uvicorn, gunicorn, a plain script, and Streamlit are too different to assume one. You provide it.

pandastack app create \
  --name sales-dashboard \
  --git-url https://github.com/acme/sales-dashboard \
  --git-branch main \
  --start-command "streamlit run app.py --server.port \$PORT --server.address 0.0.0.0 --server.headless true"

pandastack app deploy <app-id> --follow

Pin your Python version in the repo rather than hoping the default matches your laptop. A .python-version file is read by the runtime installer, so the version you develop against is the version you deploy on.

# .python-version
3.12

# requirements.txt — pin, or a transitive upgrade will break a build
# on a Tuesday for no reason you can see.
streamlit==1.41.1
pandas==2.2.3
plotly==5.24.1
psycopg[binary]==3.2.3

Step 3: the WebSocket, and what it means for your hosting

Streamlit's whole interaction model is a persistent WebSocket. When you move a slider, the browser sends an event over that socket, your script reruns top to bottom on the server, and the new UI is pushed back. This has three practical consequences.

• Your host must support WebSockets, and so must anything in front of it. A proxy that only speaks HTTP will produce an app that loads and then does nothing when you click — the most confusing possible symptom, because the page renders fine.
• Idle timeouts disconnect users. A proxy that closes idle connections after sixty seconds will drop a user who is reading a chart, and Streamlit will show its reconnecting message. Check the idle timeout on every hop.
• A user's session is pinned to one process. There is no shared state between replicas, so load balancing across two instances without sticky sessions means a user's socket can land somewhere that has never heard of them.

Step 4: state lives in memory, and memory goes away

st.session_state is a dictionary in the server process. It survives reruns and it does not survive anything else — not a redeploy, not a restart, not the process being recycled. Anything a user would be upset to lose has to go somewhere durable.

import os
import streamlit as st
import psycopg

# Wrong for anything that matters: this is gone on the next deploy.
if "saved_reports" not in st.session_state:
    st.session_state.saved_reports = []

# Right: session_state for UI state, a database for facts.
@st.cache_resource
def get_conn():
    """One connection per process, reused across reruns.

    cache_resource is the important decorator here — without it, every
    slider move opens a new connection, and you exhaust the pool in
    about a minute of ordinary clicking.
    """
    return psycopg.connect(os.environ["DATABASE_URL"], autocommit=True)

@st.cache_data(ttl=300)
def load_sales(region: str):
    """Cached by argument value for five minutes. Reruns are constant in
    Streamlit, so an uncached query here means a database round trip on
    every single interaction."""
    with get_conn().cursor() as cur:
        cur.execute("SELECT day, revenue FROM sales WHERE region = %s", (region,))
        return cur.fetchall()

region = st.selectbox("Region", ["EMEA", "AMER", "APAC"])
st.line_chart(load_sales(region))

The distinction between the two cache decorators is worth learning properly, because getting it wrong is the usual cause of a Streamlit app that is mysteriously slow or that runs out of database connections. cache_resource is for things you want exactly one of per process — connections, clients, loaded models. cache_data is for return values keyed by arguments, and it copies the result so callers cannot mutate the cache.

Step 5: attaching a database

Most useful Streamlit apps read from somewhere. The connection string goes in as an environment variable, and is read at runtime rather than baked into anything.

# Create a database and read its connection URL.
pandastack database create --label dashboard-db
pandastack database connection <database-id>

# Attach it to the app. Updating an env var takes effect on the next deploy.
pandastack app create \
  --name sales-dashboard \
  --git-url https://github.com/acme/sales-dashboard \
  --env DATABASE_URL="postgres://..." \
  --start-command "streamlit run app.py --server.port \$PORT --server.address 0.0.0.0 --server.headless true"

The four failures you will actually hit

1. Deploy fails the health check, logs look fine. Missing --server.address 0.0.0.0. Nothing outside the process can reach loopback.
2. App loads but clicking does nothing. The WebSocket is not getting through. Check every proxy hop for WebSocket support and for an upgrade header being stripped.
3. Users get disconnected after a minute of reading. An idle timeout somewhere in front of the app. Raise it, or accept the reconnect.
4. Everything is slow and the database runs out of connections. Uncached work in the script body. Every interaction reruns the whole file top to bottom — wrap connections in cache_resource and queries in cache_data.

The short version

Deploying Streamlit is four flags and two decorators. Bind to 0.0.0.0 on the platform's port with headless mode on, make sure WebSockets get through every proxy between the browser and your process, keep durable state in a database rather than session_state, and cache your connections and queries so that constant reruns do not become constant load.

Then add authentication before it points at production data. Streamlit will not do that for you and the failure mode is not a broken app — it is a working one, on the internet, with your numbers in it.