Skip to content

fastgrpc dev

Start the development server with hot reload and gRPC server reflection.

fastgrpc dev <file> [--host HOST] [--port PORT]

Arguments

Argument Default Description
<file> required Path to the Python file containing your @service classes
--host 127.0.0.1 Host to bind
--port 50051 Port to bind

What it does

  1. Imports the entry-point file, executing your @service and @rpc decorators.
  2. Detects whether all handlers are sync or async (raises if mixed) and picks the matching gRPC stack.
  3. Runs the codegen pipeline: inspector → lock → validator → proto writer → protoc compiler.
  4. Synthesizes *Servicer subclasses with proto↔dataclass conversion wrappers.
  5. Starts the server with reflection enabled.
  6. Starts the Rust file watcher and rebuilds on every .py change.

Examples

fastgrpc dev main.py
fastgrpc dev main.py --port 50061
fastgrpc dev examples/complex/main.py --host 0.0.0.0 --port 50051

Reflection

Dev mode enables gRPC server reflection. This means clients like grpcurl and Postman can discover the schema at runtime without needing a .proto file:

grpcurl -plaintext localhost:50051 list
# → fastgrpc.UserService
# → grpc.reflection.v1alpha.ServerReflection

grpcurl -plaintext localhost:50051 describe fastgrpc.UserService

grpcurl -plaintext -d '{"user_id": 1}' \
  localhost:50051 fastgrpc.UserService/GetUser

Output

✓ Serving on grpc://127.0.0.1:50051 (async)
Watching . for changes...
↻ reloading (1 file(s) changed)
✓ reloaded on grpc://127.0.0.1:50051

The (async) or (sync) tag tells you which gRPC stack was selected.

Generated artifacts

Everything goes inside .fastgrpc/ (gitignored):

.fastgrpc/
├── fastgrpc.proto         # generated schema
├── fastgrpc_pb2.py        # compiled message classes
└── fastgrpc_pb2_grpc.py   # compiled servicer base

Plus .fastgrpc.lock at the project root (committed; see Lock file).

To get a visible .proto for client teams, use fastgrpc proto or fastgrpc compile.