Passenger-style idle shutdown and on-demand wake-up for hosting many low-traffic applications

[komagata]

I would like to discuss whether kamal-proxy could provide an opt-in feature that stops an application container after a period without requests and automatically starts it again when the next request arrives.

I found the following existing draft PRs for essentially this feature:

• Add idle container support (scale-to-zero) #197
• Add idle container configuration for kamal-proxy kamal#1800

I do not want to duplicate or supersede that work. Before doing further implementation, I would first like to confirm whether this use case fits the direction of Kamal and kamal-proxy, and how the existing draft PRs should be handled.

Background

Kamal 2 makes it practical to host multiple independent web applications on a single server.

However, a Rails application continues to consume a meaningful amount of memory through its Puma and Rails processes even when it receives no traffic. In my experience, even a small Rails application can use roughly 150–300 MB per container.

When many low-traffic applications share one server, the limiting resource is therefore often the memory consumed by idle applications, rather than CPU or request throughput.

A concrete use case

I am involved with a programming school where students create Rails applications as their graduation projects.

There is value in keeping these applications publicly available after graduation, both as portfolios and as records of the students' work. However, most receive very little traffic and may go days or weeks without a request.

Many students cannot afford ongoing hosting fees. I would like to provide a minimal hosting environment for them at no cost. If an application becomes genuinely popular, we would ask its owner to move it to a dedicated server or a regular PaaS.

I believe the same mechanism would also be useful for:

• personal collections of small applications
• internal tools
• demo applications
• staging environments
• review apps
• low-traffic customer-specific applications
• temporary test environments

For these applications, a cold-start delay of 10–30 seconds can be acceptable.

Similarity to Passenger

Phusion Passenger has supported a similar execution model for Ruby applications for many years.

Passenger can spawn an application process when a request arrives and shut it down after an idle timeout. It can also limit the total number of application processes running on a server.

What I am considering is applying this proven Passenger-style model at the container level for applications deployed with Kamal.

Expected behavior

Conceptually, I imagine an opt-in flow like this:

1. Deploy the application normally with Kamal.
2. Stop the current web container after a configured period without requests.
3. When kamal-proxy receives the next request for that host, start the target container.
4. Hold the initial request while waiting for the health check to succeed.
5. Forward the held request once the application is ready.
6. Return a 503 or similar response if the application does not become ready before the wake timeout.

A possible configuration might look like this:

proxy:
  host: app.example.com
  idle:
    timeout: 1800
    wake_timeout: 60

I am not proposing this exact configuration or implementation as a requirement. I would prefer whichever design best fits the project.

Non-goals

This is not intended to turn Kamal into a general-purpose orchestrator or PaaS.

At least initially, I think the following can remain out of scope:

• scaling out to multiple replicas based on traffic
• scheduling across multiple servers
• CPU- or memory-based autoscaling
• automatically managing background-job containers
• managing databases, Redis, or other accessories
• general-purpose container orchestration comparable to Kubernetes

The intended scope is an opt-in transition between zero and one web container.

Issues that would need consideration

I understand that this requires more than a simple timer and docker stop / docker start. At minimum, the design should consider:

• coalescing simultaneous wake-up requests into a single start operation
• safely holding POST request bodies
• not stopping while requests are still being processed
• WebSocket and streaming-response behavior
• avoiding idle shutdown during a Kamal deployment
• deploying a new version while the current application is sleeping
• consistent state after a kamal-proxy restart
• container start and health-check failures
• the security implications of mounting the Docker socket into kamal-proxy
• allowing applications with background jobs or other always-on requirements to opt out

Existing draft implementation

As I understand it, kamal-proxy#197 connects directly to the Docker socket and starts or stops the target container itself.

This provides a very simple user experience and does not require an additional service. On the other hand, direct Docker access changes the responsibilities and security profile of kamal-proxy.

One alternative might be for kamal-proxy to expose generic activation and deactivation hooks while delegating Docker operations to a small external lifecycle service.

I do not want to decide between these approaches in advance. I would appreciate guidance from the maintainers about which direction, if either, is appropriate for the project.

Questions

Before proceeding with implementation, I would appreciate feedback on the following:

1. Is hosting many low-traffic applications on one server within the intended scope of Kamal and kamal-proxy?
2. Is Passenger-style idle shutdown and on-demand wake-up worth considering as a kamal-proxy feature?
3. Is direct Docker socket access from kamal-proxy acceptable, as proposed in Add idle container support (scale-to-zero) #197?
4. Would delegating container operations to an external lifecycle service be more appropriate?
5. Should the existing draft PRs Add idle container support (scale-to-zero) #197 and Add idle container configuration for kamal-proxy kamal#1800 be continued and improved?
6. If the existing author would like to continue, would collaboration on implementation and real-world testing be welcome?

If this use case fits the project, I would be happy to collaborate with the existing PR author and help with design, tests, and validation in a real environment.

I would first like to reach agreement on the responsibility and smallest useful scope before doing more implementation work.

[komagata]

A brief update: I have continued validating the existing approach locally, without opening a new PR or pushing changes upstream.

I adapted the draft implementation from #197 and tested it with real Docker containers and a Rails application deployed through Kamal. The prototype successfully:

• stops an idle application container
• starts it again on the next request
• holds the initial request until the health check succeeds
• handles concurrent wake-up requests
• avoids stopping while requests are in flight
• preserves the sleeping state across a kamal-proxy restart

I also addressed several race conditions and failure cases found during testing.

Before preparing any PR, I would still appreciate guidance on the main architectural question: is direct Docker socket access an acceptable responsibility for kamal-proxy, or should container lifecycle operations be delegated externally?

I am happy to share the prototype branch or collaborate with @martijnenco if maintainers would like to explore this direction.

[martijnenco]

Hi!
Well absolutely thank you for taking this one step further, I really really hope that this will see the light of day at some point. For my use case it would be to have review apps our current review app setup with k8s and AWS RDS is an absolute mess. It's slow, buggy, overly complicated and expensive. If we would replace it with something like this it would be so so easy, more reliable and cost friendlier.

Now my code, please don't take it to seriously, it's made with AI, I am completely new in programming in GO. But it might be a strong start.
And on the collaboration part, yeah, if I can help I will gladly do, but currently I still have no opensource contributions and no knowledge of GO, so I am not sure how helpfull I can be..

Now, I do know that @mhenrixon was also working//looking at this in mhenrixon#19.

[komagata]

I published a detailed write-up of the experiment, including the motivation, real-VPS validation results, problems found with real Docker, and instructions for trying the exact forks:

https://docs.komagata.org/6456

The main results were:

• a real Rails container used roughly 200–315 MiB while running and 0 B while stopped
• cold wake through kamal-proxy completed in about 3.15 seconds
• large POST bodies, 20 concurrent wake requests, proxy restarts, failure/retry behavior, and deploys while sleeping were tested successfully
• three independent Rails services could sleep and wake independently

The article links the exact experimental kamal-proxy and Kamal revisions. They are not official releases or upstream PRs, but they are available for anyone who wants to reproduce the experiment.

@martijnenco, the work is based on #197 and includes the review-app use case you described. @mhenrixon, I also referenced the related direction from your issue. Test results from review-app or internal-tool environments would be especially useful.

[kevinmcconnell]

Thanks @komagata and @martijnenco for working on this. I do think it's a great idea, and definitely worth pursuing if we can get an implementation we're happy with. It would be nice to get this capability into Kamal.

is direct Docker socket access an acceptable responsibility for kamal-proxy, or should container lifecycle operations be delegated externally?

This is the biggest tradeoff I think. Mounting the Docker socket is the simplest approach, but effectively it's giving root to the proxy process. I don't think it's a showstopper given it would be opt-in, but worth thinking about alternatives too. The only more restricted alternative that springs to mind would be to have a simple start/stop service on the host and mount access to that instead. But maybe there's a better way -- do you have any other ideas in mind?

[komagata]

Thank you — that is very encouraging.

The main alternative I have considered is a small host-side lifecycle service exposed through a Unix socket. It would have Docker access, but kamal-proxy itself would only be able to request a narrow set of operations such as:

• start this application container
• stop this application container

The service could validate container names against Kamal labels or an explicit allowlist before performing an operation. This would keep the Docker socket out of the proxy container and provide a clearer security boundary.

A few other possibilities seem less attractive:

• A Docker socket proxy can restrict API endpoints and HTTP methods, but it may still allow the proxy to start or stop any container unless it also understands Kamal's container identity.
• A Docker authorization plugin could enforce stronger rules, but it would add considerably more host setup and Docker-specific operational complexity.
• Generic activation/deactivation hooks would be flexible, but coordinating timeouts, failures, readiness, and concurrent wake requests would become more complicated for users.

The current prototype keeps container operations behind a small ContainerLifecycle interface, so the idle controller itself is not tied to direct Docker access. The direct socket client could later be replaced by a host-side service without changing the request, state, or wake-up logic.

My current inclination is to use direct Docker socket access as the smallest opt-in implementation, document the security implications clearly, and preserve the lifecycle interface as the boundary for a more restricted backend. However, if you would prefer the host-side service boundary from the beginning, I can explore that before preparing the draft PR.

@martijnenco has also agreed that I can open new draft PRs based on #197 and basecamp/kamal#1800. I can prepare those once we have a reasonable initial direction for this tradeoff.