Simple Web Server

Building a Web Server with FastAPI

Often times you'll want a long-running server where you can make HTTP or WebSocket calls to your WendyOS device. This allows your device to accept incoming requests and respond to them, making it easy to build interactive applications or APIs that can be accessed from other devices on your network.

To prove this out, we'll use FastAPI, a modern, fast (high-performance) web framework for building APIs with Python based on standard Python type hints.

Prerequisites

Wendy CLI installed on your development machine
Python 3.14 installed
Docker installed (see Docker Installation)
A WendyOS device plugged in over USB or connectable over Wi-Fi

Setting Up Your Project

Create a New Directory

First, create a directory for your project:

mkdir simple-server
cd simple-server

Create requirements.txt

Create a requirements.txt file with FastAPI and Uvicorn:

fastapi
uvicorn[standard]

Create the Web Server

Create an app.py file with the following content:

#!/usr/bin/env python3
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Car(BaseModel):
    make: str
    year: int

@app.get("/")
async def root():
    return "hello-world"

@app.get("/json")
async def get_car():
    return Car(make="Tesla", year=2024)

Multiple Routes: This example includes two routes:

GET / - Returns a simple string "hello-world"
GET /json - Returns a JSON object with a Pydantic model

Create a Dockerfile

Create a Dockerfile in the project root:

# Use uv with Python 3.14 (slim variant for better compatibility)
FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim

# Set working directory
WORKDIR /app

# Copy application files
COPY requirements.txt .
COPY app.py .

# Create a non-root user for security
RUN useradd --create-home --shell /bin/bash app && \
    chown -R app:app /app
USER app

# Expose port 8000
EXPOSE 8000

# Run the application with uvicorn, ensuring dependencies are available
CMD ["uv", "run", "--with", "fastapi", "--with", "uvicorn[standard]", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Important: The server runs on 0.0.0.0 and not localhost or 127.0.0.1. This is because your WendyOS device needs to accept connections from other devices on the network. Binding to 0.0.0.0 makes the server accessible externally.

Deploy to WendyOS Device

Deploy your containerized web server to your WendyOS device:

wendy run

You'll see output similar to the following as the CLI discovers your device, builds the container, and starts the server:

wendy run
✔︎ Searching for WendyOS devices [5.0s]
✔︎ Which device do you want to run this app on?: True Probe (wendyos-true-probe.local) [USB, Ethernet, LAN]
i Info
  True Probe
╭───────────┬──────────────────────────────────────────────╮
│ Interface │ Details                                      │
├───────────┼──────────────────────────────────────────────┤
│ USB 3.2   │ VID: 0x1D6B, PID: 0x0104, S/N: 1421325024451 │
│ Ethernet  │ en30, 2.5 Gbps                               │
│ LAN       │ wendyos-true-probe.local                     │
╰───────────┴──────────────────────────────────────────────╯
✔︎ Builder ready [0.1s]
✔︎ Container built and uploaded successfully! [0.4s]
ℹ︎ Preparing app
✔︎ App ready to start [0.1s]
✔ Success
  Started app
Downloading pydantic-core (1.8MiB)
Downloading uvloop
 Downloaded pydantic-core
 Downloaded uvloop
Installed 19 packages in 16ms
INFO:     Started server process [41]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Test Your Server on WendyOS

After deploying your server to your WendyOS device, you can test it from your development machine. As long as your WendyOS device is accessible over USB or the Local Area Network, you can reach it from your browser.

Open up your browser and navigate to:

http://wendyos-true-probe.local:8000

Replace the hostname: Each WendyOS device has a unique hostname. Replace wendyos-true-probe with your device's actual hostname shown in the CLI output. In addition, don't forget to add the port to the hostname.

You should see the following output:

"hello-world"

This confirms your web server is successfully running on your WendyOS device and accepting requests from your network.

Verifying Deployment

You can also verify the server is running by listing the applications on your device:

wendy device apps list
✔︎ Searching for WendyOS devices [5.3s]
✔︎ Listing applications: True Probe [USB, Ethernet, LAN] 
╭───────────────┬─────────┬─────────┬──────────╮
│ App           │ Version │ State   │ Failures │
├───────────────┼─────────┼─────────┼──────────┤
│ simple-server │ 0.0.0   │ Stopped │ 0        │
╰───────────────┴─────────┴─────────┴──────────╯

Explore the API Documentation

FastAPI automatically generates interactive API documentation. After starting your server, visit:

Swagger UI: http://wendyos-true-probe.local:8000/docs
ReDoc: http://wendyos-true-probe.local:8000/redoc

These interfaces let you explore and test your API endpoints interactively. Remember to replace wendyos-true-probe with your device's actual hostname.

Learn More

FastAPI is a fantastic modern web framework for Python with automatic API documentation, type validation, and excellent performance. Learn more by visiting https://fastapi.tiangolo.com/.

Next Steps

Now that you have a basic web server running:

Add more routes to handle different endpoints
Implement POST, PUT, and DELETE routes for a full REST API
Use Pydantic models for request body validation
Connect to WendyOS device features to control hardware via HTTP
Add WebSocket support for real-time communication
Check out FastAPI Examples for comprehensive examples

Simple Web Server

Testing the app on your own machine

On this page