@@ -38,7 +38,8 @@ import (
 // Inherited: Init.
 // Overridden: Load (fastapi puts source under ./code, discovers REST
 // endpoint), Update (applies builder templates), Sync (gRPC codegen for
-// declared dependencies), Build (custom DockerTemplating + docker build),
+// declared dependencies and the optional service-owned gRPC server), Build
+// (custom DockerTemplating + docker build),
 // Deploy (k8s), Create (two-question Communicate + REST endpoint).
 type Builder struct {
 	*pythonbuilder.Builder
@@ -129,9 +130,30 @@ func (s *Builder) Sync(ctx context.Context, _ *builderv0.SyncRequest) (*builderv
 			return s.Base.Builder.SyncError(err)
 		}
 	}
+
+	if s.FastAPI.Settings.GRPCServer.Enabled {
+		if err := s.syncGRPCServer(ctx); err != nil {
+			return s.Base.Builder.SyncError(err)
+		}
+	}
 	return s.Base.Builder.SyncResponse()
 }
 
+// syncGRPCServer regenerates the Python protobuf + grpc.aio server stubs from
+// the service-owned proto contract via Buf. Generation is cached on the proto
+// tree, so it re-runs deterministically only when the contract changes.
+func (s *Builder) syncGRPCServer(ctx context.Context) error {
+	buf, err := proto.NewBuf(ctx, s.Local("code"))
+	if err != nil {
+		return s.Wool.Wrapf(err, "cannot create proto generator")
+	}
+	buf.WithGeneratedDirs(s.Local("code/src/rpc/_generated"))
+	if err := buf.Generate(ctx); err != nil {
+		return s.Wool.Wrapf(err, "cannot generate grpc server code")
+	}
+	return nil
+}
+
 // Env + DockerTemplating structs are the template context for the
 // builder Dockerfile.
 type Env struct {
@@ -247,7 +269,13 @@ func (s *Builder) Upgrade(ctx context.Context, req *builderv0.UpgradeRequest) (*
 }
 
 // Parameters is the template parameter set for the k8s deployment.
-type Parameters struct{}
+type Parameters struct {
+	// GRPCEnabled adds the gRPC containerPort and Service port to the rendered
+	// manifests. GRPCPort is the fixed in-cluster port the grpc.aio listener
+	// binds (the app defaults to it when CODEFLY_GRPC_PORT is unset).
+	GRPCEnabled bool
+	GRPCPort    int
+}
 
 // Deploy renders and applies k8s manifests.
 func (s *Builder) Deploy(ctx context.Context, req *builderv0.DeploymentRequest) (*builderv0.DeploymentResponse, error) {
@@ -260,7 +288,10 @@ func (s *Builder) Deploy(ctx context.Context, req *builderv0.DeploymentRequest)
 			OwnConfiguration:         true,
 			DependencyConfigurations: true,
 		},
-		Parameters: Parameters{},
+		Parameters: Parameters{
+			GRPCEnabled: s.FastAPI.Settings.GRPCServer.Enabled,
+			GRPCPort:    int(standards.Port(standards.GRPC)),
+		},
 	})
 }
 
@@ -269,6 +300,7 @@ func (s *Builder) Options() []*agentv0.Question {
 	return []*agentv0.Question{
 		communicate.NewConfirm(&agentv0.Message{Name: PublicEndpoint, Message: "Expose API as public", Description: "is that directly accessible from the internet?"}, true),
 		communicate.NewConfirm(&agentv0.Message{Name: HotReload, Message: "Code hot-reload (Recommended)?", Description: "codefly can restart your service when code changes are detected 🔎"}, true),
+		communicate.NewConfirm(&agentv0.Message{Name: GRPCServer, Message: "Add a gRPC server?", Description: "runs a grpc.aio listener alongside FastAPI with a proto contract ⚙️"}, false),
 	}
 }
 
@@ -277,6 +309,10 @@ type CreateConfiguration struct {
 	*services.Information
 	Image *resources.DockerImage
 	Envs  []string
+
+	// GRPCEnabled gates the gRPC boot in src/main.py and the grpcio
+	// dependencies in pyproject.toml. False keeps the REST-only scaffold.
+	GRPCEnabled bool
 }
 
 // Create applies factory templates, scaffolds src/tests dirs, and
@@ -295,11 +331,21 @@ func (s *Builder) Create(ctx context.Context, _ *builderv0.CreateRequest) (*buil
 		}
 	}
 
-	create := CreateConfiguration{Information: s.Information, Envs: []string{}}
+	create := CreateConfiguration{Information: s.Information, Envs: []string{}, GRPCEnabled: s.FastAPI.Settings.GRPCServer.Enabled}
 	if err := s.Base.Templates(ctx, create, services.WithFactory(factoryFS)); err != nil {
 		return s.Base.Builder.CreateError(err)
 	}
 
+	// The gRPC scaffold (proto contract, buf config, grpc.aio server + user
+	// servicer seam) is applied from a separate tree only when opted in, so a
+	// REST-only service keeps its generated layout untouched.
+	if s.FastAPI.Settings.GRPCServer.Enabled {
+		grpc := services.WithTemplate(grpcFS, "grpc", "").WithOverride(shared.SkipAll())
+		if err := s.Base.Templates(ctx, create, grpc); err != nil {
+			return s.Base.Builder.CreateError(err)
+		}
+	}
+
 	// Scaffold package + tests dirs with empty __init__.py.
 	if _, err := shared.CheckDirectoryOrCreate(ctx, s.Local("code/src")); err != nil {
 		return s.Base.Builder.CreateError(err)
@@ -347,9 +393,39 @@ func (s *Builder) CreateEndpoints(ctx context.Context) error {
 	}
 	s.FastAPI.RestEndpoint = api
 	s.Endpoints = []*basev0.Endpoint{s.FastAPI.RestEndpoint}
+
+	if s.FastAPI.Settings.GRPCServer.Enabled {
+		grpcEndpoint, grpcErr := s.grpcEndpoint(ctx)
+		if grpcErr != nil {
+			return grpcErr
+		}
+		s.FastAPI.GRPCEndpoint = grpcEndpoint
+		s.Endpoints = append(s.Endpoints, grpcEndpoint)
+	}
 	return nil
 }
 
+// grpcEndpoint builds the service-owned gRPC endpoint from the proto contract.
+// The proto path is resolved relative to the Python source dir (code/), where
+// the scaffolded proto/ tree and the generated stubs both live. It inherits the
+// same public/private visibility as the REST endpoint.
+func (s *Builder) grpcEndpoint(ctx context.Context) (*basev0.Endpoint, error) {
+	protoPath := s.Local("code/%s", s.FastAPI.Settings.GRPCServer.Proto)
+	grpc, err := resources.LoadGrpcAPI(ctx, shared.Pointer(protoPath))
+	if err != nil {
+		return nil, s.Wool.Wrapf(err, "cannot load grpc proto %q", protoPath)
+	}
+	endpoint := s.Base.BaseEndpoint(standards.GRPC)
+	if s.FastAPI.Settings.PublicEndpoint {
+		endpoint.Visibility = resources.VisibilityPublic
+	}
+	api, err := resources.NewAPI(ctx, endpoint, resources.ToGrpcAPI(grpc))
+	if err != nil {
+		return nil, s.Wool.Wrapf(err, "cannot create grpc api")
+	}
+	return api, nil
+}
+
 // isFileNotExistErr matches the bespoke "file does not exist" error string
 // that resources.LoadRestAPI returns for missing files — it doesn't wrap
 // os.ErrNotExist, so errors.Is can't catch it directly.
@@ -365,9 +441,21 @@ func (s *Builder) populateSettingsFromAnswers() error {
 	if s.FastAPI.Settings.PublicEndpoint, err = communicate.Confirm(s.answers, PublicEndpoint); err != nil {
 		return err
 	}
+	if s.FastAPI.Settings.GRPCServer.Enabled, err = communicate.Confirm(s.answers, GRPCServer); err != nil {
+		return err
+	}
+	s.applyGRPCDefaults()
 	return nil
 }
 
+// applyGRPCDefaults fills the proto path when the server is enabled but the
+// path was left blank (interactive answers and defaults never set it).
+func (s *Builder) applyGRPCDefaults() {
+	if s.FastAPI.Settings.GRPCServer.Enabled && s.FastAPI.Settings.GRPCServer.Proto == "" {
+		s.FastAPI.Settings.GRPCServer.Proto = defaultProtoPath
+	}
+}
+
 func (s *Builder) populateSettingsFromDefaults() error {
 	opts := s.Options()
 	var err error
@@ -377,6 +465,10 @@ func (s *Builder) populateSettingsFromDefaults() error {
 	if s.FastAPI.Settings.PublicEndpoint, err = communicate.GetDefaultConfirm(opts, PublicEndpoint); err != nil {
 		return err
 	}
+	if s.FastAPI.Settings.GRPCServer.Enabled, err = communicate.GetDefaultConfirm(opts, GRPCServer); err != nil {
+		return err
+	}
+	s.applyGRPCDefaults()
 	return nil
 }
 
@@ -400,6 +492,12 @@ func renderFromFactory(ctx context.Context, info *services.Information) (string,
 //go:embed templates/factory
 var factoryFS embed.FS
 
+// all: so the scaffold's dotfiles (code/.gitignore) are embedded — go:embed
+// skips names beginning with "." without it.
+//
+//go:embed all:templates/grpc
+var grpcFS embed.FS
+
 //go:embed templates/builder
 var builderFS embed.FS
 
 
@@ -0,0 +1,165 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"testing"
+	"time"
+
+	basev0 "github.com/codefly-dev/core/generated/go/codefly/base/v0"
+	agentv0 "github.com/codefly-dev/core/generated/go/codefly/services/agent/v0"
+	builderv0 "github.com/codefly-dev/core/generated/go/codefly/services/builder/v0"
+	"github.com/codefly-dev/core/resources"
+	"github.com/codefly-dev/core/shared"
+	"github.com/codefly-dev/core/standards"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+
+	agenttesting "github.com/codefly-dev/core/agents/testing"
+)
+
+// TestSettingsParseGRPCServer proves the nested grpc-server block round-trips
+// through the flat inline-embedded Settings and defaults to disabled.
+func TestSettingsParseGRPCServer(t *testing.T) {
+	var enabled Settings
+	require.NoError(t, yaml.Unmarshal([]byte(`
+python-version: "3.12"
+grpc-server:
+  enabled: true
+  proto: proto/api.proto
+`), &enabled))
+	require.True(t, enabled.GRPCServer.Enabled)
+	require.Equal(t, "proto/api.proto", enabled.GRPCServer.Proto)
+
+	var absent Settings
+	require.NoError(t, yaml.Unmarshal([]byte(`python-version: "3.12"`), &absent))
+	require.False(t, absent.GRPCServer.Enabled)
+}
+
+func confirmAnswer(value bool) *agentv0.Answer {
+	return &agentv0.Answer{Value: &agentv0.Answer_Confirm{Confirm: &agentv0.ConfirmAnswer{Confirmed: value}}}
+}
+
+// createServiceForTest drives Load + Create in a temp workspace, mirroring the
+// setup in main_test but stopping before Runtime so it needs no docker/network.
+func createServiceForTest(t *testing.T, answers map[string]*agentv0.Answer) (*Builder, string) {
+	t.Helper()
+	ctx := context.Background()
+	tmpDir, err := os.MkdirTemp("testdata", "grpc")
+	require.NoError(t, err)
+	tmpDir = shared.MustSolvePath(tmpDir)
+	t.Cleanup(func() { _ = os.RemoveAll(tmpDir) })
+
+	serviceName := fmt.Sprintf("svc-%v", time.Now().UnixMilli())
+	service := resources.Service{Name: serviceName, Version: "0.0.0"}
+	require.NoError(t, service.SaveAtDir(ctx, path.Join(tmpDir, fmt.Sprintf("mod/%s", service.Name))))
+
+	identity := &basev0.ServiceIdentity{
+		Name:                service.Name,
+		Version:             service.Version,
+		Module:              "mod",
+		Workspace:           "test",
+		WorkspacePath:       tmpDir,
+		RelativeToWorkspace: fmt.Sprintf("mod/%s", service.Name),
+	}
+
+	svc := NewService()
+	builder := NewBuilder(svc)
+
+	communicate := answers != nil
+	_, err = builder.Load(ctx, &builderv0.LoadRequest{Identity: identity, CreationMode: &builderv0.CreationMode{Communicate: communicate}})
+	require.NoError(t, err)
+	if communicate {
+		builder.answers = answers
+	}
+
+	_, err = builder.Create(ctx, &builderv0.CreateRequest{})
+	require.NoError(t, err)
+	return builder, path.Join(tmpDir, fmt.Sprintf("mod/%s", service.Name))
+}
+
+// TestCreateRESTOnlyByDefault pins the untouched REST-only layout: one
+// endpoint, no proto tree, and no gRPC dependencies or boot code leaking into
+// the scaffold.
+func TestCreateRESTOnlyByDefault(t *testing.T) {
+	builder, root := createServiceForTest(t, nil)
+
+	require.False(t, builder.FastAPI.Settings.GRPCServer.Enabled)
+	require.Equal(t, 1, len(builder.Endpoints))
+	require.Nil(t, builder.FastAPI.GRPCEndpoint)
+
+	_, err := os.Stat(filepath.Join(root, "code/proto/api.proto"))
+	require.True(t, os.IsNotExist(err))
+	_, err = os.Stat(filepath.Join(root, "code/src/rpc/server.py"))
+	require.True(t, os.IsNotExist(err))
+
+	pyproject, err := os.ReadFile(filepath.Join(root, "code/pyproject.toml"))
+	require.NoError(t, err)
+	require.NotContains(t, string(pyproject), "grpcio")
+
+	main, err := os.ReadFile(filepath.Join(root, "code/src/main.py"))
+	require.NoError(t, err)
+	require.NotContains(t, string(main), "CODEFLY_GRPC_PORT")
+}
+
+// TestCreateWithGRPCServer proves opting in scaffolds the proto contract, the
+// server/servicer seam, the dependencies and boot code, and advertises a
+// second gRPC endpoint alongside REST.
+func TestCreateWithGRPCServer(t *testing.T) {
+	builder, root := createServiceForTest(t, map[string]*agentv0.Answer{
+		HotReload:      confirmAnswer(false),
+		PublicEndpoint: confirmAnswer(false),
+		GRPCServer:     confirmAnswer(true),
+	})
+
+	require.True(t, builder.FastAPI.Settings.GRPCServer.Enabled)
+	require.Equal(t, defaultProtoPath, builder.FastAPI.Settings.GRPCServer.Proto)
+
+	require.Equal(t, 2, len(builder.Endpoints))
+	require.NotNil(t, builder.FastAPI.GRPCEndpoint)
+	require.Equal(t, standards.GRPC, builder.FastAPI.GRPCEndpoint.Api)
+
+	for _, rel := range []string{
+		"code/proto/api.proto",
+		"code/proto/buf.gen.yaml",
+		"code/src/rpc/server.py",
+		"code/src/rpc/servicer.py",
+		"code/tests/rpc/test_grpc.py",
+		"code/.gitignore",
+	} {
+		_, err := os.Stat(filepath.Join(root, rel))
+		require.NoError(t, err, "expected scaffolded file %s", rel)
+	}
+
+	pyproject, err := os.ReadFile(filepath.Join(root, "code/pyproject.toml"))
+	require.NoError(t, err)
+	require.Contains(t, string(pyproject), "grpcio")
+	require.Contains(t, string(pyproject), "grpcio-tools")
+
+	main, err := os.ReadFile(filepath.Join(root, "code/src/main.py"))
+	require.NoError(t, err)
+	require.Contains(t, string(main), "CODEFLY_GRPC_PORT")
+	require.Contains(t, string(main), "from src.rpc.server import serve")
+}
+
+// TestDeploymentRendersGRPCPort proves the gRPC container/service ports appear
+// only when the deployment parameters opt in.
+func TestDeploymentRendersGRPCPort(t *testing.T) {
+	enabled := agenttesting.AssertKustomizeTemplates(t, deploymentFS, Parameters{GRPCEnabled: true, GRPCPort: 9090})
+	svc, err := os.ReadFile(filepath.Join(enabled, "base", "service.yaml"))
+	require.NoError(t, err)
+	require.Contains(t, string(svc), "grpc-port")
+	require.Contains(t, string(svc), "9090")
+
+	deployment, err := os.ReadFile(filepath.Join(enabled, "base", "deployment.yaml"))
+	require.NoError(t, err)
+	require.Contains(t, string(deployment), "containerPort: 9090")
+
+	disabled := agenttesting.AssertKustomizeTemplates(t, deploymentFS, Parameters{})
+	svc, err = os.ReadFile(filepath.Join(disabled, "base", "service.yaml"))
+	require.NoError(t, err)
+	require.NotContains(t, string(svc), "grpc-port")
+}