Your First Isolated Environment

In this tutorial, we will create two isolated development environments for two different git branches. Both environments will run simultaneously on unique ports without interfering with each other. Along the way, we will learn how to manage these environments using the hako CLI.

Prerequisites

We need a git repository with a Node.js project. The project must use the PORT environment variable to determine which port to listen on.

If you do not have a project ready, create a new directory and add this package.json file:

{
  "name": "hako-tutorial",
  "version": "1.0.0",
  "scripts": {
    "dev": "node -e \"const http = require('http'); const port = process.env.PORT || 3000; http.createServer((req, res) => { res.writeHead(200); res.end('Hello from ' + process.env.HAKO_BRANCH); }).listen(port); console.log('Server running on port ' + port);\""
  }
}

Ensure you have initialized a git repository and committed this file:

git init
git add package.json
git commit -m "Initial commit"

Create the first environment

Let's create our first environment for a new feature branch called feature-auth. We will use the --start flag to immediately boot the environment.

Run the following command in your terminal:

hako new feature-auth --start

The output should look something like this:

[info] Creating worktree for feature-auth...
[info] Generating .env.hako...
[info] Starting environment feature-auth...
[success] Environment feature-auth is running on port 40000

Notice that hako automatically created a git worktree and allocated a port from its managed range. You can verify the environment is running by visiting http://localhost:40000 in your browser or using curl:

curl http://localhost:40000

You should see the message Hello from feature-auth.

Inspect the environment

We can check the status of our environments at any time. Let's see what hako has created.

Run hako ls to list all active environments:

hako ls

You should see feature-auth listed as running. To see the specific port allocation, run:

hako ports feature-auth

This shows the base port and any other ports allocated to this environment. For more details on how hako manages these ports, see the port allocation explanation.

Create a second environment

The power of hako is running multiple branches at once. Let's create a second environment for feature-payments.

hako new feature-payments --start

The output will show a different port:

[info] Creating worktree for feature-payments...
[info] Generating .env.hako...
[info] Starting environment feature-payments...
[success] Environment feature-payments is running on port 40100

We now have two branches running simultaneously. Verify the second environment:

curl http://localhost:40100

You should see Hello from feature-payments.

Verify isolation

Both environments are completely isolated. They use different directories and different ports. Run hako ports without arguments to see both:

hako ports

You will see two distinct port blocks. Each environment has its own .env.hako file in its worktree directory, which hako uses to inject the correct PORT and other variables.

View logs

If you need to debug an environment, you can view its logs directly through hako.

hako logs feature-auth

This will show the output from the dev script we defined in package.json.

Stop and clean up

When we are finished with a feature, we can stop the environment and remove the worktree.

First, stop the feature-auth environment:

hako stop feature-auth

Then, remove it entirely:

hako rm feature-auth

This command stops the processes and deletes the worktree directory, keeping your machine clean.

Conclusion

Congratulations. You have successfully managed two isolated development environments simultaneously. You can now switch between features without stopping your dev server or worrying about port collisions.

To learn more about advanced features, explore these guides:

• How to Set Up Docker Compose Mode for containerized projects.
• How to Set Up Shell Integration for automatic environment loading.
• How to Configure Lifecycle Hooks for custom setup scripts.
• CLI Reference for a full list of commands.