Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A proxy for developing locally against a remote server.
Latest commit 4f704b7 @whylom Correct typo.


Proximo is an easily configurable proxy for developing locally against a remote server.

Why would you desire such a thing? I envy anyone who has never encountered a legacy application so mysterious and monstrous that a single development environment (configured before the dawn of recorded history) must be shared among all developers. Code changes must be manually uploaded to the shared development environment before they are confirmed to work. The environment starts to drift farther and farther away from what's in source control.

Proximo makes this situation far more tolerable by letting you work locally with static files (HTML, CSS, JavaScript). It is a tiny Sinatra app that serves local files if it finds them in the specified directory. Otherwise it acts as a proxy, forwarding incoming requests to a remote server and serving the result.


  1. Download or clone this repository.

  2. Copy or rename proximo.example.yml to proximo.yml.

  3. Customize proximo.yml.

  4. Customize hosts file with the local hostnames required.

  5. Start server with sudo ruby proximo.rb


This is a minimal configuration. Requests directed to (mapped to in your hosts file) will use this configuration. The server attempts to serve the requested file from the docroot. If not found, it forwards the request to the remote server.
  docroot: ~/apps/foo

You can also specify that certain requests should always be forwarded to the remote server, even if they exist in the docroot. This is useful for JSP, ASP, PHP files that you cannot be served dynamically from your machine.
  docroot: ~/apps/foo
    - /time
    - *.php

If you are unfortunate enough to need to forward requests to multiple remote hosts (we were) you can use this alternative format for specifying the remotes:
  docroot: ~/apps/foo
      - for: /articles/*
        use: localhost:3000


This app was a quick hack that solved a real-life problem and saved lives. But I'm not happy with the central configuration file, and the need to hack on your hosts file. Here's what I'd like to improve:

  • Package as a gem, with a proximo binary that accepts basic configuration (port, remote host, etc.) as command-line arguments.
  • Allow more complex configuration to be versioned in a .proximo file that is automatically picked up by the Proximo binary.
  • Refactor proxy to forward all HTTP headers automatically.
  • Refactor to use Rack instead of Sinatra.
Something went wrong with that request. Please try again.