Login:    Password:      Don't have a username? Register!

Home > Projects > Envoy



Envoy is a standalone file-associations registry, intended for use by both end-users on the desktop, and open-source developers in their own programs.

It can be used with any file-association support in your existing software, providing a consistent interface no matter which desktop environment, browser or mail client you use.


Both bz2 and gzip compressed tarballs of the latest version are available. For Gentoo users, there's also an ebuild available (add motif or gtk2 to your use flags to build the frontend). RPM and DEB versions hopefully coming soon.

If using the tarballs, simply unpack them, cd into the envoy directory created, and issue the usual:

make install

sequence (rembering to do the last as root).


If the installation above worked you will have two new programs in your /usr/local/bin directory (this is just /usr/bin on Gentoo): envoy, a wrapper for the library and consul, a frontend that offers a simple interface for choosing which programs to use for the various file types.

Associate envoy with all filetypes in your other software that traditionally asks you to setup file-associations (such as your browser when downloading a file).

The first time, this will run consul. While you might have many hundreds of programs on your system, relatively few will actually be relevant for viewing files - a media-player, an image-viewer and word-processor will cover the vast majority of day-today usage, for example. To make things simpler, Envoy only lists programs registered with it as "handlers", to make opening a new file-type as quick as possible. Envoy will detect and automatically list many common programs, such as MPlayer, Open Office and Firefox, but if the program you want isn't listed there's no choice but to dive into the file system for now.

Click on "New handler", and a file-selection box will open up (this can take a while the first time). Select the program to add as a new handler, then hit the OK button. You'll see it appear in the list. If you want, you can add any other handlers you know you will need while we're here. When you're done adding handlers, select the specific one you want to use for the type of file being opened - in case you've forgotten, the message at the top of the box will remind you.

That's it. Now whenever you double-click or download that type of file again Envoy will automatically open the correct program. You might not want to use that program for evermore, however. If you want to change a file association, you can run genvoy or xenvoy directly. If you include a file on the command-line, it will assume you want to change the association for that type of file, otherwise it will offer a list of file types, and ask you to pick.

Either way, you'll end up at the handler selection again. Just pick your handler from the list (or add a new one) as before, and your association will be updated for anything using Envoy for it's file associations.


The functionality of Envoy is contained in libenvoy, a shared library you can use in any programs that need to handle launching external files. Proper documentation will be provided once I'm happy the interface is stable, but all the necessary functions are documented in the included header file.

Additionally, from version 0.4 onwards, libenvoy included support for reading from URIs, such as http://casual-tempest.net/main.php or file:///usr/bin/envoy.

It uses a plugin system to handle the different protocols, and currently comes with handlers for file:// and http:// protocols. URIs using either of these can be read (and written to in the case of file://) using a similar API to the common open/read/close API standard.

This exists as just a proof-of-concept currently, but it should be stable and functional.


This is still a beta-release, so if you encounter any bugs, or have any problems, please either let me know on the Envoy mailing list.

Thank you for showing an interest in Envoy, and I hope it proves useful.