---
title: "Run a service locally"
url: "https://docs.alisx.com/how-to/alis-build/run-a-service-locally/"
---
# Run a service locally

Start a service on your machine with the environment variables of one of its deployment environments loaded, on macOS, Linux and Windows alike.

## Prerequisites

- The service's packages installed: `alis packages install <pkg>`.
- The product's `.alis/.env` file, written for the deployment environment you want to mirror:

    ```bash title="Terminal"
    alis environment refresh acme.sh.<env-id> --output ~/alis.build/acme/build/sh/.alis/.env
    ```

    In the TUI, **Set active deployment environment** (++shift+e++ on a deployment environment cell) writes the same file. Without it, `alis run` fails with `ENV_NOT_FOUND`.

## Run

```bash title="Terminal"
alis run
```

From inside a service folder, the command loads `<product>/.alis/.env` into the process environment and starts the service using the first of these that applies:

1. the Makefile `run` target, when the folder has one and `make` is installed;
2. otherwise the Go main package in the folder (`go run .`);
3. otherwise the first component it detects: a Go server in a subfolder, else a frontend app (`npm run dev` or `pnpm dev`).

Pass a service folder path or a package id to run something other than the current directory. Arguments after `--` go to the program; with `make` they arrive as `ARGS="..."`. The service runs in the foreground; ++ctrl+c++ stops it and `alis` exits with the service's status (130 when interrupted). `--no-env` runs without loading the file.

`alis service run` is the same command.

## See what would run

```bash title="Terminal"
alis run --dry-run --json
```

Prints the plan: the directory, the env file, the variable names (never the values), the runner and the command.

## Give the service a Makefile

`alis run` and the TUI's ++m++ action both execute `make run`, so a Makefile is the way to run anything beyond `go run .`. The conventions every Alis Makefile follows (why each exists is in [How Makefiles work](https://docs.alisx.com/explanation/makefiles.md)):

- A `run` target starts the service locally, and `.DEFAULT_GOAL := run` sits above the targets so a bare `make` does the same.
- Recipes that need configuration start with `$(LOAD_ENV)`, which sources the repo's `.alis/.env`:

    ```make
    ENV_FILE := $(shell git rev-parse --show-toplevel)/.alis/.env
    LOAD_ENV := set -a; [ -f "$(ENV_FILE)" ] && . "$(ENV_FILE)"; set +a;

    run: ## Go backend (go run .)
    	$(LOAD_ENV) go run .
    ```

- A trailing `## comment` documents a target; the `help` target lists documented targets and the TUI's ++shift+m++ action shows them.
- A service that needs another one adds a `dep-<service>` target that starts it directly on its own port, never by recursing into the other service's `make run`.
- Recipes are indented with a tab.

On Windows, GNU make and bash are not installed by default: use `alis run`, which knows this contract, rather than calling `make` yourself.

## Let your agent see the frontend

```bash title="Terminal"
alis preview
```

Says where the service's web frontend answers: the port from `--url`, `--port`, `ALIS_APP_URL`, the service's `.claude/launch.json`, the Makefile's `APP_URL` or a Vite config, else `localhost:8080`. Nothing is launched: your agent opens that address with its own browser tools (Claude in Chrome, the Codex browser, a Playwright MCP) in your browser on the machine. See [Preview a service frontend](https://docs.alisx.com/how-to/alis-build/preview-a-service-frontend.md).

## Related

- [Manage environment variables](https://docs.alisx.com/how-to/alis-build/manage-environment-variables.md)
- [How Makefiles work](https://docs.alisx.com/explanation/makefiles.md)
- [Install and upgrade packages](https://docs.alisx.com/how-to/alis-build/install-and-upgrade-packages.md)