Serverless Offline is a Serverless Framework plugin that emulates AWS Lambda and API Gateway on your local machine so you can develop and test HTTP functions without deploying to AWS. It spins up a local HTTP server that maps your serverless.yml events to your handler functions, giving you a fast edit-run loop. It is a development-only tool, and treating it like a faithful production replica is where teams get into trouble.
This post covers what the plugin actually does, how to install and run it, and — more to the point — the places where local emulation quietly diverges from the real cloud in ways that matter for security.
Installing serverless-offline
The plugin ships on npm as serverless-offline. Because it is a build-time dependency, install it as a dev dependency:
npm install --save-dev serverless-offline
Then register it in your serverless.yml plugins block:
plugins:
- serverless-offline
Run it with the framework CLI:
npx serverless offline
By default it binds an HTTP listener on localhost:3000 and routes requests to your handlers. You will see each defined function and its route printed at startup. If you searched for npm serverless-offline or npm serverless offline expecting a standalone binary, note that it is always driven through the serverless command — the npm package only adds the plugin.
What it emulates, and what it does not
Serverless Offline reimplements enough of API Gateway and the Lambda runtime to invoke your handlers with a plausible event object and context. That is genuinely useful for iterating on request parsing, routing, and business logic.
What it does not faithfully reproduce is the security boundary. This is the crux of the whole tool. In production, Lambda runs inside AWS with an execution role, resource policies, VPC rules, and API Gateway authorizers all in force. Locally, most of that is either stubbed or absent. Specifically:
- IAM is not enforced. Your handler runs with whatever AWS credentials are in your local environment, not the scoped execution role you defined. Code that would be denied in production because the role lacks a permission will happily succeed locally. You can pass an integration test locally that fails the moment it hits real IAM.
- Authorizers may be bypassed or mocked. Custom Lambda authorizers and Cognito integrations are approximated. Do not conclude that your auth works because a local request went through.
- Networking differs. There is no VPC, no security groups, no private subnet. A handler that reaches a database it should not be able to reach locally will be blocked by network rules in production — or vice versa.
The security lesson: local success proves your logic runs, not that your access controls hold. Authorization must be verified against a real deployment in a staging account.
Guard your local environment file
Serverless projects commonly load secrets from a .env file or from serverless.yml environment blocks. When you run offline, those values are injected into your process exactly as written. Two failure modes recur:
First, developers commit .env. Add it to .gitignore on day one and run a secret scan in CI so a leaked key never lands in history. Second, people point local runs at production resources — a real database, a live queue — because it is convenient. Now a bug in a half-finished handler runs against production data with production credentials. Use isolated dev resources and dev credentials for offline work, always.
Keep the plugin and its dependency tree patched
Like any npm package, serverless-offline and the Serverless Framework itself pull in a transitive dependency tree. Because it is a dev tool, teams tend to leave it un-updated for months, and dev dependencies are a real supply-chain surface — they run on developer machines and in CI, often with broad filesystem and network access. Audit them:
npm audit
Do not dismiss dev-dependency findings just because "it never ships to prod." A malicious or vulnerable build-time package executes in exactly the environment that holds your cloud credentials. An SCA tool such as Safeguard can flag a vulnerable transitive package in your devDependencies that npm audit ranks as low-priority but that actually runs during every local invoke. The SCA product page explains the reachability angle in more depth.
A safe local workflow
Put together, a defensible serverless-offline setup looks like this: install it as a dev dependency, run it only against isolated dev cloud resources with scoped dev credentials, keep .env out of git, and never treat a passing local run as evidence that IAM or authorizers work. Reserve those verifications for a staging deploy where the real controls are in force. Pair that with dependency scanning on your build-time tree and you get the fast local loop without inheriting a false sense of security.
FAQ
Is serverless-offline safe to use in production?
No. It is a development and testing tool that emulates Lambda and API Gateway locally. It is not a production runtime and does not enforce the IAM, networking, and authorizer controls that protect a real deployment. Use it only for local development.
How do I install the serverless-offline npm package?
Install it as a dev dependency with npm install --save-dev serverless-offline, add serverless-offline to the plugins list in your serverless.yml, then run npx serverless offline. It is a plugin for the Serverless Framework, not a standalone command.
Why does my function work offline but fail after deploy?
The most common cause is IAM. Serverless Offline runs your handler with your local AWS credentials, not the scoped execution role, so permission-denied errors only surface after deployment. Networking differences (VPC, security groups) and mocked authorizers are the other frequent culprits. Always verify authorization against a real staging environment.
Do dev dependencies like serverless-offline pose a supply-chain risk?
Yes. Build-time packages run on developer machines and in CI, often where cloud credentials live, so a vulnerable or malicious dev dependency is a genuine risk. Run npm audit and use dependency scanning against your full tree, including devDependencies, rather than assuming only shipped code matters.