Apps

surfra.App is the deploy client. The handler file does not construct it. You run deploy from a laptop or from CI, with SURFRA_API_KEY set.

import surfra

app = surfra.App("myllm-staging")
app.deploy(
    image="ghcr.io/example/myllm:latest",
    entrypoint="python -m surfra.worker",
    env={"MODEL_ID": "example"},
    autoscale={
        "min_replicas": 0,
        "max_replicas": 4,
        "idle_timeout_sec": 300,
        "execution_timeout_sec": 1200,
        "gpu": "rtx4090",
        "providers": [
            {
                "provider": "runpod",
                "gpu": "rtx4090",
                "priority": 1,
                "num_workers": 1,
            },
            {
                "provider": "vast",
                "gpu": "rtx4090",
                "priority": 2,
                "num_workers": 1,
                "spot": True,
            },
        ],
    },
)

The app name is one token, such as myllm-staging. Deploying it again replaces the image, entrypoint, env, and autoscale in place.

Replicas

Field	Meaning
min_replicas	Machines that stay up between requests
max_replicas	The cap, including machines started for the queue
idle_timeout_sec	How long a machine stays up after its last request
execution_timeout_sec	How long one request may run after a worker takes it
providers	GPU and provider order. Lower priority is tried first
num_workers	Worker ids one replica token may register

concurrent_workers on the handler can raise num_workers the first time a replica registers, up to 64.

Registries and env

env is a string map copied onto the replica. Pull credentials and Doppler or Cloudflare stores are attached in the dashboard, or passed in registry:

app.deploy(
    image="ghcr.io/example/private:latest",
    entrypoint="python -m surfra.worker",
    registry={"docker_secret_id": "sec_...", "secret_id": "sec_..."},
    autoscale={"min_replicas": 0, "max_replicas": 1, "providers": []},
)

docker_secret_id is a Docker registry credential. secret_id is a credential store. Docker login is checked when the credential is saved. A Doppler store is downloaded into the replica environment at start.