---
title: Service Runtime
description: Foreground runs, background service polling, worker slots, limits, cooldowns, logs, and restart behavior.
relatedCommands:
  - alpaca run --help
  - alpaca service --help
  - alpaca service status --help
  - alpaca service log show --help
  - alpaca issue log show --help
  - alpaca issue log search --help
relatedDocs:
  - quick-start
  - workflow-state
  - scheduling
  - config
  - command-flows
  - issues
  - hierarchical-workflows
  - maintenance
---

# Service Runtime

Use this guide when deciding whether to run AlpacaLoop once in the foreground, operate the background service, inspect service logs, or explain why an issue is waiting.

## When to Use

- Use `alpaca run` for one foreground processing cycle in a configured repository.
- Use `alpaca service enable`, `disable`, `restart`, `status`, and `log show` for the background polling service.
- Use this doc with `alpaca docs show config` when explaining polling, worker timeout, parallelism, run limits, cooldowns, or approval settings that change setup blocker handling.
- Use `alpaca docs show scheduling` for user-facing schedule options and recurring parent behavior.

## Key Commands

```bash
alpaca run -h
alpaca service -h
alpaca service status -h
alpaca service log show -h
alpaca issue log show -h
alpaca issue log search -h
```

## Core Behavior

`alpaca run` processes runnable workflow issues once with the configured worker. Do not use it while the background service is running. Use `--issue <id[,id...]>` to restrict the cycle to specific tracker issues, including accepted `AI: Running` continuations without active ownership.

When an issue body or fresh comment first needs workflow setup, a run cycle publishes that setup before normal execution. If the resulting workflow state is immediately plannable, AlpacaLoop claims the issue in the same cycle, writes `AI: Running` with execution ownership, and starts the first `workflow_plan` pass. Scheduled runs, recurring parents, controller-child control-plane work, human handoffs, setup failures, and setup deferrals wait for their normal later path instead.

The background service polls registered repositories and processes runnable issues. It uses repo-local `alpaca.config.json` from each registered repository, machine-local auth profiles, and service-local logs. Service logs are stored at `~/.alpaca/logs/service.log`, or at `<evidenceRoot>/logs/service.log` when a machine-local evidence root is configured. When the active service log grows beyond 50 MiB, the service copies it to a timestamped `service.log.<UTC timestamp>` archive and truncates the active log; rotated archives are not deleted automatically.

`alpaca service enable` installs and starts the service, or refreshes the service definition to the current `alpaca` CLI when it is already running. Run it again after changing Node/npm managers or the global install path. The first install captures supported provider, built-in worker fallback, custom worker, and Alpaca Git author environment variables from the current shell; later `enable` and `restart` runs preserve the existing service definition environment unless `--refresh-env` is passed to replace it from the current shell. `alpaca service disable` stops and removes it after current service work finishes. `alpaca service restart` restarts it after current work finishes using the current CLI. `alpaca service status` shows service state and registered repositories. `alpaca service log show --tail <lines>` shows recent logs.

On Linux and WSL2, service mode requires a working systemd user session (`systemctl --user`). WSL2 support assumes systemd is enabled. If user systemd is unavailable, use foreground `alpaca run` instead of the background service.

Runtime concurrency comes from `parallelism.maxWorkers`, `parallelism.maxIssues`, and `parallelism.mode`. `balance` spreads slots across runnable issues; `greedy` gives earlier issues more slots when possible. Pull request merge monitoring does not consume worker issue slots. When dependency automation is `auto`, pull requests waiting only on open managed dependencies are skipped during merge-monitor scheduling until those dependencies close.

Recurring parent scheduling is covered in `alpaca docs show scheduling`. At runtime, the service creates recurring children only when the recurring parent is due and still below its active-child limit.

Automatic execution stops and hands off when `aiRunLimits.maxRuns` or `aiRunLimits.maxHours` is reached. Issue-level workflow options can override the default limits.

Worker command total timeouts use `workerTimeoutSec` from `alpaca.config.json`. The default is `3600` seconds, and there is no issue-level override. Worker no-output timeouts use `workerNoOutputTimeoutSec`; the default is `600` seconds, and `null` disables the idle watchdog. When a worker command exceeds either timeout, AlpacaLoop terminates the command, records timeout metadata in stderr, treats the command as exit code `124`, and classifies the failure as a timeout with the public message that the AI did not finish in time.

When diagnosing a timeout, start with the issue worker log because it contains the worker command output and the timeout diagnostic:

```bash
alpaca issue log show --issue <id> --tail 100
alpaca issue log search --query "timed_out" --context 2
```

Use the service log when you need the surrounding polling or worker-launch context:

```bash
alpaca service log show --tail 100
```

If a timeout happens before the worker writes useful output, `lastOutputAt=none` in the diagnostic means no stdout or stderr chunk was observed before the timeout. If output was observed, `lastOutputAt` shows when AlpacaLoop last saw worker output. The timeout diagnostic includes `timeoutKind=total` for the full runtime limit and `timeoutKind=idle` for the no-output watchdog. The idle watchdog applies to worker execution only; git, publish, doctor, init, workflow lint, and event-hook commands do not use it. An idle timeout releases execution ownership and retries the issue once; a second idle timeout for the same issue follows the normal timeout human-handoff path. Total timeouts do not auto-retry.

Worker capacity and quota recovery use scheduled retry behavior. `cooldownDefaultSecs.capacity` and `cooldownDefaultSecs.quotaExhausted` provide fallback cooldowns when a worker does not provide a retry time.

Missing workflow templates, workflow template fit gaps, required skills, or required MCP servers can create blocking setup issues before parent planning or execution continues, depending on approval config and workflow selection state. Stay in this guide when the question is runtime status, logs, worker capacity, or why execution is waiting. Use `alpaca docs show command-flows` when the blocker is about workflow template selection or when `workflow_select` must choose `use_template`, `no_template`, or `request_template`.

Service scanning treats first-line `/alpaca ...` comments as workflow commands. Generated workflow update comments, such as `## Needs input: Plan created`, are user-visible status, not workflow command input. Use `/alpaca approve` or `alpaca issue approve --issue <id>` for foreign input approval, and `/alpaca start` or `alpaca issue start --issue <id>` for start approval. The CLI approval paths only post the corresponding approval comment; the next service scan records it. Comment commands remain exact first-line commands, not free-form instructions.

The service discovers fresh workflow comments through provider polling, not webhooks. Normal polls scan changed open candidates instead of every open issue; GitLab additionally uses GitLab Project Events because GitLab issue `updated_at` can miss new comments. Closed follow-up requests are handled by the closed follow-up scan, and editing an old comment is not treated as new workflow input.

Fresh comments during start approval can be treated as plan revision input. Execution still waits until the updated plan is accepted with `/alpaca start` or `alpaca issue start --issue <id>` when start approval remains required.

System errors publish public guidance without exposing internal details. Inspect `alpaca issue log` or service logs before resuming a system-error handoff.

## Watch Outs

- `AI: Running` means AlpacaLoop is running or has accepted a continuation; it does not guarantee a worker process is actively executing at every moment.
- Publishing local workflow or prompt changes is explicit. The service does not run `alpaca publish` automatically.
- Restart the service after package changes only when the running service must reload them before the automatic package-update restart happens.

## Related Docs

- `alpaca docs show workflow-state`
- `alpaca docs show scheduling`
- `alpaca docs show config`
- `alpaca docs show command-flows`
- `alpaca docs show issues`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show maintenance`
