the scriptable, rewriting proxy for ruby
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 6 commits behind evaryont:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


            ,  _ .___mouseHole_;:::_web_proxy___. __, .

                      ... rewrite web pages
                       ... run little apps
                        ... crossite ajax
                         ... persistence
                          ... all that!

= about mouseHole =

MouseHole is a personal web proxy written in Ruby designed to be simple to
script.  Scripts can rewrite the web as you view it, altering content and
behavior as you browse.  Basically, it's an alternative to Greasemonkey,
which does similar things from inside the Firefox web browser.

Believe it or not, though, MouseHole does a lot more than that.
Here's a taste of what you'll be seeing:

= running mouseHole =

MouseHole can either intrude completely upon your browsing experience or you
can keep it off in the outskirts, for whenever you've got a second to duck into
that little crack in the wall.  You can run it on one machine and use it
wherever, allowing whomever you want to poke their head in.

The underlying ideas are always the same, though.

* [1] Start MouseHole.
* [2] Visit to view your settings.
* [3] Set MouseHole as your web proxy.
* [4] Install user scripts.
* [5] Or, write your own.

== starting mouseHole ==

To start using mouseHole, simply run the script. On Windows, click on
mouseHole.exe.  On other operating systems, run `ruby bin/mouseHole' from inside the
unpacked mouseHole directory.  A text window should popup showing that
mouseHole is started.

You can pass in the hostname and port number you'd like to run MouseHole on.

* mouseHole to run on publicly accessible IP
* mouseHole 5300 to run on a different port on localhost.

If your Web access itself is through a proxy, set the HTTP_PROXY environment
variable to the IP:PORT of that proxy.

== the doorway ==

Visit the hostname and port you choose above in your browser.  Normally, this
will be  The doorway will appear.  A page with a bit
of mouseHole-related graffitis.  (Once you get the proxy setup, you'll be able
to use http://mh/ or http://mouse.hole/ instead of the IP:PORT.)

The doorway lets you configure the scripts you have installed.  There's not
much to it.  You can turn scripts on and off.  Or you can tell it what sites it
can or can't control.  The doorway will also let you know if a script has been
loaded or if it has errors.

== setting mouseHole as proxy ==

This is the moment of decision.  Will you use mouseHole for your whole browser
experience?  Or will you use it only occassionally?  Or would you like to be
able to turn it on and off at will?

=== using mouseHole exclusively ===

If you're using Firefox, open the Preferences window.  Select the General tab.
Click the Connection Settings button. Activate the Manual Proxy Configuration
settings.  Fill in MouseHole's hostname and port.  (Again, the default is and port 3704.)

If you're on OS X and want to use it to proxy all Safari traffic, go to the
Network preference pane (in System Preferences), select Web Proxy, enter as address and 3704 as port.

=== speeding up with lighttpd or apache2 ===

If you want to go robust, you can run MouseHole through LightTPD/FastCGI (a
free web server) or Apache2/mod_ruby (also free).  The LightTPD seems to work
better for most people, so (if you're on Linux or OSX) give it a try.

You'll need LightTPD, FastCGI, and FCGI-Ruby installed.  Once all are installed,
fire it all up with:

  mouseHole -s lighttpd

You can pass in all the typical commandline options as well, if you like.

  mouseHole -s lighttpd --no-tidy 3704

Logs for script errors are stored in ~/.mouseHole/log.

If you'd like to run Apache2, be sure you have Apache2 and mod_ruby installed.
Then, get it started with:

  mouseHole -s apache2

To stop Apache:

  apachectl -f ~/.mouseHole/temp/apache/httpd.conf -k stop

=== occasional mouseHole ===

Firefox has a few useful extensions for managing proxies.

* [ ProxyButton] which
adds a button to your toolbar. The button turns proxying on and off.

* [ SwitchProxy] adds a
toolbar, a context menu and/or a status bar menu for switching between several
proxies.  The status bar menu is especially handy as it is small, but displays
the name of your current proxy, which you can right-click on to change.

=== using proxyLike ===

ProxyLike is a mouseHole user script which lets you pass URLs into mouseHole
for rewriting on a case-by-case.  To install ProxyLike, you'll need to use
mouseHole as your proxy for a bit.  Once you've got mouseHole running as your
proxy (described above), visit
mouseHole will guide you through the installation.

You can now turn off your proxy settings in your browser.  Pass URLs into
ProxyLike by prefixing the URL with your mouseHole IP:PORT.

* will run Google through mouseHole.
* will view Hoodwink'd
Onslaught through mouseHole.

You can also install scripts through ProxyLike. If you have it installed, you
can upgrade ProxyLike with:

== install user scripts ==

To install a script, simply visit an existing script and MouseHole will
auto-detect this and prompt you for installation.

At this time, there is no way to install a script sitting on your hard drive
(because file:// URLs don't go through proxies) without throwing it in
.mouseHole/userScripts and restarting MouseHole or uploading the script to a
remote server. (1.2 and up detects new scripts in .mouseHole/userScripts and
refreshes them as you edit it.)

A list of known MouseHole scripts is available at UserScripts.

== Making Your Own Scripts ==

For help in writing your own script, see

For debugging purposes, you can visit http://localhost:3704/mouseHole/database
to view a database dump of MouseHole.