Model 3: Local HTTP Sidecar
When to Use: Microservices architectures, non-Python applications, or when you need HTTP-based integration without deploying to the cloud.
How It Works
The sidecar runs as a local HTTP server, exposing recipes via REST API. Your application communicates over localhost—no external network required.Pros & Cons
- Pros
- Cons
- Polyglot - Any language with HTTP client can use it
- Process isolation - Recipes run in separate process
- Standard HTTP - Familiar REST/JSON interface
- Streaming support - SSE for real-time events
- Auth built-in - API key and JWT authentication
- Hot reload - Update recipes without restart
Step-by-Step Tutorial
1
Install with Serve Dependencies
2
Start the Sidecar Server
3
Verify Server Health
4
List Available Recipes
5
Run a Recipe
API Reference
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Health check |
/v1/recipes | GET | List recipes |
/v1/recipes/{name} | GET | Describe recipe |
/v1/recipes/{name}/schema | GET | Get recipe schema |
/v1/recipes/run | POST | Run recipe (sync) |
/v1/recipes/stream | POST | Run recipe (SSE) |
/v1/recipes/validate | POST | Validate recipe |
Production-Ready Example
Docker Deployment
Troubleshooting
Connection refused
Connection refused
Ensure the server is running:
401 Unauthorized
401 Unauthorized
SSE streaming not working
SSE streaming not working
Ensure you’re using the correct endpoint and headers:
CORS errors in browser
CORS errors in browser
Start the server with CORS enabled:
Security & Ops Notes
Security Considerations
- Bind to localhost - Default
127.0.0.1prevents external access - API key auth - Enable
--auth api-keyfor production - HTTPS - Use a reverse proxy (nginx, traefik) for TLS
- Rate limiting - Configure
rate_limitin serve.yaml - Request size limits - Default 10MB, adjust via
max_request_size
Next Steps
- Remote Managed Runner - For cloud deployments
- Event-Driven - For async processing
- Platform/DevOps Persona - Deployment best practices

