Skip to main content
The SyncServerlessClient is the synchronous Python client for interacting with fal Serverless. Its namespaces and methods mirror the CLI so you can automate the same workflows from Python.

​
Import and Initialize

from fal.api import SyncServerlessClient

client = SyncServerlessClient(
    host=None,     # Optional. Override API host
    api_key=None,  # Optional. If omitted, read from env/profile
    profile=None,  # Optional. Named profile to use
    team=None,     # Optional. Team context for runner ops
)

​
Overview of Namespaces

  • client.apps.* — corresponds to fal apps ...
  • client.runners.* — corresponds to fal runners ...
  • client.deploy(...) — corresponds to fal deploy ...

​
Apps Namespace

Manage your applications: list them, view runners for a specific app, and adjust scaling.

​
List Applications (fal apps list)

apps = client.apps.list()

# Optional app name filter
filtered = client.apps.list(filter="stable")

​
List App Runners (fal apps runners my-app)

app_runners = client.apps.runners("my-app")

# Optional filters
recent = client.apps.runners("my-app", since=datetime.now() - timedelta(hours=1)) # last hour
running_only = client.apps.runners("my-app", state=["running"])                   # by state

​
Scale Application (fal apps scale)

Maps to CLI flags in fal apps scale. Any omitted option keeps the current value. 
client.apps.scale(
    "my-app",
    keep_alive=300,            # seconds
    max_multiplexing=1,
    max_concurrency=10,
    min_concurrency=1,
    request_timeout=600,       # seconds
    startup_timeout=900,       # seconds
    machine_types=["GPU-H100", "GPU-H200"],
    regions=["us-east-1", "us-west-2"],
    concurrency_buffer=1,
    concurrency_buffer_perc=10,
)

​
Runners Namespace

List and manage runners.

​
List Runners (fal runners list)

all_runners = client.runners.list()

# Recent runners only
last_10_min = client.runners.list(since=datetime.now() - timedelta(minutes=10))

​
Keys Namespace

Create and manage API keys that the service uses to authenticate requests. The Python surface mirrors fal keys ....

​
Create Key (fal keys create)

from fal.sdk import KeyScope

# ADMIN keys can manage resources; API keys are limited to app invocation.
key_id, key_secret = client.keys.create(
    scope=KeyScope.ADMIN,          # or KeyScope.API
    description="CI deploy key",
)
print(f"Store securely: {key_id}:{key_secret}")  # secret shown only once

​
List Keys (fal keys list)

keys = client.keys.list()

for key in keys:
    print(key.key_id, key.scope.value, key.alias)  # alias holds the description

​
Revoke Key (fal keys revoke)

client.keys.revoke("key-id-to-revoke")

​
Secrets Namespace

Store configuration values for builds and runtime without hardcoding them. Values are never returned when you list secrets.

​
Set Secret (fal secrets set)

client.secrets.set("MY_API_TOKEN", "s3cr3t-value")

​
List Secrets (fal secrets list)

secrets = client.secrets.list()
for secret in secrets:
    print(secret.name, secret.created_at)

​
Unset Secret (fal secrets unset)

client.secrets.unset("MY_API_TOKEN")

​
Deploy (fal deploy)

Programmatic equivalent of fal deploy. If app_ref is omitted, discovery behavior matches the CLI (e.g., pyproject.toml). 
# Auto-discover
client.deploy()

# Deploy from a file path
client.deploy("path/to/myfile.py")

# Deploy a specific class in a file
client.deploy("path/to/myfile.py::MyApp")

# Deploy by existing app name
client.deploy("my-app")

# With options mirroring CLI flags
client.deploy(
    app_ref="path/to/myfile.py::MyApp",
    app_name="myapp",
    auth="public",                # "private" | "public"
    strategy="rolling"            # "recreate" | "rolling"
    reset_scale=True,             # use previous scaling if False
)

​
Reference

CLI Overview

CLI commands that mirror these methods

API Reference

Full method signatures and types