feat: serverless deploy directory

docs/runware_serverless_deploy.md

@@ -6,9 +6,32 @@ Deploy a new serverless application
 
 Create a new serverless application from a Python entry file.
 
-The file is zipped and submitted as the application source. Worker settings
-are supplied via flags (a local project config via 'runware serverless init'
-is planned). Endpoints are derived server-side from the SDK.
+The whole source directory is zipped and submitted as the application source, so
+the entry file can import its own modules and read its own data files. That
+directory is the working directory unless --src-dir says otherwise.
+
+The entry file must live inside the source directory. A relative path is resolved
+inside it; an absolute path is taken as given.
+
+Exclude what the app does not need with a .runwareignore file at the root of the
+source directory; it takes gitignore syntax. A .gitignore is NOT consulted --
+what a project keeps out of version control is a different question from what it
+ships. Either way .env files are never uploaded, and neither are .git,
+__pycache__, .venv, node_modules or the usual build and tool caches.
+
+Environment variables must be supplied here with --env or --env-file. An app's
+environment is frozen into the version this command creates, which is what the
+worker is rendered from, so setting one afterwards with 'apps env set' stores it
+without it ever reaching a pod. Prefer --env-file for anything secret: a value
+passed as --env is visible in the process list and recorded in shell history.
+
+Anything the app downloads at runtime belongs on a --volume. The app runs in a
+sandbox whose filesystem is part of the checkpointed state, so an unmounted
+download is copied into every checkpoint and fetched again on every cold start.
+A volume keeps it out of both.
+
+Worker settings are supplied via flags (a local project config via 'runware
+serverless init' is planned). Endpoints are derived server-side from the SDK.
 
 ```
 runware serverless deploy <file> [flags]
@@ -17,9 +40,23 @@ runware serverless deploy <file> [flags]
 ### Examples
 
 ```
-  # deploy a Python entry file
+  # deploy the current directory, with app.py as the entry point
   runware serverless deploy ./app.py --id my-app --gpu-type h100
 
+  # deploy a project that lives elsewhere; app.py is resolved inside --src-dir
+  runware serverless deploy app.py --src-dir ~/projects/my-app --id my-app --gpu-type h100
+
+  # an entry file in a subdirectory of the project
+  runware serverless deploy src/app.py --src-dir ~/projects/my-app --id my-app --gpu-type h100
+
+  # pass a token to the worker without putting it in the process list
+  printf 'HF_TOKEN=%s' "$token" > .env.deploy
+  runware serverless deploy model.py --id my-app --gpu-type l40s --env-file .env.deploy
+
+  # keep downloaded model weights on persistent node-local storage
+  runware serverless deploy model.py --id my-app --gpu-type l40s \
+    --volume /root/.cache/huggingface
+
   # override worker settings and base image
   runware serverless deploy ./app.py --id my-app --name "My App" \
     --max-workers 2 --idle-ttl 120 --gpu-type h100 \
@@ -30,6 +67,8 @@ runware serverless deploy <file> [flags]
 
 ```
       --base-image string         Builder base image (default "python:3.11-slim")
+      --env stringArray           Environment variable as KEY=VALUE (repeatable)
+      --env-file stringArray      File of KEY=VALUE lines to read environment variables from (repeatable)
       --gpu-type string           GPU type ID (see 'serverless gpus')
       --gpus-per-worker int32     GPUs allocated per worker (default 1)
   -h, --help                      help for deploy
@@ -40,6 +79,8 @@ runware serverless deploy <file> [flags]
       --name string               Display name (defaults to --id)
       --requirement stringArray   Additional pip package to install (repeatable)
       --scaling-delay int32       Scaling delay in seconds (default 10)
+      --src-dir string            Directory to package as the application source (default: the working directory)
+      --volume stringArray        Absolute path inside the app backed by persistent node-local storage (repeatable)
 ```
 
 ### Options inherited from parent commands

go.mod

@@ -5,13 +5,15 @@ go 1.26.4
 require (
 	github.com/briandowns/spinner v1.23.2
 	github.com/charmbracelet/log v1.0.0
+	github.com/go-git/go-git/v5 v5.16.3
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/jedib0t/go-pretty/v6 v6.7.10
 	github.com/oapi-codegen/runtime v1.6.0
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
 	github.com/spf13/cobra v1.10.2
-	golang.org/x/term v0.41.0
+	github.com/spf13/pflag v1.0.10
+	golang.org/x/term v0.45.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -28,10 +30,13 @@ require (
 	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
 	github.com/fatih/color v1.7.0 // indirect
 	github.com/getkin/kin-openapi v0.142.0 // indirect
+	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
+	github.com/go-git/go-billy/v5 v5.6.2 // indirect
 	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/go-openapi/jsonpointer v0.23.1 // indirect
 	github.com/go-openapi/swag/jsonname v0.26.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -45,16 +50,17 @@ require (
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/speakeasy-api/jsonpath v0.6.3 // indirect
 	github.com/speakeasy-api/openapi v1.24.0 // indirect
-	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0 // indirect
+	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
 	golang.org/x/mod v0.38.0 // indirect
+	golang.org/x/net v0.57.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/text v0.40.0 // indirect
 	golang.org/x/tools v0.48.0 // indirect
+	gopkg.in/warnings.v0 v0.1.2 // indirect
 )
 
 tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen

go.sum

@@ -41,6 +41,12 @@ github.com/fsnotify/fsnotify v1.4.9 h1:hsms1Qyu0jgnwNXIxa+/V/PDsU6CfLf6CNO8H7IWo
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
 github.com/getkin/kin-openapi v0.142.0 h1:izj0vBdFprMhitfzaX8sTqztsEQyvwhssBoB6n8NO7w=
 github.com/getkin/kin-openapi v0.142.0/go.mod h1:3BH9M9XDe/y9M5DSvEocVYAYq1w0qrhJHjC/vZi0AaY=
+github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 h1:+zs/tPmkDkHx3U66DAb0lQFJrpS6731Oaa12ikc+DiI=
+github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376/go.mod h1:an3vInlBmSxCcxctByoQdvwPiA7DTK7jaaFDBTtu0ic=
+github.com/go-git/go-billy/v5 v5.6.2 h1:6Q86EsPXMa7c3YZ3aLAQsMA0VlWmy43r6FHqa/UNbRM=
+github.com/go-git/go-billy/v5 v5.6.2/go.mod h1:rcFC2rAsp/erv7CMz9GczHcuD0D32fWzH+MJAU+jaUU=
+github.com/go-git/go-git/v5 v5.16.3 h1:Z8BtvxZ09bYm/yYNgPKCzgWtaRqDTgIKRgIRHBfU6Z8=
+github.com/go-git/go-git/v5 v5.16.3/go.mod h1:4Ge4alE/5gPs30F2H1esi2gPd69R0C39lolkucHBOp8=
 github.com/go-logfmt/logfmt v0.6.1 h1:4hvbpePJKnIzH1B+8OR/JPbTx37NktoI9LE2QZBBkvE=
 github.com/go-logfmt/logfmt v0.6.1/go.mod h1:EV2pOAQoZaT1ZXZbqDl5hrymndi4SY9ED9/z6CO0XAk=
 github.com/go-openapi/jsonpointer v0.23.1 h1:1HBACs7XIwR2RcmItfdSFlALhGbe6S92p0ry4d1GWg4=
@@ -74,6 +80,8 @@ github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpO
 github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOlocH6Fxy8MmwDt+yVQYULKfN0RoTN8A=
+github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99/go.mod h1:1lJo3i6rXxKeerYnT8Nvf0QmHCRC1n8sfWVwXF2Frvo=
 github.com/jedib0t/go-pretty/v6 v6.7.10 h1:B/2qW2Bkv2L6n14PP8o1kx75kWzHOQ3YTluWzg9icac=
 github.com/jedib0t/go-pretty/v6 v6.7.10/go.mod h1:YwC5CE4fJ1HFUDeivSV1r//AmANFHyqczZk+U6BDALU=
 github.com/juju/gnuflag v0.0.0-20171113085948-2ce1bb71843d/go.mod h1:2PavIy+JPciBPrBUjwbNvtwB6RQlve+hkpll6QSNmOE=
@@ -117,10 +125,13 @@ github.com/onsi/gomega v1.7.0/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1Cpa
 github.com/onsi/gomega v1.7.1/go.mod h1:XdKZgCCFLUoM/7CFJVPcG8C1xQ1AJ0vpAezJrB7JYyY=
 github.com/onsi/gomega v1.10.1/go.mod h1:iN09h71vgCQne3DLsj+A5owkum+a2tYe+TOCB1ybHNo=
 github.com/onsi/gomega v1.17.0/go.mod h1:HnhC7FXeEQY45zxNK3PPoIUhzk/80Xly9PcubAlGdZY=
-github.com/onsi/gomega v1.19.0 h1:4ieX6qQjPP/BfC3mpsAtIGGlxTWPeA3Inl/7DtXw1tw=
 github.com/onsi/gomega v1.19.0/go.mod h1:LY+I3pBVzYsTBU1AnDwOSxaYi9WoWiqgwooUqq9yPro=
+github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
+github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
@@ -132,8 +143,9 @@ github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
-github.com/sergi/go-diff v1.1.0 h1:we8PVUC3FE2uYfodKH/nBHMSetSfHDR6scGdBi+erh0=
 github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
+github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 h1:n661drycOFuPLCN3Uc8sB6B/s6Z4t2xvBgU1htSHuq8=
+github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/speakeasy-api/jsonpath v0.6.3 h1:c+QPwzAOdrWvzycuc9HFsIZcxKIaWcNpC+xhOW9rJxU=
 github.com/speakeasy-api/jsonpath v0.6.3/go.mod h1:2cXloNuQ+RSXi5HTRaeBh7JEmjRXTiaKpFTdZiL7URI=
 github.com/speakeasy-api/openapi v1.24.0 h1:opoD27rupX7zBVPq1HkIGLeMOzNNA7JalhYP8q34i04=
@@ -160,8 +172,8 @@ go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
-golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0 h1:985EYyeCOxTpcgOTJpflJUwOeEz0CQOdPt73OzpE9F8=
-golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0/go.mod h1:/lliqkxwWAhPjf5oSOIJup2XcqJaw8RGS6k3TGEc7GI=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
 golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
@@ -199,8 +211,8 @@ golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
-golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -231,11 +243,12 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EV
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
+gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
+gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20191026110619-0b21df46bc1d/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/api/serverless/client.go

@@ -46,6 +46,9 @@ type CodeSourceUpsert = gen.CodeSourceUpsert
 // CodebaseSource is the zipped customer code payload.
 type CodebaseSource = gen.CodebaseSource
 
+// AppVolume is a persistent node-local directory mounted into the application.
+type AppVolume = gen.AppVolume
+
 // WorkerConfig is the live worker configuration on an app.
 type WorkerConfig = gen.WorkerConfig
 

internal/cmd/serverless/deploy.go

@@ -24,19 +24,60 @@ func newDeployCmd(logger *log.Logger) *cobra.Command {
 		requirements  []string
 		minWorkers    int32
 		gpusPerWorker int32
+		srcDir        string
+		volumes       []string
+		envVars       []string
+		envFiles      []string
 	)
 
 	cmd := &cobra.Command{
 		Use:   "deploy <file>",
 		Short: "Deploy a new serverless application",
 		Long: `Create a new serverless application from a Python entry file.
 
-The file is zipped and submitted as the application source. Worker settings
-are supplied via flags (a local project config via 'runware serverless init'
-is planned). Endpoints are derived server-side from the SDK.`,
-		Example: `  # deploy a Python entry file
+The whole source directory is zipped and submitted as the application source, so
+the entry file can import its own modules and read its own data files. That
+directory is the working directory unless --src-dir says otherwise.
+
+The entry file must live inside the source directory. A relative path is resolved
+inside it; an absolute path is taken as given.
+
+Exclude what the app does not need with a .runwareignore file at the root of the
+source directory; it takes gitignore syntax. A .gitignore is NOT consulted --
+what a project keeps out of version control is a different question from what it
+ships. Either way .env files are never uploaded, and neither are .git,
+__pycache__, .venv, node_modules or the usual build and tool caches.
+
+Environment variables must be supplied here with --env or --env-file. An app's
+environment is frozen into the version this command creates, which is what the
+worker is rendered from, so setting one afterwards with 'apps env set' stores it
+without it ever reaching a pod. Prefer --env-file for anything secret: a value
+passed as --env is visible in the process list and recorded in shell history.
+
+Anything the app downloads at runtime belongs on a --volume. The app runs in a
+sandbox whose filesystem is part of the checkpointed state, so an unmounted
+download is copied into every checkpoint and fetched again on every cold start.
+A volume keeps it out of both.
+
+Worker settings are supplied via flags (a local project config via 'runware
+serverless init' is planned). Endpoints are derived server-side from the SDK.`,
+		Example: `  # deploy the current directory, with app.py as the entry point
   runware serverless deploy ./app.py --id my-app --gpu-type h100
 
+  # deploy a project that lives elsewhere; app.py is resolved inside --src-dir
+  runware serverless deploy app.py --src-dir ~/projects/my-app --id my-app --gpu-type h100
+
+  # an entry file in a subdirectory of the project
+  runware serverless deploy src/app.py --src-dir ~/projects/my-app --id my-app --gpu-type h100
+
+  # pass a token to the worker without putting it in the process list
+  printf 'HF_TOKEN=%s' "$token" > .env.deploy
+  runware serverless deploy model.py --id my-app --gpu-type l40s --env-file .env.deploy
+
+  # keep downloaded model weights on persistent node-local storage
+  runware serverless deploy model.py --id my-app --gpu-type l40s \
+    --volume /root/.cache/huggingface
+
   # override worker settings and base image
   runware serverless deploy ./app.py --id my-app --name "My App" \
     --max-workers 2 --idle-ttl 120 --gpu-type h100 \
@@ -48,7 +89,17 @@ is planned). Endpoints are derived server-side from the SDK.`,
 				name = id
 			}
 
-			zipBase64, modelFile, err := packPythonFile(entryFile)
+			zipBase64, modelFile, err := packDirectory(srcDir, entryFile)
+			if err != nil {
+				return err
+			}
+
+			appVolumes, err := buildVolumes(volumes)
+			if err != nil {
+				return err
+			}
+
+			appEnv, err := buildEnvironmentVariables(envFiles, envVars)
 			if err != nil {
 				return err
 			}
@@ -66,9 +117,11 @@ is planned). Endpoints are derived server-side from the SDK.`,
 			}
 
 			body := serverlessapi.AppCreate{
-				AppId:     id,
-				AppName:   name,
-				AppSource: source,
+				AppId:                id,
+				AppName:              name,
+				AppSource:            source,
+				Volumes:              appVolumes,
+				EnvironmentVariables: appEnv,
 				Configuration: serverlessapi.WorkerConfigCreate{
 					MaxWorkers:       maxWorkers,
 					IdleTtlSecs:      idleTTL,
@@ -94,6 +147,10 @@ is planned). Endpoints are derived server-side from the SDK.`,
 		},
 	}
 
+	cmd.Flags().StringVar(&srcDir, "src-dir", "", "Directory to package as the application source (default: the working directory)")
+	cmd.Flags().StringArrayVar(&volumes, "volume", nil, "Absolute path inside the app backed by persistent node-local storage (repeatable)")
+	cmd.Flags().StringArrayVar(&envVars, "env", nil, "Environment variable as KEY=VALUE (repeatable)")
+	cmd.Flags().StringArrayVar(&envFiles, "env-file", nil, "File of KEY=VALUE lines to read environment variables from (repeatable)")
 	cmd.Flags().StringVar(&id, "id", "", "Application ID (immutable, lowercase slug)")
 	cmd.Flags().StringVar(&name, "name", "", "Display name (defaults to --id)")
 	cmd.Flags().Int32Var(&maxWorkers, "max-workers", 1, "Maximum number of workers")