Deploy a Streamlit app
Data apps that never sleep, private to your team. Gradio too.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/streamlit/prompt.txt | ssh exe.dev new --prompt=/dev/stdinStreamlit and Gradio turn a Python script into a web app: a dashboard over
your data, an internal tool, a model demo. This page gives that app a
home. One exe.dev VM runs it under systemd, keeps its data on a real
disk, and deploys every git push. exe.dev puts it on HTTPS behind its
own login, so it's private from the start, and it tells your app who is
looking, in the X-ExeDev-Email header: no passwords, no st.login
setup.
Unlike Streamlit Community Cloud or Hugging Face Spaces, nothing sleeps: the app is up when your team opens it on Monday morning, with the caches it built and the files it wrote still there. Scheduled jobs refresh the data, LLM calls go through exe.dev's gateway with no API key on the VM, and Shelley, the agent on the VM, can read the logs and fix the code. Bring an app from GitHub or a Hugging Face Space, or start from a small dashboard with all of that wired up.
What you get#
- Your app, or a new Streamlit starter dashboard, running as
app.serviceon 127.0.0.1:8000 and enabled to start after a reboot. git push exe maindeploys: the hook builds a new release in~/releaseswith uv, runs a Streamlit app once headless with Streamlit's AppTest, switches~/appto it, restarts, and checks it answers. A failed deploy rejects the push and leaves the running version up.- The app private behind exe.dev login, reading the viewer's email from the
X-ExeDev-Emailheader (st.context.headersin Streamlit,gr.Requestin Gradio). - Settings and secrets outside the repository, mode 600, in
~/app.envand~/.streamlit/secrets.toml(st.secrets). - Data in
~/data, refreshed every hour byapp-refresh.timerin the starter, and backed up every night to~/backups, with a backup restored and checked in a scratch directory.
What's running, and where
https://my-streamlit.exe.xyz/
your app, for you and the people you share it with
my-streamlit.exe.xyz:app.git
git push exe main deploys
streamlit run on 127.0.0.1:8000, as app.service under systemd
~/app/.venv
git push installs, runs the app once headless, restarts, and checks; a failure rejects the push
app-refresh.timer runs refresh.py every hour
Deploy with Shelley#
Click Deploy and Shelley will set up Streamlit on a new VM, then check that it works. No config-file wrangling required.
Have these ready; Shelley asks for them:
REPO: the app to deploy: a GitHub repository (owner/name or a URL), a Hugging Face Space URL, ornewto start from a small Streamlit dashboard
Prefer a terminal?
curl -fsSL \
https://exe.dev/deploy/streamlit/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhen it's done, run this on your computer (only you can):
git clone -o exe my-streamlit.exe.xyz:app.git # if you started fresh
git remote add exe my-streamlit.exe.xyz:app.git # or, in your own app's checkoutWhat Shelley is told
REPO=<fill-this-in>
Set up Streamlit on this VM by following the exe.dev recipe at https://exe.dev/deploy/streamlit.md from top to bottom.
The values at the top of this message are mine:
- REPO: the app to deploy: a GitHub repository (owner/name or a URL), a Hugging Face Space URL, or `new` to start from a small Streamlit dashboard
Ask me for any that still say <fill-this-in> before you need them.
The recipe's example VM name is my-streamlit. This VM's name is the output of `hostname`: use it wherever the recipe writes my-streamlit. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- Your app, or a new Streamlit starter dashboard, running as `app.service` on 127.0.0.1:8000 and enabled to start after a reboot.
- `git push exe main` deploys: the hook builds a new release in `~/releases` with uv, runs a Streamlit app once headless with Streamlit's AppTest, switches `~/app` to it, restarts, and checks it answers. A failed deploy rejects the push and leaves the running version up.
- The app private behind exe.dev login, reading the viewer's email from the `X-ExeDev-Email` header (`st.context.headers` in Streamlit, `gr.Request` in Gradio).
- Settings and secrets outside the repository, mode 600, in `~/app.env` and `~/.streamlit/secrets.toml` (`st.secrets`).
- Data in `~/data`, refreshed every hour by `app-refresh.timer` in the starter, and backed up every night to `~/backups`, with a backup restored and checked in a scratch directory.
Read the whole recipe, including the closed details, and follow "Set up
by hand" in order, skipping VM creation. The walkthrough above it is for
the owner afterwards. Ask for REPO first if it says <fill-this-in>.
For REPO=new, build the starter exactly as written. For a GitHub
repository or a Hugging Face Space, follow "Bring your app": set
APP_FILE and the other settings in ~/app.env, and for a Gradio app
change ExecStart as it says. Never commit to the owner's repository or
push to ~/app.git (run the hook by hand instead), so the owner's first
push fast-forwards. Remove whatever you make only for testing. If a
private GitHub repository can't be cloned, give the owner the
`integrations add github` command with this VM's name and wait for them.
If the app needs API keys you don't have, say which, and where they go.
Don't reboot, don't make the VM public, and don't run the Restore steps
on live data: test the backup in a scratch directory as written.
The VM can't open its own https://<vm>.exe.xyz; "Check it" tests
through localhost instead. Skip the optional sections (Gradio next to
Streamlit, integrations, public access) unless the owner asks.
Finish with https://<vm>.exe.xyz/ and only the one git command from
"Deploy with git push" that fits: `git clone -o exe` for REPO=new,
`git remote add exe` for a repository, plus the branch to push if it
isn't main, and anything you adapted or that the owner should change.
Finish with the URLs I should open and these commands, which only I can run, from my own computer (with this VM's name in them):
git clone -o exe my-streamlit.exe.xyz:app.git # if you started fresh
git remote add exe my-streamlit.exe.xyz:app.git # or, in your own app's checkout
Also at /deploy/streamlit/prompt.txt. The recipe it follows is /deploy/streamlit.md.
Open your app#
When Shelley finishes, open https://my-streamlit.exe.xyz/. exe.dev asks
you to sign in, then shows the app. Only you can see it, until you
share the VM.
The starter is a dashboard of the past weeks' earthquakes, from the US
Geological Survey's public feed: a map, a table, and two sliders. Under
the title it says Signed in as and your email address: exe.dev's proxy
told the app who you are. Type a question in the box at the bottom, such
as "Where was the strongest one?", and an LLM answers from the table, with
no API key anywhere on the VM. Each question is saved with its asker in
SQLite, at ~/data/app.db, and listed under Recent questions.
Every hour, a timer fetches the feed again and adds what's new to the database, so the history grows past the feed's one week. The page shows the new data on its next rerun; nobody restarts anything.
Deploy with git push#
The VM keeps a Git repository at ~/app.git. Pushing to it deploys. Add it
as a remote called exe on your computer. If you started fresh, clone it:
git clone -o exe my-streamlit.exe.xyz:app.git my-streamlit
cd my-streamlit
If you brought your own repository, add the remote to your checkout instead:
git remote add exe my-streamlit.exe.xyz:app.git
Change something, commit, and push. In the starter, change the title in
streamlit_app.py:
git commit -am "Rename the dashboard"
git push exe main
(If your repository's branch is master, push master.) The deploy runs
inside the push, and its output comes back to you:
remote: deploy: 4e1d2c9 (main)
remote: deploy: running streamlit_app.py once
remote: deploy: 4e1d2c9 is live at https://my-streamlit.exe.xyz/
The hook builds the commit in a new directory,
~/releases/<time>-<commit>, with uv sync --locked. Then it runs the
app's script once, headless, with Streamlit's
AppTest, so
an exception on the first page load stops the deploy instead of greeting
your team. Then it points ~/app at the new release, restarts the app (a
second or two without answers; open pages reconnect by themselves), and
waits for it to answer. If anything fails, the push ends with
deploy: FAILED, the error, and ! [remote rejected] main -> main (pre-receive hook declined); the running version stays. Fix it and push
again.
To go back to an earlier version, push it:
git push -f exe 4e1d2c9:main
GitHub can stay your source of truth: git push origin main to share the
code, git push exe main to ship it.
Tip
If
ssh my-streamlit.exe.xyzworks but the push can't connect, usevm+my-streamlit@vm.exe.xyz:app.gitas the remote's address (why).
Work on it locally#
You need uv on your computer. In your
checkout, uv sync installs the same Python and packages the VM uses. The
starter keeps a local database in data/, which Git ignores:
uv run refresh.py
uv run streamlit run streamlit_app.py
The LLM box needs exe.dev's gateway, which only answers on the VM. To try
it locally, set LLM_BASE_URL=https://api.openai.com/v1 and
OPENAI_API_KEY to your own key.
Share it, and know who's looking#
The app is private: exe.dev's proxy sends anyone who isn't signed in, or hasn't been given access, to a login page before a single request reaches the VM. To let your team in, on your computer:
ssh exe.dev share add my-streamlit alice@example.com
ssh exe.dev share add my-streamlit team # everyone on your exe.dev team
ssh exe.dev share add-link my-streamlit # a link anyone can accept after signing in
They get the app and nothing else: no shell, no Shelley. See
sharing for the rest, including share remove.
For each signed-in viewer, the proxy adds X-ExeDev-Email and
X-ExeDev-UserID to every request, and removes any a visitor tried to send
themselves (Login with exe). Streamlit shows a
session's headers in
st.context.headers,
which doesn't care about case:
user = st.context.headers.get("X-ExeDev-Email")
So per-person behavior is a few lines. To keep a page for some of the
people you've shared with, put it in pages/admin.py (Streamlit makes it a
page of its own) and start it with:
import os
import streamlit as st
ADMINS = set(os.environ.get("ADMIN_EMAILS", "").split(","))
if st.context.headers.get("X-ExeDev-Email") not in ADMINS:
st.error("This page is for admins.")
st.stop()
with ADMIN_EMAILS=you@example.com,alice@example.com in ~/app.env
(then sudo systemctl restart app). The headers are those of the page's
WebSocket connection, made when the page loads, so they are the same for
the whole session. Gradio passes them to any event handler with a
gr.Request parameter; see
Gradio apps.
Secrets and API keys#
Streamlit apps read secrets with
st.secrets,
from .streamlit/secrets.toml. On the VM, they go in
~/.streamlit/secrets.toml, outside the repository, so a deploy never
overwrites them and Git never sees them; Streamlit reads that file
wherever the app runs. It's mode 600. On the VM:
nano ~/.streamlit/secrets.toml
sudo systemctl restart app
What you'd paste into Community Cloud's Secrets box goes here, unchanged:
WAREHOUSE_URL = "postgresql://reader:...@db.example.com/sales"
[connections.snowflake]
account = "..."
Plain environment variables, the way Spaces and most other platforms pass
secrets, go in ~/app.env. Both files are in the nightly backup.
Better still, keep the key off the VM. exe.dev's
HTTP proxy integration stores a token on
exe.dev's side and adds it to each request the VM makes through it. For an
API that wants Authorization: Bearer ..., on your computer:
printf '%s' "$WEATHER_API_KEY" | ssh exe.dev integrations add http-proxy \
--name weather --target https://api.weather.example --bearer=- --attach vm:my-streamlit
The app then calls https://weather.int.exe.xyz/... with no key at all,
and a copy of the VM, a leaked backup, or a careless st.write(st.secrets)
has nothing to give away. For private GitHub repositories and LLMs there
are dedicated integrations, below; Agent secrets
shows the pattern at length.
Refresh data on a schedule#
A dashboard is only as fresh as its data. Instead of fetching it while
someone waits, let a timer do it: app-refresh.timer runs refresh.py
from the live release every hour, as you, with ~/app.env and the app's
virtualenv, and does nothing if there's no refresh.py. In the starter, it
adds the USGS feed to SQLite. Yours can pull from a warehouse, an API, or
a spreadsheet, and write a database or a Parquet file in ~/data.
On the VM, run it now, and see when it runs next and what it said last:
sudo systemctl start app-refresh
journalctl -u app-refresh -n 5 --no-pager
systemctl list-timers app-refresh.timer
The app picks up new data through its cache key. The starter caches the
dataframe with @st.cache_data on the time of the last refresh, so the
first rerun after a refresh loads it again, and every other rerun is
free:
@st.cache_data
def load(refreshed: str) -> pd.DataFrame: ...
refreshed = con.execute("SELECT max(fetched_at) FROM quakes").fetchone()[0]
quakes = load(refreshed)
For a different schedule, change OnCalendar= in
/etc/systemd/system/app-refresh.timer, for example to
Mon..Fri 06:00 or *:0/15 (every 15 minutes), and run
sudo systemctl daemon-reload. Times are UTC.
Call an LLM#
exe.dev's LLM integration answers at
https://llm.int.exe.xyz from your VM, with no API key: the VM is the
credential, and usage is billed to your exe.dev account. It speaks the
OpenAI API (and Anthropic's), so the OpenAI SDK works with a different
base_url. The starter's question box is this, with
st.write_stream
showing the answer as it arrives:
from openai import OpenAI
llm = OpenAI(base_url="https://llm.int.exe.xyz/v1", api_key="unused")
if question := st.chat_input("Where was the strongest one?"):
stream = llm.chat.completions.create(
model="gpt-5.4-mini",
messages=[{"role": "user", "content": question}],
stream=True,
)
answer = st.chat_message("assistant").write_stream(stream)
On the VM, curl -s https://llm.int.exe.xyz/v1/models lists the models
you can use: OpenAI's, Anthropic's, and open models through Fireworks.
Anthropic's SDK works the same way, with base_url="https://llm.int.exe.xyz".
For a chat UI with no code at all, see Open WebUI.
Gradio apps#
Gradio is the other way to put a Python function
in a browser, and the SDK behind most Hugging Face Spaces. It needs even
less setup here: demo.launch() listens on 127.0.0.1:7860 by default, and
exe.dev's proxy serves every port from 3000 to 9999, so a Gradio app on
the VM is at https://my-streamlit.exe.xyz:7860/ as soon as it starts,
behind the same login. Gradio's own settings, for launch() or as
environment variables:
server_name(GRADIO_SERVER_NAME): leave it at127.0.0.1. Spaces set0.0.0.0; you don't need to.server_port(GRADIO_SERVER_PORT): 7860, or 8000 to make it the VM's main app athttps://my-streamlit.exe.xyz/.root_path(GRADIO_ROOT_PATH): only if the app is served under a path, such as/chatbehind your own nginx. Gradio builds its URLs from the proxy'sX-Forwarded-HostandX-Forwarded-Proto, so at the root of a port it needs nothing.share=Truewould open a publicgradio.livetunnel past exe.dev's login. Leave it off; share the VM instead.
A handler that takes a gr.Request gets the viewer's headers:
def chat(message, history, request: gr.Request):
user = request.headers.get("x-exedev-email")
A Gradio app next to Streamlit#
This runs a chat app with the LLM gateway on port 7860, as its own service, alongside the Streamlit app. On the VM:
mkdir -p ~/chat && cd ~/chat
uv init -q --no-package --no-readme --python 3.13 --name chat
rm -f main.py
uv add -q "gradio>=6.32,<7" openai
cat > app.py <<'EOF'
"""A Gradio chat app on exe.dev: the LLM gateway, and the viewer's email."""
import gradio as gr
from openai import OpenAI
llm = OpenAI(base_url="https://llm.int.exe.xyz/v1", api_key="unused")
def chat(message, history, request: gr.Request):
user = request.headers.get("x-exedev-email", "someone")
messages = [{"role": "system", "content": f"You are talking to {user}."}]
messages += [{"role": m["role"], "content": m["content"]} for m in history]
messages.append({"role": "user", "content": message})
reply = ""
stream = llm.chat.completions.create(model="gpt-5.4-mini", messages=messages, stream=True)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
reply += chunk.choices[0].delta.content
yield reply
demo = gr.ChatInterface(chat, title="Ask anything")
demo.launch(server_name="127.0.0.1", server_port=7860)
EOF
sudo tee /etc/systemd/system/chat.service >/dev/null <<'EOF'
[Unit]
Description=Gradio chat app in ~/chat
After=network-online.target
Wants=network-online.target
[Service]
User=exedev
WorkingDirectory=/home/exedev/chat
Environment=PYTHONUNBUFFERED=1 GRADIO_ANALYTICS_ENABLED=False
ExecStart=/home/exedev/chat/.venv/bin/python app.py
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now chat.service
sleep 10; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:7860/
Expect 200. Open https://my-streamlit.exe.xyz:7860/ and ask "What's
my email address?". After editing app.py, sudo systemctl restart chat.
Other ports are always private, even if you make port 8000 public, and
the people you've shared the VM with can open them too.
From Hugging Face Spaces#
A Gradio Space is a Git repository: app.py (or the file its README's
app_file names), requirements.txt, and a README whose front matter
says which Gradio and Python to use. Bring it like any other app: give
Shelley the Space's URL as REPO, or follow
Bring your app by hand, which clones it with:
git clone --bare https://huggingface.co/spaces/OWNER/NAME ~/app.git
Then, on your computer, clone the Space, add the VM as a remote, and push
there to deploy: git remote add exe my-streamlit.exe.xyz:app.git. Things
to know:
- Settings. Spaces install Gradio for you, so a Space's
requirements.txtusually lacks it:EXTRA_PACKAGES=gradio==<sdk_version>in~/app.envadds it. Spaces' Python defaults to 3.10; setPYTHONto the README'spython_versionif it has one. The Space's secrets and variables go in~/app.envtoo. - System packages. For a
packages.txt, runxargs -a packages.txt sudo apt-get install -yon the VM once. - Models. The VM has no GPU. ZeroGPU's
@spaces.GPUdoes nothing outside Spaces, so small models run on the CPU, and their downloads stay cached in~/.cache/huggingfaceacross restarts. A model that needs a GPU should run elsewhere, behind an API the app calls. - Large files. Files a Space keeps in Git LFS reach the VM as
small pointer files, since the hook copies the repository with
git archive. Download them at startup withhuggingface_hubinstead, which most Spaces already do for their models.
Make it public (optional)#
A demo for the world, or a dashboard for people without exe.dev accounts? On your computer:
ssh exe.dev share set-public my-streamlit
Now anyone can open https://my-streamlit.exe.xyz/, and X-ExeDev-Email
arrives only for visitors who have signed in on this host. Offer them a
sign-in link where you need to know who they are:
user = st.context.headers.get("X-ExeDev-Email")
if not user:
st.link_button("Sign in", "/__exe.dev/login?redirect=/")
st.stop()
Only port 8000 can be public; a Gradio app on 7860 stays private.
ssh exe.dev share set-private my-streamlit closes the door again. For
your own domain, see custom domains.
Ask Shelley#
Shelley, the agent on your VM, is at https://my-streamlit.shelley.exe.xyz/.
It can read journalctl -u app, the deploy hook, and your code, so "my
last push failed, why?" or "add a page with the strongest earthquakes per
country" are fine requests. Ask it to work in a clone of ~/app.git and
deploy with git push, like you do; then git pull exe main brings its
commits to your computer.
The nuts and bolts#
Happy with what Shelley set up? You can stop here. These are the steps it followed, and the maintenance commands for later. Tested with Streamlit 1.67.0, Gradio 6.32.0, and uv 0.13.8 on Python 3.13.
Set up by hand
Create the VM#
On your computer (pick another name if my-streamlit is taken):
ssh exe.dev new --name=my-streamlit
ssh my-streamlit.exe.xyz
Everything else runs on the VM, as exedev.
Prepare the VM#
uv is preinstalled. Install Python 3.13 with it, and make the directories
for data, backups, and scripts. Then create the app's settings,
~/app.env, and its secrets, ~/.streamlit/secrets.toml, once:
uv python install 3.13
mkdir -p ~/data ~/backups ~/bin ~/.streamlit
if [ ! -e ~/app.env ]; then
install -m 600 /dev/null ~/app.env
cat >> ~/app.env <<EOF
# Settings and secrets for app.service, app-refresh, and the deploy hook.
# One KEY=value per line, no quotes. Back this file up.
APP_FILE=streamlit_app.py
DATA_DIR=$HOME/data
EOF
fi
[ -e ~/.streamlit/secrets.toml ] || install -m 600 /dev/null ~/.streamlit/secrets.toml
cat ~/app.env
APP_FILE is the script to run. The hook also reads PYTHON (the Python
for a project with only requirements.txt; 3.13 if unset),
EXTRA_PACKAGES (packages the repository doesn't list), and
SMOKE_TEST=no (skip the headless run).
Back up nightly#
This script copies each SQLite database in ~/data with sqlite3 .backup, which is safe while the app writes, and checks the copy. It adds
the rest of ~/data, ~/app.env, and the secrets file, and keeps the 14
newest backups of each kind:
cat > ~/bin/app-backup <<'EOF'
#!/bin/bash
# Back up ~/data, ~/app.env and ~/.streamlit/secrets.toml to
# ~/backups/app-<kind>-<time>.tar.gz. SQLite databases (*.db) are copied
# with .backup, safe while the app runs. Keeps the 14 newest backups of
# each kind. Usage: app-backup [nightly|manual]
set -euo pipefail
umask 077
kind=${1:-manual}
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
mkdir -p "$HOME/backups" "$work/data"
rsync -a --exclude='*.db' --exclude='*.db-wal' --exclude='*.db-shm' "$HOME/data/" "$work/data/"
for db in "$HOME"/data/*.db; do
[ -e "$db" ] || continue
copy="$work/data/$(basename "$db")"
sqlite3 "$db" ".backup '$copy'"
[ "$(sqlite3 "$copy" 'PRAGMA integrity_check')" = ok ]
done
cp "$HOME/app.env" "$HOME/.streamlit/secrets.toml" "$work/"
out="$HOME/backups/app-$kind-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" .
mv "$out.part" "$out"
ls -1t "$HOME/backups/app-$kind-"*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/app-backup
Run it every night at about 03:30 UTC:
sudo tee /etc/systemd/system/app-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up ~/data, ~/app.env and secrets to ~/backups
[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/app-backup nightly
EOF
sudo tee /etc/systemd/system/app-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the app every night
[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-backup.timer
systemctl list-timers app-backup.timer
The timer should show its next run.
Run the app with systemd#
exe.dev's HTTPS proxy sends https://<vm>.exe.xyz/ to port
8000 and reaches it on 127.0.0.1, so the app listens there and nowhere
else. The proxy carries Streamlit's WebSocket as it is, so the rest of
Streamlit's defaults stay: CORS and XSRF protection on (uploads work,
since the page and the server share an address) and no baseUrlPath.
The flags turn off the file watcher, since a deploy restarts the app
anyway, and Streamlit's usage statistics. Flags on the command line win
over a repository's .streamlit/config.toml, so its theme still
applies:
sudo tee /etc/systemd/system/app.service >/dev/null <<'EOF'
[Unit]
Description=Streamlit app in ~/app
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/exedev/app/.venv/bin/streamlit run ${APP_FILE} --server.address 127.0.0.1 --server.port 8000 --server.headless true --server.fileWatcherType none --browser.gatherUsageStats false
Restart=always
RestartSec=3
TimeoutStopSec=20
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app.service
It starts with the first deploy. The data refresh is a oneshot service
and an hourly timer; ConditionPathExists skips it for apps without a
refresh.py:
sudo tee /etc/systemd/system/app-refresh.service >/dev/null <<'EOF'
[Unit]
Description=Refresh the app's data with ~/app/refresh.py
ConditionPathExists=/home/exedev/app/refresh.py
[Service]
Type=oneshot
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/exedev/app/.venv/bin/python refresh.py
EOF
sudo tee /etc/systemd/system/app-refresh.timer >/dev/null <<'EOF'
[Unit]
Description=Refresh the app's data every hour
[Timer]
OnCalendar=hourly
RandomizedDelaySec=5m
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-refresh.timer
Add the deploy hook#
Create the repository you'll push to. To start fresh:
git init --bare -b main ~/app.git
To bring your app, clone it from GitHub (or a Hugging Face Space) instead,
with your repository in place of OWNER/NAME:
git clone --bare https://github.com/OWNER/NAME.git ~/app.git
If that asks for a password, the repository is private. On your computer, connect it with the GitHub integration, then clone through the integration, with no token on the VM:
ssh exe.dev integrations add github --name NAME --repository OWNER/NAME --attach vm:my-streamlit
git clone --bare https://github.int.exe.xyz/OWNER/NAME.git ~/app.git
The branch HEAD points to (main, usually) is the one that deploys;
pushes to other branches are stored but not deployed. Now the hook:
cat > ~/app.git/hooks/pre-receive <<'EOF'
#!/bin/bash
# Deploys each push to the deploy branch before git accepts it, or the
# branch as it is when run by hand. Builds it in a new
# ~/releases/<time>-<commit>: installs dependencies with uv and runs a
# Streamlit app once, headless, with AppTest. Then points ~/app at the new
# release, restarts app.service, and waits for an answer. Any failure
# rejects the push, and ~/app stays on (or goes back to) the running release.
set -Eeuo pipefail
by_git=${GIT_DIR:+yes} # git sets GIT_DIR for hooks, so this is a push
export GIT_DIR=$HOME/app.git PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
branch=$(git symbolic-ref --short HEAD)
exec 9>"$GIT_DIR/deploy.lock" && flock 9 # one deploy at a time
new=$(git rev-parse -q --verify "refs/heads/$branch" || true)
if [ -n "$by_git" ]; then
now=${new:-0000000000000000000000000000000000000000} new=
while read -r was sha ref; do
if [ "$ref" = "refs/heads/$branch" ]; then new=$sha from=$was; fi
done
if [ -z "$new" ]; then echo "deploy: only pushes to $branch deploy"; exit 0; fi
if [[ $new =~ ^0+$ ]]; then echo "deploy: $branch can't be deleted"; exit 1; fi
if [ "$from" != "$now" ]; then echo "deploy: $branch moved; pull and push again"; exit 1; fi
fi
old=$(readlink "$HOME/app" || true) # the live release
release=$HOME/releases/$(date -u +%Y%m%d-%H%M%S)-${new:0:12}
echo "deploy: ${new:0:7} ($branch)"
mkdir -p "$HOME/releases" && mkdir "$release"
trap 'rm -rf "$release"; echo "deploy: FAILED; the live version is unchanged" >&2' ERR
git archive "$new" | tar -x -C "$release"
unset GIT_DIR GIT_QUARANTINE_PATH GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
cd "$release"
set -a; . "$HOME/app.env"; set +a
if [ -f uv.lock ]; then uv sync -q --locked --no-dev
elif [ -f pyproject.toml ]; then uv sync -q --no-dev
else uv venv -q --python "${PYTHON:-3.13}"
if [ -f requirements.txt ]; then uv pip install -q -r requirements.txt; fi
fi
if [ -n "${EXTRA_PACKAGES:-}" ]; then uv pip install -q $EXTRA_PACKAGES; fi
if [ -x .venv/bin/streamlit ] && [ "${SMOKE_TEST:-yes}" != no ]; then
echo "deploy: running $APP_FILE once"
.venv/bin/python - 2>/dev/null <<'PY'
import os, sys
from streamlit.testing.v1 import AppTest
at = AppTest.from_file(os.path.abspath(os.environ["APP_FILE"]), default_timeout=60).run()
for e in at.exception:
print(f"deploy: {e.proto.type}: {e.message}")
print("\n".join(e.stack_trace[-2:]))
sys.exit(1 if at.exception else 0)
PY
fi
trap - ERR
go_live() { # point ~/app at a release, restart, wait 30 s for an answer below 500
ln -sfn "$1" "$HOME/app.next" && mv -T "$HOME/app.next" "$HOME/app"
since=$(date +%s)
sudo systemctl restart app.service
for _ in $(seq 30); do
sleep 1
code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/) || true
[ "$code" -ge 200 ] && [ "$code" -lt 500 ] && return 0
done
return 1
}
if ! go_live "$release"; then
echo "deploy: no answer on port 8000. The end of journalctl -u app:" >&2
journalctl -u app.service --since "@$since" -o cat | tail -n 8 >&2 || true
if [ -z "$old" ]; then echo "deploy: FAILED; fix it and deploy again" >&2; exit 1; fi
go_live "$old" || true
rm -rf "$release"
echo "deploy: FAILED; back to ${old: -12:7}" >&2
exit 1
fi
ls -1d "$HOME"/releases/*/ | head -n -3 | xargs -r rm -rf # keep three
echo "deploy: ${new:0:7} is live at https://$(hostname).exe.xyz/"
EOF
chmod +x ~/app.git/hooks/pre-receive
~/app is a link to the live release: readlink ~/app shows which, and
the hook keeps the three newest in ~/releases. Now follow
Start fresh or Bring your app.
Start fresh#
The starter is the earthquake dashboard: a uv project with Streamlit, pandas, and the OpenAI SDK, made in a scratch directory:
rm -rf /tmp/starter && mkdir /tmp/starter && cd /tmp/starter
git init -q -b main
uv init -q --no-package --no-readme --python 3.13 --name "$(hostname)"
rm -f main.py
uv add -q "streamlit>=1.67,<2" pandas openai
The database, in store.py, is shared by the page and the refresh job:
cat > store.py <<'EOF'
"""The app's SQLite database: DATA_DIR/app.db (~/data on the VM, data/ locally)."""
import os
import sqlite3
from pathlib import Path
DATA_DIR = Path(os.environ.get("DATA_DIR", "data"))
def connect() -> sqlite3.Connection:
DATA_DIR.mkdir(parents=True, exist_ok=True)
con = sqlite3.connect(DATA_DIR / "app.db", timeout=10)
con.execute("PRAGMA journal_mode=WAL") # readers don't wait for the refresh
con.executescript(
"""
CREATE TABLE IF NOT EXISTS quakes (
id TEXT PRIMARY KEY, time TEXT, latitude REAL, longitude REAL,
depth REAL, mag REAL, place TEXT, type TEXT, fetched_at TEXT);
CREATE TABLE IF NOT EXISTS questions (
asked_at TEXT, email TEXT, question TEXT, answer TEXT);
"""
)
return con
EOF
refresh.py adds the past week of earthquakes to it, keeping each by its
USGS id, so the history grows past the feed's week:
cat > refresh.py <<'EOF'
"""Add the past week of earthquakes from USGS to SQLite. app-refresh.timer runs this hourly."""
from contextlib import closing
from datetime import UTC, datetime
import pandas as pd
from store import connect
FEED = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.csv"
COLUMNS = ["id", "time", "latitude", "longitude", "depth", "mag", "place", "type"]
df = pd.read_csv(FEED, usecols=COLUMNS)[COLUMNS]
df["fetched_at"] = datetime.now(UTC).isoformat(timespec="seconds")
rows = df.astype(object).where(df.notna(), None).itertuples(index=False)
with closing(connect()) as con, con:
con.executemany("INSERT OR REPLACE INTO quakes VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", rows)
total = con.execute("SELECT count(*) FROM quakes").fetchone()[0]
print(f"{len(df)} earthquakes this week; {total} stored")
EOF
The page, streamlit_app.py, the file name Streamlit Community Cloud
looks for first:
cat > streamlit_app.py <<'EOF'
"""Earthquakes: a starter Streamlit app on exe.dev.
refresh.py keeps earthquakes from USGS in SQLite; this page maps them and
answers questions about them with an LLM through exe.dev's gateway.
"""
import os
from contextlib import closing
from datetime import UTC, datetime
import pandas as pd
import streamlit as st
from openai import OpenAI
from store import connect
st.set_page_config(page_title="Earthquakes", page_icon="🌍", layout="wide")
# exe.dev's proxy says who is looking, in a header on every request.
user = st.context.headers.get("X-ExeDev-Email")
# exe.dev's LLM gateway needs no key on the VM. Locally, set LLM_BASE_URL
# to a provider's API and OPENAI_API_KEY to your key.
llm = OpenAI(
base_url=os.environ.get("LLM_BASE_URL", "https://llm.int.exe.xyz/v1"),
api_key=os.environ.get("OPENAI_API_KEY", "unused"),
)
@st.cache_data(show_spinner=False)
def load(refreshed: str) -> pd.DataFrame:
"""Every stored earthquake; cached until the next refresh changes `refreshed`."""
with closing(connect()) as con:
df = pd.read_sql("SELECT * FROM quakes", con)
df["time"] = pd.to_datetime(df["time"], utc=True, format="ISO8601")
return df.sort_values("time", ascending=False)
st.title("Earthquakes")
st.caption(f"Signed in as **{user}**" if user else "Not signed in")
with closing(connect()) as con:
refreshed = con.execute("SELECT max(fetched_at) FROM quakes").fetchone()[0]
if refreshed is None:
st.info("No data yet. On the VM, run `sudo systemctl start app-refresh`.")
st.stop()
quakes = load(refreshed)
days = st.sidebar.slider("Past days", 1, 30, 7)
min_mag = st.sidebar.slider("Minimum magnitude", 0.0, 7.0, 2.5, 0.5)
since = pd.Timestamp.now(tz="UTC") - pd.Timedelta(days=days)
shown = quakes[(quakes["time"] >= since) & (quakes["mag"] >= min_mag)]
a, b, c = st.columns(3)
a.metric("Earthquakes", len(shown))
b.metric("Strongest", f"{shown['mag'].max():.1f}" if len(shown) else "none")
c.metric("Stored", len(quakes))
st.map(shown.assign(radius=shown["mag"] * 20_000), size="radius", color="#ff4b4b88")
st.dataframe(shown[["time", "mag", "place", "depth"]], hide_index=True)
st.caption(f"USGS data, refreshed {refreshed} UTC.")
st.subheader("Ask about these earthquakes")
if question := st.chat_input("Where was the strongest one?"):
st.chat_message("user").write(question)
table = shown.head(300)[["time", "mag", "place", "depth"]].to_csv(index=False)
stream = llm.chat.completions.create(
model=os.environ.get("LLM_MODEL", "gpt-5.4-mini"),
messages=[
{"role": "system", "content": "Answer briefly from this table:\n" + table},
{"role": "user", "content": question},
],
stream=True,
)
answer = st.chat_message("assistant").write_stream(stream)
with closing(connect()) as con, con:
asked_at = datetime.now(UTC).isoformat(timespec="seconds")
con.execute("INSERT INTO questions VALUES (?, ?, ?, ?)", (asked_at, user, question, answer))
with closing(connect()) as con:
recent = pd.read_sql(
"SELECT asked_at, email, question FROM questions ORDER BY asked_at DESC LIMIT 10", con
)
if len(recent):
st.caption("Recent questions")
st.dataframe(recent, hide_index=True)
EOF
Ignore what shouldn't be committed, commit, and push to ~/app.git.
That runs the hook: the first deploy. Then fetch the data once:
cat > .gitignore <<'EOF'
__pycache__/
*.py[oc]
.venv/
.env
data/
.streamlit/secrets.toml
EOF
git add .gitignore .python-version pyproject.toml uv.lock store.py refresh.py streamlit_app.py
git -c user.name="$(hostname)" -c user.email="exedev@$(hostname).exe.xyz" commit -q -m "Streamlit starter"
git push -q ~/app.git main && cd ~ && rm -rf /tmp/starter
sudo systemctl start app-refresh.service
journalctl -u app-refresh -n 3 -o cat --no-pager
Expect deploy: ... is live at https://... from the push, and a line like
1843 earthquakes this week; 1843 stored from the refresh. Continue with
Check it.
Bring your app#
The hook already knows uv projects (uv.lock or pyproject.toml) and
requirements.txt, the files Streamlit Community Cloud and Spaces use.
Check what else your app expects, in its README and on the platform it
came from:
- The script. Set
APP_FILEin~/app.envto the file Streamlit runs (the "Main file path" on Community Cloud), relative to the repository's top, such asapp/dashboard.py. - Python. uv uses the version in
.python-versionorrequires-python. For a project with onlyrequirements.txt, setPYTHON=3.12(say) in~/app.env; Community Cloud shows the app's version in its settings. - Secrets and settings. Copy Community Cloud's Secrets into
~/.streamlit/secrets.toml; put environment variables in~/app.env. Point databases and files the app writes into~/data(DATA_DIRis set there); anything written inside~/appis lost at the next deploy. - System packages. For a
packages.txt, runxargs -a packages.txt sudo apt-get install -yonce. - A Gradio app (or a Gradio Space): it runs with Python rather than
streamlit run. In/etc/systemd/system/app.service, make theExecStartlineExecStart=/home/exedev/app/.venv/bin/python ${APP_FILE}, thensudo systemctl daemon-reload, and add to~/app.env:APP_FILE=app.py(the Space'sapp_file),GRADIO_SERVER_PORT=8000,GRADIO_ANALYTICS_ENABLED=False, and for a SpaceEXTRA_PACKAGES=gradio==<sdk_version>. Iflaunch()names a port, change it to 8000 or delete it. See From Hugging Face Spaces. - A data refresh. The timer runs
refresh.pyat the top of the repository, if there is one. PointExecStartin/etc/systemd/system/app-refresh.serviceat another script if you have one.
Then deploy it once:
~/app.git/hooks/pre-receive
Expect deploy: ... is live at https://.... If the headless run fails,
the error is above it: often a missing secret or package. If the app
doesn't answer, journalctl -u app -n 50 says why. Fix it, and run the
hook again.
Check it#
systemctl is-active app.service
systemctl is-enabled app.service app-backup.timer app-refresh.timer
curl -s http://localhost:8000/_stcore/health; echo
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/
Expect active, enabled three times, ok (Streamlit's health check;
a Gradio app answers {"detail":"Not Found"} there, which is fine), and 200. Then open
https://<vm>.exe.xyz/ in a browser. sudo reboot, wait a minute,
reconnect, and the same checks pass.
Test a backup#
Make a backup and restore it into a scratch directory:
sudo systemctl start app-backup.service
latest=$(ls -1t ~/backups/app-nightly-*.tar.gz | head -n 1)
rm -rf /tmp/restore-test && mkdir /tmp/restore-test
tar -xzf "$latest" -C /tmp/restore-test
ls -a /tmp/restore-test /tmp/restore-test/data
for db in /tmp/restore-test/data/*.db; do
[ -e "$db" ] && sqlite3 "$db" 'PRAGMA integrity_check' && sqlite3 "$db" .tables
done
rm -rf /tmp/restore-test
Expect app.env, secrets.toml, the data directory, and for each
database ok and its tables (the starter's are questions and quakes).
Setup is done: continue with Open your app.
Back up and restore
On the VM, ~/bin/app-backup makes a backup now and prints its path. Each
archive holds data/ (each SQLite database as a consistent copy),
app.env, and secrets.toml. A backup on the VM won't help if you lose
the VM, so copy them off now and then. On your computer:
scp -r my-streamlit.exe.xyz:backups my-streamlit-backups
They hold your app's secrets, so keep them private. For a copy of the
whole VM, ssh exe.dev cp my-streamlit my-streamlit-copy works too.
Restore#
Pick a backup and use its name below. On a new VM, first follow Set up by hand up to your first deploy, then copy the archive over from your computer:
scp my-streamlit-backups/app-nightly-20261116-033012.tar.gz my-streamlit.exe.xyz:backups/
On the VM, stop the app and the refresh, set the current data aside, and unpack:
backup=~/backups/app-nightly-20261116-033012.tar.gz
sudo systemctl stop app.service app-refresh.timer
mv ~/data ~/data.before-restore-$(date +%s)
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
mv /tmp/restore/data ~/data
diff /tmp/restore/app.env ~/app.env
diff /tmp/restore/secrets.toml ~/.streamlit/secrets.toml
If diff shows settings or secrets you need from the backup (on a new VM,
you do), copy them: install -m 600 /tmp/restore/app.env ~/app.env and
install -m 600 /tmp/restore/secrets.toml ~/.streamlit/secrets.toml.
Then start again:
sudo systemctl start app.service app-refresh.timer
sleep 5; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/
rm -rf /tmp/restore
Expect 200, and your data in the app. Delete ~/data.before-restore-*
once you're happy.
Update Streamlit, Python, and the rest
Updates travel through Git like any other change. On your computer:
- Packages:
uv lock --upgrade-package streamlit(or--upgradefor everything), try it withuv run streamlit run streamlit_app.py, commituv.lock, and push. Streamlit's release notes list what changed; the hook's headless run catches the crashes. - Python: change
.python-version(to3.14, say) andrequires-pythoninpyproject.toml, runuv lock, commit, and push. The hook'suv syncdownloads that Python for the new release.
On the VM:
- A Gradio app next to Streamlit:
cd ~/chat && uv lock --upgrade-package gradio && uv sync && sudo systemctl restart chat. - uv: the preinstalled uv is fine. For a newer one,
curl -LsSf https://astral.sh/uv/install.sh | shinstalls it in~/.local/bin, which the hook and your shell try first. - Ubuntu:
sudo apt-get update && sudo apt-get upgrade -y.
Something not working?
On the VM, the app's log, and the live release:
journalctl -u app -n 100 --no-pager
systemctl status app --no-pager
readlink ~/app
deploy: FAILEDand a rejected push: the lines above it say why.The lockfile at uv.lock needs to be updated: runuv lockand commituv.lock. AModuleNotFoundError: the package is missing frompyproject.tomlorrequirements.txt. An exception from the headless run: the same error your viewers would get;uv run streamlit runshows it locally. If the script can't run without a viewer (it waits on something only a browser sends), setSMOKE_TEST=noin~/app.env.- Deploy again without a new commit, after changing a setting, say:
on your computer,
ssh my-streamlit.exe.xyz app.git/hooks/pre-receive. Settings and secrets alone need onlysudo systemctl restart appon the VM. - The push is rejected (
non-fast-forward): someone else pushed first, maybe Shelley.git pull exe main, then push. - The page says "Connection error" or keeps reconnecting: the app
restarted or stopped.
systemctl status appshows whether it's running, and the log shows why it stopped. - The browser can't reach the app: check that it listens on
127.0.0.1:8000 (
ss -ltnp | grep 8000). For another port, runssh exe.dev share port my-streamlit <port>on your computer. st.context.headershas noX-ExeDev-Email: the page wasn't loaded throughhttps://my-streamlit.exe.xyz/(on the VM, a curl to localhost has none), or the VM is public and the visitor hasn't signed in.- The data is old:
systemctl list-timers app-refresh.timershows the last and next runs, andjournalctl -u app-refresh -n 20the last output. A cached function that doesn't take the refresh time as an argument keeps old data untilttlruns out or the app restarts. - A header-injecting proxy gets
403on the WebSocket: testing identity locally withmitmdump, as in Login with exe? Streamlit refuses a WebSocket whoseOrigindoesn't match itsHost; add--set keep_host_header=true. exe.dev's proxy keeps theHost. database is locked: a write took longer than the 10-second timeout. Keep transactions short.- Down after a reboot:
sudo systemctl enable --now app.service.
Frequently asked questions#
How is this different from Streamlit Community Cloud?
Community Cloud is free, but its apps are public unless they're your one private app, they go to sleep after 12 hours without traffic until someone clicks to wake them, and they get at most about 2.7 GB of memory. Here the app is private by default, never sleeps, keeps what it writes to disk, and can use all of the VM. You pay for the VM; see exe.dev plans. Streamlit is Apache-2.0.
How is it different from Hugging Face Spaces?
A free Space sleeps after 48 hours without visitors, its disk isn't persistent, and creating a new Gradio or Docker Space now needs a paid Hugging Face plan. A VM keeps its disk and its process, and stays private until you open it. It has no GPU, so models that need one should run elsewhere, behind an API the app calls.
Do I need st.login or Gradio's auth?
No. exe.dev's proxy signs people in before any request reaches the VM, and tells the app who they are in X-ExeDev-Email. st.login and st.user are for apps that bring their own OpenID Connect provider; they stay empty here, and that's fine.
Can I run several apps on one VM?
Yes. A Streamlit multipage app (a pages/ directory) is one app with many pages. For separate apps, run each as its own service on a port from 3000 to 9999, as in Gradio next to Streamlit: streamlit run other.py --server.port 8501 is at https://my-streamlit.exe.xyz:8501/, private to you and the people you share the VM with.
How many people can use it at once?
Streamlit runs every viewer's session in one process, rerunning the script on each interaction, so slow work belongs in @st.cache_data, @st.cache_resource, or the refresh timer. A dashboard for a team is easy on a default VM. For more, resize it: ssh exe.dev resize my-streamlit --cpu=4, and sudo systemctl restart app.
Why not Docker?
You can: Docker is preinstalled, and Docker Compose runs a Streamlit image as well as anything else. But a Streamlit app is one Python process, and uv with systemd starts it in seconds, with the same Python on your laptop and on the VM, and no image to rebuild on each push.
Updated Nov 16, 2026 · tested end to end Nov 16, 2026 · Markdown · manifest.json · Something wrong? Tell us