JSON Application Framework

A JSON Web Application Framework for developing lightweight applications interfaced via JSON-encoded HTTP requests. This is ideal for back end applications serving functionality for other applications.

Halcyon consists of two parts, the server application and the client. The server application is similar to a Merb or Rails app, without the need for implementing views, and the client is used to facilitate talking to the application from other applications.

On Rack

Halcyon is a Rack application, meaning that it can sit right along with any other Rack app, such as a Merb or Rails app, and can be manipulated by any kind of Rack middleware/filter. This means that interfacing with Halcyon in unconventional ways is trivial since the Rack specification makes communicating with Rack apps dead simple.


Halcyon is actively being developed by a very small community of developers and contributors. Halcyon has seen a good deal of paradigm shift up until the 0.5.0 release, but with that release its internal API has stabilized and should remain fairly backwards compatible from here on.

The changes made on the way to the 0.5.0 codebase were to remove all of the server-like code to make Halcyon more application-centric and also to model application development and structure to be more Rails- or Merb-like, though this was just the natural evolution of Halcyon's design.


A Gem of Halcyon is available. You can install it with:

$ sudo gem install halcyon

The latest development release can be installed with RubyGems:

$ sudo gem install halcyon --source http://halcyon.rubyforge.org/latest/

Alternatively, you can install the latest development efforts from the git repository, located at github.com/mtodd/halcyon:

$ git clone git://github.com/mtodd/halcyon.git
$ cd halcyon; rake install

Don't forget to install the JSON gem for improved performance:

$ sudo gem install json

More in depth documentation can be found at halcyon.rubyforge.org/docs/installation.html.


After installing a Halcyon app, you can generate a new app, similar to the rails or merb-gen app commands, with this:

$ halcyon init app_name

This will create a directory and generate a skeletal Halcyon application. You can run this application without changing anything; here's how:

$ cd app_name
$ halcyon start -p 4647

A great tutorial to dive right into using Halcyon and writing apps is located at halcyon.rubyforge.org/docs/tutorial.html. This will step you through what to do, what to expect, and what it means.


Please mail bugs, suggestions and patches to <[email protected]>.

You are also welcome to join the #halcyon channel on irc.freenode.net.

Our website is up so stop by and check out what's going down. Our address is halcyon.rubyforge.org/. On there you will find information about our mailing list as well, so do stop by.

Thanks To

  • Bill Marquette, typo correction, reviewing examples

  • Elliott Cable, missing dependency, Thin testing

  • ramstedt, Mongrel on JRuby port numericality issue (#14)

  • Ben Simpson, PHP Client bug fixes

  • Eivind Uggedal, dependencies for Router support of resources











Matt Todd