quickstart

Quickstart instructions to install spx, create a project, and deploy your app.

spx new scaffolds a complete project and does the first deploy. spx run <file> re-deploys the current version of your app to the production runtime in under 5s.

When developing with spx, spx run should be the only way you run your code.

Install + first project

Install the spx CLI:

brew install ab-10/spx/spx

Authenticate the CLI:

spx login

Create and deploy your first project:

spx new <project-name>
cd <project-name>

spx new creates a project with a working FastAPI server, installs dependencies, and performs the first deploy. The entrypoint is main.py, and the FastAPI app must be named app.

If your local setup uses Python, use Python 3.12.

Iteration loop

After each change, re-deploy with:

spx run main.py

spx prints a .runspx.com URL for the deployed process. Verify it:

curl https://<your-slug>.runspx.com

The URL is stable for the project. Running spx run <file> again replaces the running remote service behind the same project URL.

Port binding behavior

TLDR: bind your app to 0.0.0.0:8080 and it will just work.

When authoring an SPX Python entrypoint, assume it is run directly via python <file> and must itself start and keep an HTTP server bound to 0.0.0.0 on a port in 8000-9000 (prefer 8080).

SPX automatically scans 8000-9000 for listening user app ports inside your deployment VM.

If multiple candidate ports are listening in that range, SPX routes the public deployment URL to the lowest discovered port.

If no listening port is discovered in 8000-9000, deployment status reports a clear failure reason so you can adjust your app bind port.

Dependencies

Manage deployment dependencies with spx uv.

spx uv list
spx uv add httpx
spx uv add "uvicorn[standard]>=0.34"
spx uv remove httpx

Changes to dependencies apply on the next deploy.

spx run main.py

You do not need local python, pip, or uv installed to deploy.

For persisted project secrets and environment variables, see Secrets. For project files that survive redeploys, see Persistent filesystem.

Deployment lifetime

An SPX deployment is a remote service, not a process tied to your local terminal. Closing your terminal, ending the local CLI process, or putting your laptop to sleep does not intentionally stop the deployed service.

Use spx ps to list running remote services. Use spx kill <deployment-slug> to stop a running service and remove its active routing while stopped. spx kill does not delete your local project files or saved project identity.

If you are starting from an existing project

spx run <file>

After the first successful run, project identity persists automatically in .spx/state.json.

Hard requirements

1. Python 3.12 for uv project workflows. No other versions are supported.
2. uvicorn and fastapi must be in project dependencies, otherwise spx run will fail.