Skip to main content
The run command starts the Framefox development server with hot-reload capabilities and automatic browser opening.

​
Usage

framefox run [options]

​
Options

​
--port
integer
default:"8000"
Port to run the server on. If the port is in use, the command will automatically try the next available port.
​
-p
integer
Short form of --port
​
--no-browser
boolean
default:"false"
Don’t open the browser automatically when the server starts

​
Examples

​
Start on Default Port

framefox run
Starts the server on port 8000 and opens your browser.

​
Start on Custom Port

framefox run --port 3000
or 
framefox run -p 3000

​
Start Without Browser

framefox run --no-browser
Useful for remote development or when you want to manually open the browser.

​
Combine Options

framefox run --port 9000 --no-browser

​
Example Output

$ framefox run

Starting optimized dev server on port 8000

INFO:     Will watch for changes in these directories: ['src']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345]
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

​
Port Already in Use

$ framefox run

Port 8000 already in use, trying 8001...

Starting optimized dev server on port 8001

INFO:     Uvicorn running on http://127.0.0.1:8001

​
Features

​
Hot Reload

The development server automatically reloads when you modify files in the src directory: 
INFO:     Detected file change in 'src/controller/user_controller.py'
INFO:     Reloading...
INFO:     Application startup complete.
Hot reload is configured with a 0.5-second delay to prevent excessive reloads during rapid file changes.

​
Automatic Port Detection

If the specified port is in use, the command automatically searches for the next available port (up to 10 attempts).

​
Browser Auto-Open

By default, your default browser opens automatically 2 seconds after the server starts, giving it time to fully initialize.

​
Development Mode Settings

When you run the development server, these environment variables are automatically set:
  • FRAMEFOX_DEV_MODE=true - Enables development mode
  • FRAMEFOX_CACHE_ENABLED=true - Enables caching for better performance
  • FRAMEFOX_MINIMAL_SCAN=true - Optimizes container scanning

​
Server Technology

The development server runs on Uvicorn, a lightning-fast ASGI server:
  • Hot reload support
  • Async/await support
  • WebSocket support
  • HTTP/2 support
  • Production-ready (when configured appropriately)

​
Stopping the Server

To stop the server, press: 
CTRL+C
Output: 
^C
Stopping the server...
INFO:     Shutting down
INFO:     Finished server process

​
Accessing Your Application

Once the server is running, access your application at: Replace 8000 with your custom port if specified.

​
Performance Tips

  • The server watches only the src directory for changes to minimize CPU usage
  • A 0.5-second reload delay prevents excessive reloads
  • Service container caching is enabled for faster startup

​
Common Use Cases

​
Development with Database Changes

# Terminal 1: Run the server
framefox run

# Terminal 2: Watch for entity changes and create migrations
framefox database:create-migration
framefox database:upgrade

​
Team Development

For consistent ports across team members, add to your documentation: 
# Always use port 8080 for this project
framefox run --port 8080

​
Remote Development

When developing on a remote server: 
# Don't open browser on remote machine
framefox run --no-browser

# Then access via SSH tunnel or ngrok

​
Troubleshooting

​
Port Already in Use

If you see “Port already in use” errors repeatedly: 
# Find process using the port
lsof -i :8000

# Kill the process
kill -9 <PID>

​
Reload Not Working

Ensure your changes are in the src directory: 
src/
  controller/
  entity/
  repository/
Files outside src won’t trigger reloads.

​
Browser Not Opening

If the browser doesn’t open automatically:
  1. Check if the server started successfully
  2. Manually open http://localhost:8000
  3. Use --no-browser if auto-open is problematic

​
Module Not Found Errors

Ensure you’ve installed all dependencies: 
pip install -r requirements.txt

​
Production Deployment

The framefox run command is for development only. For production, use a production-grade ASGI server configuration.
Production setup: 
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
Or with Gunicorn: 
gunicorn main:app --worker-class uvicorn.workers.UvicornWorker --workers 4

Build docs developers (and LLMs) love

Get started for freeTalk to us