Quick Start - Hello World

This guide walks you through building and deploying a Hello World app on fal Serverless. By the end, you will have a working app running on cloud infrastructure with a persistent URL, a Playground for browser-based testing, and client SDK code you can copy into any project. The entire process takes about two minutes. The workflow you will learn here is the same one you will use for every fal app, from simple utilities to production AI models. You write a Python class, test it with fal run, deploy it with fal deploy, and call it with the fal client SDK. Once you are comfortable with this loop, the Deploy Your First Image Generator tutorial shows how to apply it to a real Stable Diffusion XL model.

Before You Start

You’ll need:

Python - we recommend 3.11
A fal account (sign up is free)

Step 1: Install the CLI

pip install fal

Step 2: Authenticate

Get your API key from the fal dashboard and authenticate:

fal auth login

This opens your browser to authenticate with fal. Once complete, your credentials are saved locally.

Step 3: Create Your First App

Create a file called hello_world.py with this simple app:

import fal

class MyApp(fal.App):
    @fal.endpoint("/")
    def run(self) -> dict:
        print("Processing Hello World request...")
        return {"message": "Hello, World!"}

Step 4: Validate Locally with `fal run`

Always validate with fal run before you fal deploy. It boots your app on a temporary worker — running setup() and your endpoints exactly as production will — so import errors, missing dependencies, and model-loading failures surface here instead of as a production crashloop. Skipping this step is the most common way new apps fail on their first deploy.

fal run hello_world.py::MyApp

This starts your app and prints two URLs: a direct HTTP endpoint and a web playground. By default, fal run uses public auth mode so you can test without an API key.

Use --auth private if you want to require API key authentication during development. See Authentication Modes for details.

Once you see Application startup complete, test it with curl using the URL from the output:

curl $FAL_RUN_URL -H 'Content-Type: application/json' -d '{}'

{"message": "Hello, World!"}

You can also use the playground URL to test through a browser interface.

Step 5: Deploy Your App

Once fal run works, deploy to create a persistent URL:

fal deploy hello_world.py::MyApp

This deploys your app to fal’s infrastructure with runners managed automatically based on demand. The output includes your app’s endpoint ID and persistent URL.

Step 6: Call Your Deployed App

Once deployed, you can call your app from any Python or JavaScript application using the fal client SDK.

Python
JavaScript

pip install fal-client

import fal_client

result = fal_client.subscribe("your-username/hello-world", arguments={})
print(result)
# {"message": "Hello, World!"}

npm install @fal-ai/client

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("your-username/hello-world", {
  input: {},
});
console.log(result.data);
// { message: "Hello, World!" }

Replace your-username/hello-world with the endpoint ID shown after deploying. See Calling Your Endpoints for all calling patterns including async queue, streaming, real-time, and webhooks.

Next Steps

From here, the Deploy Your First Image Generator tutorial applies the same workflow to a real Stable Diffusion XL model. To understand how apps are structured and how runners start up and shut down, read App Lifecycle. For all the ways to call your deployed app, including async queue, streaming, real-time, and webhooks, see Calling Your Endpoints.

Setting Up

Model APIs

Serverless

Compute

Organizations

Quick Start - Hello World

Before You Start

Step 1: Install the CLI

Step 2: Authenticate

Step 3: Create Your First App

Step 4: Validate Locally with `fal run`

Step 5: Deploy Your App

Step 6: Call Your Deployed App

Next Steps

​Before You Start

​Step 1: Install the CLI

​Step 2: Authenticate

​Step 3: Create Your First App

​Step 4: Validate Locally with fal run

​Step 5: Deploy Your App

​Step 6: Call Your Deployed App

​Next Steps

Before You Start

Step 1: Install the CLI

Step 2: Authenticate

Step 3: Create Your First App

Step 4: Validate Locally with `fal run`

Step 5: Deploy Your App

Step 6: Call Your Deployed App

Next Steps