API Reference

Create a new server from a dictionary of endpoints. This is the primary method for turning Python functions into HTTP endpoints with automatic process management.

import syft_serve as ss

def predict(data: dict):
    return {"prediction": "positive", "confidence": 0.95}

# Create a server
server = ss.create(
    name="ml_api",
    endpoints={"/predict": predict},
    dependencies=["numpy", "scikit-learn"]
)

print(server.url)  # http://localhost:8000

List all currently running servers. Returns a list of Server objects that you can inspect and control.

# List all servers
servers = ss.list()

for server in servers:
    print(f"{server.name}: {server.url} - {server.status}")

Get a specific server by name. Useful for retrieving a server created in a previous session or different notebook.

# Get a specific server
server = ss.get("ml_api")

# Access server properties
print(f"URL: {server.url}")
print(f"Status: {server.status}")
print(f"Uptime: {server.uptime}")

Server objects have rich display representations in Jupyter notebooks that show status, logs, and control options at a glance.

# In Jupyter, just evaluate the server object
server

# Or get multiple servers
servers = ss.list()
servers  # Shows a list with each server's display

Get the most recent lines from the server's standard output logs. Useful for debugging and monitoring server activity.

# Get recent logs
logs = server.stdout.tail(20)
print(logs)

# Check for errors
errors = server.stderr.tail(20)

Stream logs in real-time as they are generated. This creates a continuous output that follows the log file, similar to `tail -f`.

# Follow logs in real-time
for line in server.stdout.follow():
    print(line)
    if "error" in line.lower():
        break

Get the most recent lines from the server's standard error logs. Useful for debugging errors and tracking warnings.

# Check for errors
errors = server.stderr.tail(20)
if errors:
    print("Recent errors:", errors)

Stream error logs in real-time as they are generated. Perfect for monitoring errors and warnings as they occur.

# Monitor errors in real-time
for error in server.stderr.follow():
    print(f"ERROR: {error}")
    # Send alert or take action

Access the server's environment information including Python version, installed packages, and environment variables.

# Check server environment
print(f"Python: {server.env.python}")
print(f"Packages: {len(server.env.packages)}")

# Find specific package
for pkg in server.env.packages:
    if "numpy" in pkg:
        print(pkg)

Gracefully terminate a server. This stops the server process, cleans up resources, and removes it from the active servers list.

# Terminate a specific server
server = ss.get("ml_api")
server.terminate()

# Or with custom timeout
server.terminate(timeout=10.0)

Terminate all running servers at once. This is useful for cleanup in notebooks or when shutting down a development environment.

# Clean up all servers
results = ss.terminate_all()

print(f"Terminated {results['tracked_terminated']} servers")
if results['orphaned_discovered'] > 0:
    print(f"Also found and terminated {results['orphaned_terminated']} orphaned processes")

Servers can be configured to automatically terminate after a specified time period. This prevents resource leaks and is perfect for temporary endpoints.

# Create a temporary server (5 minutes)
temp_server = ss.create(
    name="temp_endpoint",
    endpoints={"/process": process_data},
    expiration_seconds=300
)

# Create a permanent server
permanent_server = ss.create(
    name="always_on",
    endpoints={"/health": lambda: "OK"},
    expiration_seconds=-1
)

# Check time remaining
print(f"Expires in: {temp_server.expiration_info}")