Who is the ActionHero?

> npm start

> actionhero@12.2.2 start /Users/evantahler/Projects/actionhero
> node ./bin/actionhero

info: actionhero >> start
2015-11-14 16:01:27 - notice: *** starting actionhero ***
2015-11-14 16:01:27 - info: actionhero member has joined the cluster
2015-11-14 16:01:27 - notice: pid: 36087
2015-11-14 16:01:27 - notice: server ID:
2015-11-14 16:01:27 - info: ensuring the existence of the chatRoom: defaultRoom
2015-11-14 16:01:27 - info: ensuring the existence of the chatRoom: anotherRoom
2015-11-14 16:01:27 - notice: starting server: web
2015-11-14 16:01:27 - notice: starting server: websocket
2015-11-14 16:01:28 - notice: environment: development
2015-11-14 16:01:28 - notice: *** Server Started @ 2015-11-14 16:01:28 ***

ActionHero is a node.js API framework for both tcp sockets, web sockets, and http clients. The goal of ActionHero is to create an easy-to-use toolkit for making reusable & scalable APIs. Clients connected to an ActionHero server can consume the API, consume static content, and communicate with each other.

ActionHero servers can process both requests and tasks (delayed actions like `send e-mail` or other background jobs). ActionHero servers can also run in a cluster (on the same or multiple machines) to work in concert to handle your load.

The ActionHero API defines a single access point and accepts GET, POST, PUT and DELETE input along with persistent connection via TCP or web sockets. You define Actions which handle input and response, such as `userAdd` or `geoLocate`. HTTP, HTTPS, and TCP clients can all use these actions. The ActionHero API is not inherently "RESTful" (which is meaningless for persistent socket connections) but can be extended to be so if you wish.

ActionHero will also serve static files for you, but ActionHero is not a 'rendering' server (like express or rails).


The website and documentation is hosted on GitHub Pages. You can submit pull requests to the master branch's `docs` folder within the ActionHero project.

Documentation Notes

This documentation will always reflect the master branch of ActionHero, and therefore may be slightly ahead of the latest release on NPM.

Getting Started


  • node.js ( >= v4.0.0)
  • npm
  • redis (for cluster support, cache, stats, and tasks); but not required.
# On OSX With Homebrew:

brew install node
brew install redis

# On Ubuntu:

(sudo) apt-get install node
(sudo) apt-get install redis-server

# On Windows:

[download nodeJS](
[download redis](

Install and Quickstart

Get started now:

mkdir ~/project && cd ~/project
npm install actionhero
./node_modules/.bin/actionhero generate
npm install
npm start
  • Create a new directory mkdir ~/project && cd ~/project
  • Checkout the ActionHero source npm install actionhero
  • Use the generator to create a template project ./node_modules/.bin/actionhero generate
  • npm install to install dependencies
  • You can now start up the server: npm start

Visit in your browser to see the ActionHero in action!

You can also opt to install ActionHero globally npm install actionhero -g and then you can just call actionhero start.

Application Structure

# ActionHero Project Layout

|- config
| -- api.js
| -- errors.js
| -- i18n.js
| -- logger.js
| -- redis.js
| -- routes.js
| -- tasks.js
| -- servers
| ---- web.js
| ---- websocket.js
| ---- socket.js
|-- (project settings)
|- actions
|-- (your actions)
|- initializers
|-- (any additional initializers you want)
|- log
|-- (default location for logs)
|- node_modules
|-- (your modules, ActionHero should be npm installed in here)
|- pids
|-- (pidfiles for your running servers)
|- public
|-- (your static assets to be served by /file)
|- servers
|-- (custom servers you may make)
|- tasks
|-- (your tasks)
|- locales
|-- (translation files)
|- tests
|-- (tests for your API)
package.json (be sure to include 'actionhero':'x')

The map to the right describes ActionHero's default project layout.

Actions in /actions will be loaded in automatically, along /initializers and /tasks.

/public will become your application's default static asset location.

If you wish to customize your project's paths, you can do so within config/api.js in the api.config.general.paths section.


Want to see an example application using ActionHero? You can check out the code and follow the detailed guide here ( This project demonstrates many of the core features of ActionHero in a simple project.

All Diagrams

ActionHero Sections

ActionHero Action Request Flow

ActionHero Task Request Flow

Cluster Topology

Redis Configurations


Example Projects

Example Actions

cachetest: This action demonstrates how to handle parameter checking for an action, and how to use the internal cache methods of actionhero to save and recall data provided from a client.

randomNumber: This example shows how to craft a simple action with no input, but to respond differently to clients based on their HTTP method (if it exists)

status: This action will render some statistics about this ActionHero node, and all nodes in the cluster. Useful for health checks.

SimpleFileResponder: This action demonstrates how you can can manually send files from within actions.

JadefileResponder: This snippet is for rendering Jade templates on the server for pushState single page apps in ActionHero. Useful when you need to bootstrap model data on initial page load. It also pre-compiles the templates on server start and will recompile if they change.

oauth: This file is actually 2 actions which are needed to authenticate a user against twitter's API. Note the use of api.cache to save and load the temporary secret tokens, and how to send custom (redirect) headers with ActionHero

Authentication Example: This example contains a working user system (auth, login, user creation, sessions, etc) using redis.

Tic-Tac-Toe API This advanced example demonstrates how to create actions (and initializers) which will enable you to play tic-tac-toe against an AI Player.

Example Clients

node via TCP: You can talk to an ActionHero server from another node project over TCP directly using this package.

node via HTTP/connect: ActionHero has a robust test suite for the web server which users connect.

Angular: You can connect to ActionHero via angular and connect via HTTP or WebSocket (actionheroWebSocket).

Example Initializers

mysql: Use sequilize.js within an initializer

session: use the cache methods and to easily make some session management helpers.

passport: Use the passport package for authentication in ActionHero.

mongo: a MongoDB initializer

Example Tasks

runAction: This (non periodic) task is used to call an action in the background. For example, you might have an action to sendEmail which can be called synchronously by a client, but you also might want to call it in a delayed manner. This is the task for you!

sayHi A very simple example which will just log ‘HELLO' to the command line every 5 seconds.

cleanLogFiles: This periodic task will run on all servers and inspect ActionHero's log directly for large log files, and delete them

pingSocketClients: This periodic task will run on all servers and send a ‘ping' to any connected TCP clients to help them keep their


ActionHero could not be possible with out the help of our community. Thank you all.

Join us on Slack to talk more about ActionHero!