Encore Run

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

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:

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.

   bashCopy

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

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:

   bashCopy

   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 (opens in a new tab) and https://encore.dev/docs/dev-dash (opens in a new tab)