---
name: encore-run
description: Run an Encore.ts or Encore.go app locally. Covers `encore check` to start the app, call endpoints, and stop it in one command, running `encore run` in the background so it doesn't block the shell, the local development dashboard, and fixing startup errors.
when_to_use: >-
  User wants to run, start, or serve the app locally, try an endpoint, check that the app starts or that a change works, or open the local development dashboard. Also use when `encore run` blocks the shell, fails to start, says the port is already in use, says the Docker daemon isn't running, or warns that secrets aren't defined. SKIP for writing or running automated tests (`encore-testing`, `encore-go-testing`) and for deploying (`encore-deploy`). Trigger phrases: "run the app", "start the server", "encore run", "localhost:4000", "does it work", "call the endpoint", "local dashboard", "localhost:9400", "encore check", "port is already in use", "docker daemon is not running".
title: encore-run
canonical_url: https://skilld.dev/gh/encoredev/skills/run
last_updated: 2026-10-27T15:20:19.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install encoredev/skills/run`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/run`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/encoredev/skills/run) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/run`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/run --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/run --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Running an Encore App Locally

## Instructions

Run these commands from the app's root directory (the one with `encore.app`) or any directory below it. Pick one:

- **To check that the app starts, or that a change works:** use `encore check` (step 1). It always exits.
- **To keep the app running,** for the user to try or for many requests: use `encore run` in the background (step 2).

Never run `encore run` in the foreground. It doesn't exit, so the command blocks until it times out.

### 1. Check with `encore check`

```bash
encore check                       # start the app and stop it
encore check 'curl /hello/world'   # start it, call an endpoint, stop it
```

For several requests or JSON bodies, pass the requests on stdin, one per line:

```bash
encore check <<'EOF'
curl /hello/world
curl /url -X POST -H 'Content-Type: application/json' -d '{"url": "https://encore.dev"}'
curl /admin --no-fail -i
EOF
```

- **Exit code 0:** the app started, and every request returned a status below 400.
- **Exit code 1:** stdout has each request's result, between `=== [i/N] curl ... ===` and `--- exit: N ---`. stderr has build errors and app logs. Fix the problem and run it again.
- **Request arguments:** anything after the path goes to curl. Add `-i` to see the status and headers, and `--no-fail` to a request that should return an error status.

### 2. Run in the background

1. Start it, with its output in a log file. If your tool has its own way to run background commands, use that instead.

   ```bash
   encore run --browser=never > /tmp/encore-run.log 2>&1 &
   echo $! > /tmp/encore-run.pid
   ```

2. Wait until the log has `Encore development server running!`. If the process exits first, the log has the error (see [Errors](#errors)).
3. Call the API at `http://localhost:4000`. The local development dashboard is at `http://localhost:9400`, with an API explorer and a trace of every request.
4. After each code change, the app rebuilds and restarts. Check the log for build errors.
5. When you're done, stop it:

   ```bash
   kill "$(cat /tmp/encore-run.pid)"
   ```

Flags: `--port=<n>` changes the API port (default 4000). `--listen=0.0.0.0:4000` accepts connections from other machines. `--watch=false` turns off rebuilding on changes.

## Errors

- **`no encore.app found in directory (or any of the parent directories)`:** `cd` into the app. If there's no app yet, see `encore-create-app`.
- **`The docker daemon is not running. Start it first.`:** start Docker (macOS: `open -a Docker`), wait until `docker info` succeeds, and run again.
- **`docker not found: is it installed and in your PATH?`:** the app has a SQL database, which needs Docker. See `encore-install`.
- **`Failed to run on 127.0.0.1:4000 - port is already in use`:** an earlier `encore run` usually holds the port. Stop it, or use the free port from the next line of output: `Note: port <n> is available; specify --port=<n> to use it`.
- **`secrets not defined: <names>`:** a warning. The app runs with those secrets empty. Set local values with `encore secret set --type local <name>`, or in a gitignored `.secrets.local.cue` file for an app that isn't on Encore Cloud (see `encore-secret` or `encore-go-secret`).
- **Build errors:** fix the file and line shown, then run again. A background `encore run` rebuilds on save.

## Guidelines

- Prefer `encore check` to confirm a change works. It can't leave a process running.
- Stop background runs you started.
- Agents can list services and endpoints, call endpoints, read traces, and query databases through the local Encore MCP server. To set it up, see `encore-mcp`.
- For automated tests, use `encore-testing` or `encore-go-testing`.
- Docs: https://encore.dev/docs/cli/cli-reference and https://encore.dev/docs/dev-dash
