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.secrets.* — corresponds to fal secrets ...
  • client.keys.* — corresponds to fal keys ...
  • client.environments.* — corresponds to fal environments ...
  • 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 apps in a specific environment
staging_apps = client.apps.list(environment_name="staging")

​
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

# List runners for an app in a specific environment
staging_runners = client.apps.runners("my-app", environment_name="staging")

​
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,
    environment_name="staging",  # target environment
)

​
Rollout Application (fal apps rollout)

client.apps.rollout("my-app")

# Force rollout
client.apps.rollout("my-app", force=True)

# Rollout in a specific environment
client.apps.rollout("my-app", environment_name="staging")

​
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")

# Set secret in a specific environment
client.secrets.set("MY_API_TOKEN", "staging-value", environment_name="staging")

​
List Secrets (fal secrets list)

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

# List secrets for a specific environment
staging_secrets = client.secrets.list(environment_name="staging")

​
Unset Secret (fal secrets unset)

client.secrets.unset("MY_API_TOKEN")

# Unset secret in a specific environment
client.secrets.unset("MY_API_TOKEN", environment_name="staging")

​
Environments Namespace

Create and manage environments to organize your applications and secrets across different stages (development, staging, production).

​
Create Environment (fal environments create)

env = client.environments.create("staging", description="Staging environment")
print(f"Created: {env.name}")

​
List Environments (fal environments list)

environments = client.environments.list()
for env in environments:
    print(env.name, env.description, env.is_default)

​
Delete Environment (fal environments delete)

client.environments.delete("staging")
Deleting an environment removes all apps and secrets in that environment.

​
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
    environment_name="staging",   # target environment
)

​
Reference

CLI Overview

CLI commands that mirror these methods

API Reference

Full method signatures and types