Skip to content

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:

    alis environment refresh acme.sh.<env-id> --output ~/alis.build/acme/build/sh/.alis/.env

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

Run

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; CtrlC 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

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):

  • 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:

    Makefile
    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 ShiftM 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

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.