# AI agents (/docs/ai-agents)

`aka mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. A coding agent can use it to look up the URL of the app it is working on instead of guessing a port.

## Set it up [#set-it-up]

For Claude Code:

```bash
claude mcp add aka -- aka mcp
```

For other MCP clients, add it to the client's configuration:

```json
{ "mcpServers": { "aka": { "command": "aka", "args": ["mcp"] } } }
```

## Tools [#tools]

| Tool | What it does |
|---|---|
| `list_apps` | the running apps and aliases, with their URLs |
| `get_url` | the URL of one app |
| `add_alias` | route a name to a port |
| `remove_alias` | remove an alias |
| `doctor` | run the setup checks |

The server does not start dev servers. Agents run `aka <name> <command>` in a shell.

## Docs for agents [#docs-for-agents]

These docs are also served as plain text: [`/llms.txt`](/llms.txt) lists every page, [`/llms-full.txt`](/llms-full.txt) has all of them in one file, and each page has a Markdown version (the copy button at the top of the page).


# Aliases and list (/docs/aliases)

An alias routes a name to a port aka did not start, such as a database UI or a server started by another tool:

```bash
aka alias db 5432             # https://db.localhost -> 127.0.0.1:5432
aka alias api 127.0.0.1:8080  # or a loopback address
aka alias                     # list aliases
aka alias rm db
```

Aliases are saved in `~/.aka/aliases.json` and come back when the proxy restarts. A running app cannot take an alias's name, even with `--force`.

## List [#list]

```bash
aka list          # running apps and aliases
aka list --json   # for scripts
```

`aka list --json` prints an array with each route's `url`, `hostname`, `port`, `pid`, `command`, whether it is an `alias`, and when it started (`since`).


# Changelog (/docs/changelog)

{/* Generated from CHANGELOG.md by scripts/sync.mjs. Edit that file instead. */}

Releases, with downloads, are on [GitHub](https://github.com/visveshkhanna/aka/releases).

## [v0.1.2](https://github.com/visveshkhanna/aka/releases/tag/v0.1.2) · 2026-11-11 [#v012--2026-11-11]

### Added [#added]

- Documentation at [aka.visvesh.dev](https://aka.visvesh.dev), with search, and plain-text versions for coding agents at `/llms.txt`.
- A shorter install command: `curl -fsSL https://aka.visvesh.dev/install.sh | sh`.

### Changed [#changed]

- aka is licensed under the Apache License 2.0. Release archives include the licence.

## [v0.1.1](https://github.com/visveshkhanna/aka/releases/tag/v0.1.1) · 2026-11-11 [#v011--2026-11-11]

### Fixed [#fixed]

- `aka --version`, `aka doctor` and the MCP server report the release version for binaries built with `go install`, instead of `dev`.

## [v0.1.0](https://github.com/visveshkhanna/aka/releases/tag/v0.1.0) · 2026-11-11 [#v010--2026-11-11]

The first release.

### Run apps [#run-apps]

- `aka <name> <command>` gives any dev server a stable `https://<name>.localhost` URL, with a free port passed through `PORT`.
- Port detection follows apps that ignore `PORT`, through their listening sockets and printed URLs, for as long as they run.
- Presets set the port for about 30 dev servers that ignore `PORT`, including Angular, Vite, Django, uvicorn, FastAPI, gunicorn, Flask, Rails, Laravel, Spring Boot and ASP.NET, looking through wrappers such as `npx`, `uv run` and `npm run`. Your own presets go in `~/.aka/presets.json`.
- A bare `aka` finds and runs the project's dev command across about 15 ecosystems, and infers the app name from the project.
- In a git worktree, the branch becomes a prefix: `login.shop.localhost`.

### Several apps [#several-apps]

- `aka.toml` and `aka up` run several apps together, each with its own URL.
- `aka compose` runs Docker Compose and gives each published service a URL.
- `aka alias` routes a name to a port aka did not start.

### HTTPS [#https]

- HTTPS with HTTP/2 from a local, name-constrained certificate authority that can only sign `*.localhost` and loopback names.
- `aka trust` and `aka untrust` for the macOS keychain, Linux distribution trust stores, the Windows user Root store and NSS databases.
- `sudo aka proxy start` serves port 443 and then drops root.

### Tools [#tools]

- `aka doctor` checks the setup and explains each problem.
- Apps print the setting to change when Django, Vite, Rails, webpack-dev-server or ASP.NET reject the `.localhost` host.
- `aka mcp`, a Model Context Protocol server for coding agents.
- `aka service install` starts the proxy at login with launchd, systemd or the Windows Run key.
- `aka list --json` for scripts.

### Platforms [#platforms]

- macOS, Linux and Windows on x64 and arm64, and 32-bit ARM Linux, as single static binaries.


# Commands (/docs/commands)

```text
aka                            run this project's dev command (or aka.toml's apps)
aka <name> <command...>        run command, route <name>.localhost to it
aka <command...>               same, name inferred from the project
aka <name> -- <command...>     explicit name ({port} in the command is replaced)
aka up [app...]                run the apps listed in aka.toml together
aka compose [args...]          docker compose up, with <service>.<project>.localhost URLs
aka list [--json]              show running apps and aliases
aka alias <name> <port>        route <name>.localhost to a port aka did not start
aka alias [rm <name>]          list or remove aliases
aka proxy start|stop|status    manage the proxy
sudo aka proxy start           also serve port 443 (root is dropped after binding)
aka service install|uninstall|status   start the proxy at login
aka trust | untrust            add or remove the local CA in the system trust store
aka doctor                     check the setup and explain what is wrong
aka mcp                        MCP server on stdio, for AI coding agents
aka --version
aka --help
```

| Command | Guide |
|---|---|
| `aka`, `aka <name> <command>` | [Running apps](/docs/running-apps) |
| `aka up` | [Several apps](/docs/multiple-apps) |
| `aka compose` | [Docker Compose](/docs/docker-compose) |
| `aka list`, `aka alias` | [Aliases and list](/docs/aliases) |
| `aka proxy`, `aka service` | [The proxy](/docs/proxy) |
| `aka trust`, `aka untrust` | [HTTPS](/docs/https) |
| `aka doctor` | [Troubleshooting](/docs/troubleshooting) |
| `aka mcp` | [AI agents](/docs/ai-agents) |

## Run flags [#run-flags]

Flags go before the name:

| Flag | Meaning |
|---|---|
| `--name`, `-n <name>` | the app name |
| `--force`, `-f` | take over a name another aka is using, and stop that app |
| `--port-hint <port>` | route to this port instead of detecting one |
| `--no-preset` | do not add port flags or variables for known frameworks |
| `--choose` | pick again which dev command a bare `aka` runs |


# Configuration (/docs/configuration)

## aka.toml [#akatoml]

An optional `aka.toml` lists the apps of a project for [`aka up`](/docs/multiple-apps). aka looks for it from the current directory up to the repository root.

```toml title="aka.toml"
[apps]
web = "npm run dev"            # a name and a command

[apps.api]                     # or a table, for more settings
cmd = "uvicorn main:app --reload"
dir = "services/api"
port_hint = 8000
no_preset = false
```

| Setting | Type | Meaning |
|---|---|---|
| `cmd` (or `command`) | string | the command; required |
| `dir` | string | where to run it, relative to `aka.toml`; default the file's directory |
| `port_hint` | integer | route to this port, like `--port-hint` |
| `no_preset` | boolean | do not apply presets, like `--no-preset` |

The file accepts strings (double or single quoted), integers, booleans, tables and comments. Anything else, an unknown setting, or a key set twice is an error with its line number, so a typo never silently drops an app.

## Environment variables [#environment-variables]

| Variable | Default | Meaning |
|---|---|---|
| `AKA_PROXY_PORT` | `1355` | the proxy's port, for HTTP and HTTPS |
| `AKA_HTTPS_PORT` | `443` | the dedicated HTTPS port to try; `0` for none |
| `AKA_HTTPS` | on | `0` serves plain HTTP only |
| `AKA_PREFIX` | from the branch | the [worktree](/docs/running-apps#worktrees) prefix; empty turns it off |
| `AKA_STATE_DIR` | `~/.aka` | where aka keeps its files |
| `AKA_NO_PTY` | off | `1` captures app output through pipes instead of a pseudo-terminal |

aka sets `PORT`, `HOST`, `AKA_URL` and `AKA_PORT` for the app, `NODE_EXTRA_CA_CERTS` when HTTPS is on, and `PYTHONUNBUFFERED` when output goes through pipes.

## Files [#files]

Everything aka keeps is in `~/.aka`, or `AKA_STATE_DIR`:

| File | Contents |
|---|---|
| `ca.pem`, `ca-key.pem` | the local certificate authority |
| `aliases.json` | [aliases](/docs/aliases) |
| `projects.json` | which dev command a bare `aka` runs, per project |
| `presets.json` | your own [presets](/docs/presets#your-own-presets) (optional) |
| `daemon.log` | the proxy's log |

Nothing is written into your projects.


# Docker Compose (/docs/docker-compose)

```bash
aka compose                         # docker compose up, plus a URL per published service
aka compose -f dev.yml up --build   # arguments go to docker compose
aka compose up -d                   # containers in the background; aka routes until Ctrl+C
```

Every running service with a published TCP port gets `<service>.<project>.localhost`, for example `web.shop.localhost` for the published port of `web` in the `shop` project. With several published ports, the first that answers HTTP is used.

Routes follow services as they start and stop. With `-d`, the containers keep running after aka exits, and only the routes go away.


# How it works (/docs/how-it-works)

## The proxy [#the-proxy]

A background proxy starts on first use. It listens on `127.0.0.1:1355` and `[::1]:1355`, routes each request by its `Host` header, and speaks both HTTP and HTTPS on that port. If it may bind port 443, it serves HTTPS there too. `*.localhost` names resolve to loopback without any DNS setup ([RFC 6761](https://www.rfc-editor.org/rfc/rfc6761)), in browsers, curl and most resolvers.

The proxy never listens on other network interfaces, so apps are not exposed to the local network. A request for an unknown name gets a page listing the running apps, and a request for an app that is still starting gets a page that reloads once it is up.

Each `aka` talks to the proxy over a local socket in `~/.aka`, and every route belongs to the connection that registered it. When that connection drops, because the app exited or aka was killed, the route goes away.

## Running an app [#running-an-app]

For `aka <name> <command>`, aka:

1. registers `<name>.localhost` with the proxy, and picks a free port P from 4000 to 4999;
2. applies a [preset](/docs/presets) if the command is a known dev server that ignores `PORT`;
3. runs the command with `PORT=P`, `HOST=127.0.0.1` and `AKA_URL=https://<name>.localhost[:1355]`, replacing any `{port}` in its arguments with P.

## Finding the port [#finding-the-port]

While the command runs, aka watches its whole process tree for TCP sockets in the LISTEN state (`lsof` on macOS, `/proc` on Linux, `GetExtendedTcpTable` on Windows), and scans its output for URLs such as `http://localhost:8000`. The route points at:

1. P, if the app listens on it;
2. otherwise the port of a printed URL, if the app listens on it;
3. otherwise the first listening port that answers HTTP.

This runs for the life of the app, so when it restarts or moves to another port, the route follows. `--port-hint` skips detection.

## Stopping [#stopping]

When the command exits, aka removes the route and exits with the command's status. Ctrl+C reaches the app as it would without aka. The app runs in its own process group (a job object on Windows), so aka can stop the whole tree, including anything the app started, and only processes it started: each is tracked by its process ID and start time, so a reused ID is never signalled.

If aka itself is killed, the proxy notices the dropped connection, removes the route, and stops the app that was left behind.

## State [#state]

Everything aka keeps is in `~/.aka` (or `AKA_STATE_DIR`):

| File | Contents |
|---|---|
| `ca.pem`, `ca-key.pem` | the local certificate authority |
| `aliases.json` | aliases |
| `projects.json` | which dev command a bare `aka` runs, per project |
| `presets.json` | your own presets (optional) |
| `daemon.log` | the proxy's log |

Nothing is written into your projects.


# HTTPS (/docs/https)

aka serves every app over HTTPS, with HTTP/2, on the same port as plain HTTP (1355 by default). It tells the two apart by the first byte of each connection.

## The local certificate authority [#the-local-certificate-authority]

On first use, aka creates a certificate authority in `~/.aka` (`ca.pem` and `ca-key.pem`, readable only by you). During each TLS handshake it issues a 30-day certificate for the requested hostname, and renews it before it expires.

The CA is **name-constrained**: it can only sign `localhost`, `*.localhost` and loopback addresses (`127.0.0.0/8` and `::1`). Even if its key leaked, it could not be used to impersonate any other site.

## Trusting it [#trusting-it]

The first HTTPS run in a terminal offers to add the CA to the system trust store. You can also do it yourself, and undo it:

```bash
aka trust
aka untrust
```

| Where | How the CA is trusted |
|---|---|
| macOS | the login keychain, after you confirm (Safari, Chrome, curl, Go) |
| Linux | the distribution's anchor directory and `update-ca-certificates` or `update-ca-trust`, with `sudo` (Debian, Ubuntu, Alpine, Fedora, RHEL, Rocky, Arch, openSUSE) |
| Windows | the current user's Root store, after you confirm; no administrator rights |
| Firefox, and Chrome on Linux | their NSS databases, if `certutil` is installed |
| Node | `NODE_EXTRA_CA_CERTS` is set for each app, so server-side `fetch` to another `*.localhost` app works |

`aka doctor` reports whether the system and each NSS database trust the CA.

Some clients use their own CA bundle and do not read the system store: Python's `requests` (through `certifi`) and Java, for example. Point them at `~/.aka/ca.pem` (`REQUESTS_CA_BUNDLE`, or a Java trust store) when one app calls another over HTTPS.

## Port 443 [#port-443]

To serve `https://myapp.localhost` without a port, aka also tries to listen on port 443. That needs privileges on macOS (for loopback addresses) and on Linux. Without them, HTTPS is served on port 1355 and the URL carries the port. To bind 443:

```bash
sudo aka proxy start     # binds 443, then drops root and runs as you
```

aka binds the port as root, drops to the user who ran `sudo`, and starts the proxy as that user with the bound socket. Nothing else runs as root, and its files stay yours.

On Linux, you can instead allow the binary to bind low ports: `sudo setcap cap_net_bind_service=+ep "$(command -v aka)"`. On Windows, port 443 needs no privileges, so URLs have no port unless something else holds 443.

`AKA_HTTPS_PORT` chooses another dedicated port (`0` for none), and `AKA_HTTPS=0` turns HTTPS off for plain `http://<name>.localhost:1355`.

## Framework settings [#framework-settings]

Behind the proxy, the app itself speaks plain HTTP. aka sets `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Port` and `X-Forwarded-For` on every request so it can tell.

- **Django** builds CSRF origins from the scheme it sees, so POSTs (the admin login, for one) fail with "Origin checking failed". Add this to the development settings:

  ```python
  SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
  ```

- **uvicorn, Starlette, FastAPI, Rails**, and **Express** with `trust proxy`, read `X-Forwarded-Proto` themselves, so redirects use `https`.
- **WebSockets**, such as hot reload in Vite or Angular, are proxied too, over `wss://` when the page is HTTPS.
- A dev server that serves HTTPS itself (`ng serve --ssl`, `vite --https`) cannot be proxied; let aka handle TLS instead.


# Introduction (/docs)

aka runs a small reverse proxy on your machine and gives each dev server a name. Your app gets a free port, and you open `https://<name>.localhost` instead of remembering which port it took.

```diff
- python manage.py runserver          # http://127.0.0.1:8000
+ aka python manage.py runserver      # https://myapp.localhost:1355
```

The URL stays the same across restarts, so bookmarks, cookies, OAuth redirects and test scripts keep pointing at the right app. Two Django or two Angular projects run side by side instead of fighting over 8000 or 4200.

aka is a single static binary with no runtime dependencies. It works with any stack: Node, Python, Ruby, PHP, Go, Rust, Java, .NET, Elixir and more.

## Quick start [#quick-start]

[Install aka](/docs/installation), then trust its local certificate authority once, so browsers accept the HTTPS URLs:

```bash
aka trust
```

From a project directory, run aka with no arguments. It finds the dev command (`package.json` scripts, `manage.py`, a `Procfile`, `bin/dev` and [more](/docs/running-apps#bare-aka)) and runs it:

```bash
aka
# -> https://<project>.localhost:1355
```

Or give a name and any command:

```bash
aka myapp npm run dev                 # https://myapp.localhost:1355
aka api uvicorn main:app --reload     # https://api.localhost:1355
aka ng serve                          # name inferred from the project
```

URLs carry `:1355` until the proxy can bind port 443. Start it once with `sudo` to drop the port; aka binds 443, then gives up root:

```bash
sudo aka proxy start                  # https://myapp.localhost
```

## How it works [#how-it-works]

Each app gets a free port from 4000 to 4999 through the `PORT` environment variable. Most frameworks read it. For those that don't, such as Vite, Angular, Django, uvicorn and Rails, aka adds the matching flag or variable. Apps that ignore both are still found: aka watches the process tree for listening sockets and the output for printed URLs, and routes to the port the app actually uses.

<Cards>
  <Card title="Running apps" href="/docs/running-apps" description="Names, flags, bare aka and worktrees." />
  <Card title="Several apps" href="/docs/multiple-apps" description="Run a whole project with aka.toml and aka up." />
  <Card title="HTTPS" href="/docs/https" description="The local certificate authority and port 443." />
  <Card title="How it works" href="/docs/how-it-works" description="The proxy, port detection and process handling." />
</Cards>


# Installation (/docs/installation)

<Tabs items={['macOS and Linux', 'Windows', 'Go', 'From source']}>
  <Tab value="macOS and Linux">

```bash
curl -fsSL https://aka.visvesh.dev/install.sh | sh
```

The script downloads the latest [release](https://github.com/visveshkhanna/aka/releases) for your machine, checks its SHA-256 checksum, and installs `aka` into `~/.local/bin`. Set `AKA_INSTALL_DIR` to choose another directory, or `AKA_VERSION` to pin a version:

```bash
curl -fsSL https://aka.visvesh.dev/install.sh | AKA_VERSION=v0.1.1 sh
```

The same script is in the repository, at `https://raw.githubusercontent.com/visveshkhanna/aka/main/install.sh`.

  </Tab>
  <Tab value="Windows">

Download `aka_<version>_windows_amd64.zip`, or `arm64`, from the [latest release](https://github.com/visveshkhanna/aka/releases/latest), extract it, and put `aka.exe` in a directory on your `PATH`. aka needs Windows 10 1803 or later.

  </Tab>
  <Tab value="Go">

With Go 1.26 or later, on any platform:

```bash
go install github.com/visveshkhanna/aka/cmd/aka@latest
```

  </Tab>
  <Tab value="From source">

```bash
git clone https://github.com/visveshkhanna/aka
cd aka
go build -o bin/aka ./cmd/aka
```

  </Tab>
</Tabs>

## Set up HTTPS [#set-up-https]

aka serves every app over HTTPS from a local certificate authority. Trust it once, so browsers accept the certificates:

```bash
aka trust
```

macOS and Windows ask you to confirm; Linux runs `sudo`. The CA can only sign `.localhost` and loopback names, so it cannot be used to impersonate other sites. See [HTTPS](/docs/https).

## Check the setup [#check-the-setup]

```bash
aka doctor
```

`doctor` checks the proxy, the certificate authority, name resolution and every route, and says how to fix anything that is wrong.

## Verify a download [#verify-a-download]

Every release lists its archives in `checksums.txt`, and each archive has a build provenance attestation from the release workflow:

```bash
gh attestation verify aka_0.1.1_linux_amd64.tar.gz --repo visveshkhanna/aka
```

## Uninstall [#uninstall]

```bash
aka service uninstall   # if you installed the login service
aka proxy stop
aka untrust             # remove the CA from the trust store
rm -rf ~/.aka           # the CA, aliases and logs
rm "$(command -v aka)"
```


# Several apps (/docs/multiple-apps)

List the apps in an `aka.toml` at the project root:

```toml title="aka.toml"
[apps]
web = "npm run dev"
api = "uvicorn main:app --reload"

[apps.worker]            # a table for more settings
cmd = "python -m worker"
dir = "services/worker"  # relative to aka.toml
port_hint = 9000         # optional, like --port-hint
no_preset = false        # optional, like --no-preset
```

Then run them:

```bash
aka up            # every app
aka up web api    # some of them
aka               # a bare aka in the project runs aka up
```

Each app gets its own URL (`web.localhost`, `api.localhost`), preset and port detection, and its output is prefixed with its name. Ctrl+C stops them all. `aka up` keeps running until every app has stopped, and then exits with the status of the first app, by name, that failed, or 0.

A command that uses shell syntax (`a && b`, `$VAR`, `>`) runs through `sh -c`, or `cmd /c` on Windows. Other commands are split into words, with quotes honoured, so presets can see them.

See [Configuration](/docs/configuration#akatoml) for every setting.


# Platforms (/docs/platforms)

aka runs on macOS, Linux and Windows 10 1803 or later, on x64 and arm64 (and 32-bit ARM Linux). CI runs the unit tests and an end-to-end test with real Node and Python servers on all six x64 and arm64 combinations, and checks the login service on each system.

## macOS [#macos]

- **Port detection** reads listening sockets with `lsof`, which every macOS install has.
- **Trust** goes into the login keychain. macOS asks you to confirm.
- **Port 443** needs `sudo aka proxy start` (binding loopback addresses below 1024 is privileged), otherwise URLs carry `:1355`.
- **Login service**: a launchd agent in `~/Library/LaunchAgents`.

## Linux [#linux]

- **Port detection** reads `/proc`.
- **Trust** copies the CA into the distribution's anchor directory and rebuilds the system bundle with `sudo`. This is tested on Ubuntu 24.04 and 22.04, Debian, Fedora, Rocky Linux, Alpine, Arch and openSUSE. Firefox and Chrome keep their own NSS databases, which aka updates when `certutil` is installed (`libnss3-tools` or `nss-tools`).
- **Port 443** needs `sudo aka proxy start`, or `setcap cap_net_bind_service=+ep` on the binary.
- **Login service**: a systemd user unit in `~/.config/systemd/user`.

## Windows [#windows]

- **Port detection** reads the process table from a Toolhelp32 snapshot and listening sockets from `GetExtendedTcpTable`.
- **Stopping apps**: the app shares aka's console, so Ctrl+C reaches it directly, as without aka. aka also keeps each app in a job object, so a takeover, a third Ctrl+C, or aka itself exiting stops the whole process tree. `aka up` does the same for all of its apps.
- **Trust** goes into the current user's Root store. Windows asks you to confirm; no administrator rights are needed.
- **Port 443** needs no privileges, so URLs have no port unless something else holds 443.
- **Shell syntax** in `aka.toml` commands runs through `cmd /c`, which understands `&&`, `|` and `>`, but uses `%VAR%` rather than `$VAR`.
- **Login service**: a value under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`. Unlike launchd and systemd, it does not restart a crashed proxy; the next app does.
- **Name resolution**: browsers and curl resolve `*.localhost` by themselves, but the Windows resolver does not. Code that calls another app (Node, Python and similar) needs a hosts-file entry such as `127.0.0.1 api.localhost`.
- **Output** goes through pipes, not a pseudo-console, so some tools turn off colours.

## Known limits [#known-limits]

- `kill -9` on `aka up` itself, on macOS or Linux, leaves its apps running. Ctrl+C, closing the terminal and a plain `kill` stop them.
- Ctrl+Z suspends aka but not the app.
- A dev server that serves HTTPS itself cannot be proxied; see [HTTPS](/docs/https#framework-settings).
- Python `requests` and Java use their own CA bundles; see [HTTPS](/docs/https#trusting-it).


# Presets (/docs/presets)

Most dev servers read the `PORT` environment variable. Many popular ones do not, and listen on a fixed port such as 8000 or 4200. Before starting the command, aka adds the flag or variable that makes them listen on the assigned port instead, so several of them run at once.

The built-in presets live in [`internal/presets/presets.json`](https://github.com/visveshkhanna/aka/blob/main/internal/presets/presets.json). `P` is the assigned port:

| Ecosystem | Commands | Added |
|---|---|---|
| Angular | `ng serve` | `--port P --host 127.0.0.1` |
| Vite family | `vite`, `vitepress`, `astro dev`, `react-router dev`, `rsbuild dev` | `--port P [--strictPort] --host 127.0.0.1` |
| Other JavaScript | `wrangler dev`, `expo start`, `react-native start` | `--port P` and a host flag |
| Django | `manage.py runserver`, `django-admin runserver` | `127.0.0.1:P` |
| uvicorn, FastAPI | `uvicorn app:app`, `fastapi dev` | `--port P --host 127.0.0.1` |
| gunicorn | `gunicorn app:app` | `-b 127.0.0.1:P` |
| Flask, Streamlit, Gradio | `flask run`, `streamlit run`, any Python script | `FLASK_RUN_PORT`, `STREAMLIT_SERVER_PORT`, `GRADIO_SERVER_PORT` |
| Jupyter, MkDocs, Python | `jupyter lab`, `mkdocs serve`, `python -m http.server` | `--port=P`, `-a 127.0.0.1:P`, `P --bind 127.0.0.1` |
| Rails, Jekyll | `rails s`, `jekyll serve` | `-p P -b 127.0.0.1`, `--port P --host 127.0.0.1` |
| PHP, Laravel | `php -S`, `php artisan serve` | `127.0.0.1:P`, `--port=P --host=127.0.0.1` |
| Spring Boot, Quarkus, ASP.NET | `mvn`, `gradle`, `gradlew`, `java -jar`, `quarkus dev`, `dotnet run`, `dotnet watch` | `SERVER_PORT`, `QUARKUS_HTTP_PORT`, `ASPNETCORE_URLS` |
| Hugo | `hugo server` | `--port P --bind 127.0.0.1` |

Next.js, Nuxt, Express, Phoenix, Go, Rust, Deno and Bun apps read `PORT` and need nothing.

## Rules [#rules]

- **Wrappers are looked through.** `npx`, `bunx`, `pnpm exec` and `dlx`, `yarn exec` and `dlx`, `npm exec`, `poetry`, `uv`, `pipenv`, `pdm`, `hatch` and `rye run`, `uvx`, `pipx run`, `bundle exec`, `cross-env`, `python -m <module>`, `python <script>` and `php artisan` are skipped to find the real command.
- **Package scripts are followed.** `npm`, `pnpm`, `yarn` or `bun run <script>` looks the script up in `package.json` and forwards the flags (`npm run dev -- --port P`). Compound scripts (`a && b`, `a & b`, `a | b`, a trailing comment) are left alone.
- **Only server commands get flags**: never `vite build`, `ng test` or `manage.py migrate`.
- **Your settings win.** A flag you already passed (`--port 5000`) is not added again, and an environment variable you have set is not replaced.
- **You can turn them off.** A `{port}` placeholder in the command, or `--no-preset`, disables presets for that run.

Apps with no preset that ignore `PORT` still work: aka finds the port they listen on (see [How it works](/docs/how-it-works)).

## Your own presets [#your-own-presets]

Add or override presets in `~/.aka/presets.json`, in the same format as the built-in file. A preset with the same `name` as a built-in one replaces it.

```json
{
  "presets": [
    {
      "name": "mytool",
      "commands": ["mytool"],
      "server": { "subcommands": ["serve"] },
      "inject": [{ "flags": ["--listen", "127.0.0.1:{port}"], "unless": ["--listen"] }],
      "env": { "MYTOOL_ENV": "development" }
    }
  ],
  "wrappers": [{ "commands": ["mise"], "subcommands": ["exec"] }]
}
```

- `commands` are matched by name, ignoring the directory and a Windows extension, so `ng`, `./node_modules/.bin/ng` and `ng.cmd` are the same command.
- `server.subcommands` adds the flags only for those subcommands (`mytool serve`, not `mytool build`).
- `inject` adds `flags`, unless one of the `unless` flags is already there. `{port}` is replaced with the assigned port.
- `env` sets variables for every run of the command, with the same `{port}` substitution.
- `wrappers` adds commands to look through, such as a version manager.

If you write a preset for a common tool, consider contributing it to the built-in file.


# The proxy (/docs/proxy)

The proxy starts by itself the first time an app runs. To manage it directly:

```bash
aka proxy start     # start it (with sudo: also bind port 443, then drop root)
aka proxy status
aka proxy stop
```

`aka proxy stop` stops routing, but running apps keep running. Each one says so, and registers again when a proxy starts, with `aka proxy start` or the next app. If the proxy crashes instead, apps restart it right away. A proxy left over from an older aka is replaced automatically when it has no routes.

The proxy listens only on loopback (`127.0.0.1` and `::1`), so apps are not exposed to your network.

## Start at login [#start-at-login]

```bash
aka service install    # a launchd agent (macOS), systemd user unit (Linux), or Run key (Windows)
aka service status
aka service uninstall
```

No administrator rights are needed. launchd and systemd restart the proxy if it crashes, but `aka proxy stop` holds until the next login. The service runs as you, so it cannot bind port 443 on macOS or Linux; use `sudo aka proxy start` for URLs without a port.


# Running apps (/docs/running-apps)

```bash
aka myapp python manage.py runserver   # a name, then the command
aka uvicorn main:app --reload          # the command only: the name is inferred
aka api -- php -S 127.0.0.1:{port}     # an explicit name; {port} is replaced
```

The command runs with these variables:

| Variable | Value |
|---|---|
| `PORT` | a free port from 4000 to 4999 |
| `HOST` | `127.0.0.1` |
| `AKA_URL` | the app's public URL, such as `https://myapp.localhost:1355` |

When the command exits, the route goes away and aka exits with the command's status. Ctrl+C reaches the app as it would without aka.

## Names and commands [#names-and-commands]

The first word is taken as the app name if it is not a command on your `PATH`. When an app is named like a command, use `--name` or `--`:

```bash
aka --name test npm run test:server
aka test -- npm run test:server
```

Flags go before the name:

| Flag | Meaning |
|---|---|
| `--name`, `-n <name>` | the app name |
| `--force`, `-f` | take over a name another aka is using, and stop that app |
| `--port-hint <port>` | route to this port instead of detecting one |
| `--no-preset` | do not add port flags or variables for known frameworks |
| `--choose` | pick again which dev command a bare `aka` runs |

A name with dots is a subdomain: `aka api.shop npm start` serves `https://api.shop.localhost`. A name you give must be letters, digits and dashes.

## Bare aka [#bare-aka]

With no command, aka looks for the project's dev command from the current directory up to the repository root (outside a repository, up to just below your home directory), and runs it in the directory where it found it:

| Found | Runs |
|---|---|
| `package.json` script `dev`, else `serve`, else `start` | `<pm> run <script>`, with the package manager from `packageManager` or the lock file |
| `angular.json` without scripts | `npx ng serve` |
| `manage.py` | `manage.py runserver` through `uv run`, `poetry run`, the project's `.venv` or `python3` |
| `Procfile.dev` or `Procfile` with a `web:` line | that line, through the shell |
| `Gemfile` with `bin/dev` or `bin/rails` | `bin/dev` or `bin/rails server` |
| `artisan` with `composer.json` | `php artisan serve` |
| `mix.exs` using Phoenix | `mix phx.server` |
| `pom.xml` or `build.gradle` using Spring Boot | `./mvnw spring-boot:run` or `./gradlew bootRun` |
| `*.csproj` | `dotnet watch run` |
| `hugo.toml`, `mkdocs.yml` | `hugo server`, `mkdocs serve` |
| `Cargo.toml`, `go.mod` with `package main` | `cargo run`, `go run .` |
| `Makefile` with a `dev`, `run` or `serve` target | `make <target>` |

If several match, such as a Django backend with a `package.json` for its assets, aka asks once in a terminal and remembers the answer in `~/.aka/projects.json`. Nothing is written into your repository. `aka --choose` asks again. A run without a terminal takes the first match and lists the others.

If the project has an [`aka.toml`](/docs/multiple-apps), a bare `aka` runs its apps instead.

## Inferred names [#inferred-names]

An inferred name comes from the same walk up the directory tree: the nearest of `package.json` (without its `@scope/`), `pyproject.toml`, `Cargo.toml`, `go.mod` (the last path segment, without `/v2`), `composer.json`, `pom.xml`, `settings.gradle`, `mix.exs`, `*.csproj` and `angular.json`. Failing those, it is the repository's name, then the directory's. It is lowercased, and anything other than letters and digits becomes a dash.

## Worktrees [#worktrees]

In a checkout made with `git worktree add`, on a branch other than `main` or `master`, the inferred name gets the branch's last segment as a prefix. `feature/login` in a worktree of `shop` becomes `login.shop.localhost`, so two checkouts of the same project run at once. The main checkout never gets a prefix, and names you give are used as given.

`AKA_PREFIX=staging` sets the prefix yourself. `AKA_PREFIX=` (empty) turns it off.


# Troubleshooting (/docs/troubleshooting)

## aka doctor [#aka-doctor]

Run `aka doctor` first when a URL does not load. It checks:

- the state directory;
- the proxy: running, current build, HTTPS mode, port 443, and reachability on both loopback addresses;
- the certificate authority: constraints, expiry, system trust, and Firefox and other NSS databases;
- `*.localhost` name resolution;
- every route, through the proxy;
- the current project: its name, its dev command and the preset aka would use.

It says how to fix each problem, and exits with status 1 if a check fails.

## The app rejects the host [#the-app-rejects-the-host]

Some frameworks reject requests for hosts they do not know. When an app answers 400 or 403 for that reason, the aka running it prints the setting to change in the app's terminal. This covers:

| Framework | Setting |
|---|---|
| Django | `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS` |
| Vite | `server.allowedHosts` |
| webpack-dev-server | `allowedHosts` |
| Rails | `config.hosts` |
| ASP.NET | `AllowedHosts` |

`aka doctor` reports the same.

## Django POSTs fail with "Origin checking failed" [#django-posts-fail-with-origin-checking-failed]

Django builds CSRF origins from the scheme it sees, which is plain HTTP behind the proxy. Add this to the development settings:

```python title="settings.py"
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
```

## The browser warns about the certificate [#the-browser-warns-about-the-certificate]

Run `aka trust`, then restart a browser that was already open. On Linux, Firefox and Chrome use their own NSS databases, which aka updates only when `certutil` is installed (`libnss3-tools` or `nss-tools`). See [HTTPS](/docs/https#trusting-it).

## The app is not found [#the-app-is-not-found]

If the app listens on a port aka cannot detect, pass it: `aka --port-hint 8080 web ./server`. A server that serves HTTPS itself cannot be proxied; let aka handle TLS instead.

## Known limits [#known-limits]

- `kill -9` on `aka up` itself, on macOS or Linux, leaves its apps running. Ctrl+C, closing the terminal and a plain `kill` stop them.
- Ctrl+Z suspends aka but not the app.
- Python `requests` and Java use their own CA bundles; point them at `~/.aka/ca.pem`.
- On Windows, code that calls another app needs a hosts-file entry; see [Platforms](/docs/platforms#windows).

Still stuck? [Open an issue](https://github.com/visveshkhanna/aka/issues/new/choose) with the output of `aka doctor`.