vmux examples

Small, fast examples you can read in a minute and run in a second.

Setup

uv tool install vmux-cli
vmux login

Quick start

# Hello world
vmux run hello

# Web server with preview URL
vmux run web

# GPU compute (Modal)
vmux run gpu

Examples

The root vmux.toml declares named targets for the single-file examples. It sets setup = "none" for those targets so vmux does not Railpack-plan this whole mixed examples repo. Scripts with PEP 723 dependency blocks still install through uv run.

Project directories can declare their own vmux.toml. waves/ and llm-chat/ use local Railpack plans because each directory has a real project manifest.

All web servers honor PORT, so preview ports work everywhere.

Cloudflare (fast start)

Example	What it is	Command
hello.py	Sanity check	vmux run hello
web_server.py	FastAPI hello + preview URL	vmux run web
background_job.py	Long-running logs	vmux run background
burrow.py	WebSocket + SSE dashboard	vmux run burrow
collab-terminal/	Shared terminal over WS	vmux run collab
gradio_chat.py	Gradio UI	vmux run gradio
waves/	Bun + Vite demo	cd waves && vmux run dev

Modal (GPU + heavy deps)

Example	What it is	Command
gpu_hello.py	CUDA sanity check	vmux run gpu
jupyter.py	JupyterLab (torch/jax baked in)	vmux run jupyter
llm-chat/	GPT-OSS chat UI (A10G+)	cd llm-chat && vmux run chat
vllm_server.py	OpenAI-compatible API	vmux run vllm
whisper_api.py	Audio transcription	vmux run whisper
embeddings_api.py	RAG embeddings	vmux run embeddings
image_gen.py	SDXL Turbo	vmux run image
ollama_chat.py	Ollama + Llama	vmux run ollama

Patterns

Preview URLs

Expose a port to get a public URL:

vmux run -p 8000 python server.py          # attached
vmux run -dp 8000 python server.py         # detached

The preview URL shows a loading page with live logs until your server starts.

Detached jobs

Run in background, check later:

vmux run -d python train.py     # start
vmux ps                         # list jobs
vmux logs -f <id>               # follow logs
vmux attach <id>                # interactive tmux
vmux stop <id>                  # stop

Run vs attach

vmux run starts a job and creates a tmux session in the sandbox.
vmux attach <id> connects to that same session for interactive work.

# Start a server
vmux run -dp 8000 python web_server.py

# Later, attach to the same tmux session
vmux attach <job_id>

Session mode (LLM / automation)

Machine‑readable JSON events for Claude/Codex tool use:

vmux session run --json -dp 8000 python web_server.py
vmux session logs --json <job_id> --offset 0
vmux session exec --json "python -c \"print(1+1)\""
vmux session stop <job_id>

Note: vmux session --json is machine‑readable and does not attach to tmux.
For interactive shells, use vmux attach <job_id>.

Claude Code / Codex CLI example

Use vmux session --json as the external executor from your LLM loop:

# 1) Start a job (JSON events)
vmux session run --json -dp 8000 python web_server.py

# 2) Stream logs with offsets (for the LLM to track progress)
vmux session logs --json <job_id> --offset 0

# 3) Execute a command inside the same job
vmux session exec --json "python -c \"print('hello from vmux')\""

# 4) Stop when done
vmux session stop <job_id>

Legacy: vmux tool is still available as a hidden alias.

GPU selection

vmux run --provider modal --gpu T4 python script.py    # 16GB, budget
vmux run --provider modal --gpu L4 python script.py    # 24GB, balanced
vmux run --provider modal --gpu A10G python script.py  # 24GB, fast
vmux run --provider modal --gpu A100 python script.py  # 80GB, training
vmux run --provider modal --gpu H100 python script.py  # 80GB, fastest

Snapshot cache (Modal)

# Cache deps after a successful run
vmux run --provider modal --cache python vllm_server.py

Environment variables

# Pass env vars
vmux run -e API_KEY=xxx python script.py

# Use secrets (stored in keychain)
vmux secret set HF_TOKEN
vmux run --provider modal python script.py  # HF_TOKEN available

Stage markers

Add markers to your scripts for cleaner vmux output:

print("[vmux:stage] loading")      # start a stage
print("[vmux:stage:done] loading") # end a stage
print("[vmux:ready] http://...")   # signal ready

Agent Skills (Claude Code / Codex)

Teach your AI coding assistant to use vmux:

Claude Code

cp -r claude/skills/vmux ~/.claude/skills/vmux

Then just say "deploy this with a GPU" and Claude handles the rest.

OpenAI Codex

cp -r codex/skills/vmux ~/.agents/skills/vmux

Then say "run this in the cloud" or invoke with $vmux.

What the Skill Teaches

The skill includes the full session API for machine-readable output:

vmux session run --json -dp 8000 --provider modal --gpu A10G python app.py
vmux session logs --json <job_id> --offset 0
vmux session exec --json <job_id> "nvidia-smi"
vmux session stop <job_id>

See claude/README.md or codex/README.md for details.

API usage

After starting vllm_server.py or llm-chat/:

curl https://<preview-url>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

After starting whisper_api.py:

curl -X POST https://<preview-url>/transcribe -F "file=@audio.mp3"

After starting embeddings_api.py:

curl -X POST https://<preview-url>/embed \
  -H "Content-Type: application/json" \
  -d '{"texts": ["hello", "world"]}'