Skip to content

sam local start-api detached mode #1012

Open

Description

@frob

Describe your idea/feature/enhancement

Allow sam local start-api to run detached

Proposal

While SAM is great for local development it can fall short for CI or even test commands. In order to run tests automatically against my api-gateway I need to run sam local start-api this command continues running until I press Ctrl-C. This works well for local development but I would like to script this out into a CI that will allow me to run integration tests without deploying to aws.

Things to consider:

  1. Will this require any updates to the SAM Spec

    • No, as far as I know, this should require any updates to the spec.
  2. Additional arguments/commands

    • By adding a detached mode that also means there must be a non-interrupt way to stop the api. I suggest sam local stop-api as a way to stop the api. This command would be dependent on the directory and template that is running and thus the running instance would be a singleton.
    • I would suggest -d as this would follow the docker command scheme and be more familiar to developers.

Activity

  1. ndobryanskyy commented on Feb 26, 2019

    @ndobryanskyy
    Contributor

    Proposed feature is really handy, I like it, but there are some open questions and to me, this flag seems to be not that simple.

    • As I understood, user would be able to start only single local api-gateway? And stop-api will work from any directory to enable the user to easily stop the service? Or should one be able to start several api-gateways for different templates?
    • SAM should also include the command to attach to the running local api-gateway to examine logs -> which leads us to the fact, that all of the logs should be aggregated somewhere, so the user could examine the recent logs upon attaching.
    • -d flag name is already taken by the --debugger-port option as a shorthand name, so this should be more verbose like --detached or something;

    Does that make sense, @frob?

  2. frob commented on Feb 28, 2019

    @frob
    ContributorAuthor

    Yes that is what I am referring to.

    As I understood, user would be able to start only single local api-gateway? And stop-api will work from any directory to enable the user to easily stop the service? Or should one be able to start several api-gateways for different templates?

    Does SAM CLI currently work with multiple templates? I was thinking of single endpoints, but I could see it being useful for multiple. The purpose for this is for integration testing so as many endpoints as needed for the test and I can see an argument for multiple endpoints being required for a full integration test. Honestly, it is usually these features work better if they start small and then we can add features in another issue.

    SAM should also include the command to attach to the running local api-gateway to examine logs -> which leads us to the fact, that all of the logs should be aggregated somewhere, so the user could examine the recent logs upon attaching .

    I am unclear about this. I kind of think that logging would just follow the current workflow for docker.

    -d flag name is already taken by the --debugger-port option as a shorthand name, so this should be more verbose like --detached or something;

    Good point. Docker run docs use --detach and I suggest we use that.

  3. added
    stage/needs-feedbackNeeds feedback from the community (are you also interested in/experiencing this?)
    on Apr 23, 2019
  4. mmartsen commented on Jun 2, 2020

    @mmartsen

    Can it be just "dockerized"? So instead of running "sam local start-api" we run "docker-compose up"?
    To me it seems doable to generate docker-compose.yml after "sam build" command with all necessary folders mapped. I think majority of CI/CD tools could work with docker-compose, also things like logging, attach/detach are already solved there.

  5. Santiago8888 commented on Aug 24, 2020

    @Santiago8888

    The second time I run into this issue, current use cases:

    1. Test lambdas on CI/CD envs. without deploying them.
    2. Lift multiple API Gateways without opening multiple terminals.
  6. jonowhite commented on Jul 20, 2021

    @jonowhite

    I think this would be really helpful. I have similar use cases, my current method I am testing (which might be a little dodgy) is to send the sam command to the background and redirect all logs to prevent interference.

    sam local start-api  > /dev/null 2>&1 &

    This keeps the local API active while retaining control of the shell. So you could run it multiple times, or re-use the shell to run tests against the local API.

    Potential issue when it comes to stopping the background processes if you have multiple running and need to be careful with which you kill.

  7. tahoward commented on Jul 28, 2021

    @tahoward

    Running into a similar situation. Using this in a Makefile in interim:

    start:
    	sam local start-api --docker-network <network_name> --warm-containers EAGER &
    
    stop:
    	kill $$(ps -wwo pid,args | grep "[/]bin/sam local start-api" | awk '{print $$1}')
    	CONTAINERS=$$(docker network inspect <network_name> | jq -r '.[].Containers[].Name')
    	echo "$$CONTAINERS" | xargs docker stop; echo "$$CONTAINERS" | xargs docker rm
    

    sam local start-api --docker-network <network_name> is used to track any containers spawned by sam. It appears to orphan them when using --warm-containers and PID gets killed.

  8. dschiavu commented on Jan 17, 2023

    @dschiavu

    +1

    Would love to see this command being implemented.

  9. matthew-heyner commented on Mar 3, 2023

    @matthew-heyner

    +1

    This would be helpful.

  10. bnusunny commented on Nov 13, 2026

    @bnusunny
    Contributor

    Reopened: this issue was closed by mistake during a stale-issue sweep. It was not actually waiting on more information from the reporter. Sorry for the noise.

  11. github-actions commented on Nov 13, 2026

    @github-actions
    Contributor

    ⚠️COMMENT VISIBILITY WARNING⚠️

    Comments on closed issues are hard for our team to see.
    If you need more assistance, please either tag a team member or open a new issue that references this one.
    If you wish to keep having a conversation with other community members under this issue feel free to do so.

  12. added
    stage/pm-reviewWaiting for review by our Product Manager, please don't work on this yet
    and removed
    stage/needs-feedbackNeeds feedback from the community (are you also interested in/experiencing this?)
    on Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions