---
title: Setup and Repository Assets
description: Repository initialization, worker sign-in, health checks, repo-local assets, detach, and cleanup.
relatedCommands:
  - alpaca init --help
  - alpaca auth setup --help
  - alpaca auth list --help
  - alpaca doctor --help
  - alpaca eject --help
  - alpaca detach --help
  - alpaca cleanup --help
relatedDocs:
  - quick-start
  - install
  - config
  - service-runtime
  - capabilities
  - maintenance
---

# Setup and Repository Assets

Use this guide when preparing a repository for AlpacaLoop, checking whether setup is healthy, or removing AlpacaLoop from a repository. Check the relevant command help before changing local state.

## When to Use

- Run `alpaca init` when the repository needs an `alpaca.config.json`, service registration, repo-local skill assets, or initial worker sign-in setup.
- Run `alpaca auth setup` when a built-in worker provider needs interactive sign-in. Run `alpaca auth list` or `alpaca auth order` to inspect machine-local profiles.
- Run `alpaca doctor` when config, worker auth, labels, repo registration, remote base branches, cooldowns, or workflow templates need a health check.
- Run `alpaca eject` only when packaged workflows, system prompts, or catalog entries need repo-local customization.
- Run `alpaca detach` when the repository should no longer be managed by the background service.
- Run `alpaca cleanup` for machine-local AlpacaLoop state or eligible worker workspaces.

## Key Commands

```bash
alpaca init -h
alpaca auth setup -h
alpaca doctor -h
alpaca eject -h
alpaca detach -h
alpaca cleanup -h
```

## Core Behavior

`alpaca init` creates or updates repository setup. It writes `alpaca.config.json`, registers the repository for the background service, installs repo-local Alpaca skill assets for configured worker runtimes, and resolves initial sign-in requirements. Repository and tracker providers can be GitHub, Gitea, or GitLab. `--create-repo` is Gitea-only in this version and requires the tracker project to match the repository project. When `--create-repo` creates a new empty Gitea repository, AlpacaLoop checks that local `HEAD` points to a commit before creating the remote, then pushes `HEAD` to the configured base branch. Existing Gitea repositories are never auto-pushed by `init`; use `alpaca doctor` to detect a missing remote base branch.

Use `alpaca init --language <en|ja|zh> --display-time-zone <zone>` to set initial user-facing language and scheduling/display time zone. Use `alpaca init --remote-name <name>` when a repository has multiple Git remotes and AlpacaLoop should clone, fetch, checkout, and push through a specific remote.

Provider setup usually comes from AlpacaLoop-specific credentials. GitHub uses `ALPACA_GITHUB_TOKEN`, or `gh auth login` for local CLI credentials. Gitea uses `ALPACA_GITEA_USERNAME` and `ALPACA_GITEA_PASSWORD`, or Git credentials. GitLab uses `ALPACA_GITLAB_TOKEN` with project access. The first `alpaca service enable` captures supported service environment variables from the current shell; after changing them for an existing service, run `alpaca service enable --refresh-env` or `alpaca service restart --refresh-env`.

AlpacaLoop uses native Git for clone, fetch, commit, and push. Git account identity is not stored in `alpaca.config.json`. For background service or worker commits that should use a Bot identity, set machine-local environment variables:

```bash
export ALPACA_GIT_USER_NAME="AlpacaLoop Bot"
export ALPACA_GIT_USER_EMAIL="bot@example.com"
```

Manual terminal use can continue to use the user's repository or global Git config. Service and worker processes can use separate Bot env and tokens.

Worker authentication is machine-local for built-in workers. `alpaca auth setup` performs Codex and Claude provider sign-in; `alpaca auth list` shows registered profiles and cooldown state; `alpaca auth order` shows built-in worker preference order; `alpaca auth clear` removes machine-local profiles. Secrets and OAuth browser login are human handoff steps.

Stored Claude API key profiles use the OS credential store. Codex and Claude both support environment-variable fallbacks: `OPENAI_API_KEY` for Codex and `ANTHROPIC_API_KEY` for Claude. On headless Linux or WSL2 hosts without a usable keyring session, choose the environment-variable method instead of a stored Claude API key.

Custom workers do not use `alpaca auth setup` or machine-local auth profiles. Configure them in `alpaca.config.json` under `customWorkers`, using `${ENV_NAME}` for endpoint, header secrets, or string values in `requestParams`. `requestParams` is for provider-specific OpenAI-compatible POST body overrides, not URL query parameters or headers, and is not semantically validated by AlpacaLoop. They run through the Pi SDK and require Node.js `>=22.19.0` at runtime. Local LLMs such as Ollama or LM Studio must already be running with an OpenAI-compatible API; AlpacaLoop does not pull, start, or manage model processes.

`alpaca doctor` is the first repair check for most setup questions. It validates config, worker availability, sign-in state, cooldowns, managed labels, repo registration, remote base branch availability, and workflow template health.

`alpaca eject` copies packaged assets into the repository when local customization is needed. Reference docs under `skills/alpaca/references` remain canonical CLI docs and are not edited through `eject`.

| Eject target | Packaged source | Repository destination | Use when |
| --- | --- | --- | --- |
| `workflows` | `package-assets/system/workflows/*.md` | `.alpaca/workflows/__system/*.md` | A packaged system workflow needs a repository-specific override. |
| `system-prompts` | `package-assets/system/system-prompts/*.md` | `.alpaca/system-prompts/*.md` | Worker guidance for issue drafting, workflow planning or execution, automatic follow-up recommendation, event-hook authoring, merge integration, or handoff style needs repository-specific wording. |
| `catalog` | `package-assets/system/catalog/*.json` | `.alpaca/catalog/__system/*.json` | Curated skill/MCP install candidates or shared catalog metadata need repository-local customization. |

Use this table when deciding which ejected system prompt to customize. AlpacaLoop combines common prompts with run-specific prompts, so a worker may receive more than one row.

| System prompt | Used during | Customize when |
| --- | --- | --- |
| `worker-common` | Most worker and draft prompts. | Every worker should follow the same repository-wide wording, primary-intent, evidence, or operating convention. |
| `workflow-common` | All workflow selection, planning, execution, reconciliation, and closing runs; prompt-mode issue drafts; workflow template draft and update prompts. | AlpacaLoop-managed work needs shared guidance such as blocker routing, evidence quality, in-scope human concerns, or concise workflow comments. |
| `issue-create` | Prompt-mode `alpaca issue create --prompt` issue drafting. | Generated issue titles or bodies need durable repository wording rules. |
| `workflow-create` | Prompt-mode `alpaca workflow create/update --prompt` template authoring. | Reusable workflow template bodies, requirements, target selection, or authoring style need repository guidance. |
| `workflow-planning` | `workflow_plan` runs. | Plans need repository-specific splitting, dependency, child issue, primary-intent, or verification guidance. |
| `workflow-plan-review` | Automated review after top-level `workflow_plan` drafts. | Plan acceptance or revision feedback needs repository-specific quality gates, risk thresholds, or evidence expectations. |
| `workflow-execution` | `workflow_execute` and step-batch reconciliation runs. | Current-step execution, continuation, conservative/efficient path, or verification behavior needs repository-specific guidance. |
| `workflow-closing` | `workflow_closing` runs. | Final issue-level completion audit, completion report wording, close readiness, or follow-up recommendation judgment needs repository-specific guidance. |
| `human-handoff` | Workflow planning, execution, reconciliation, and closing runs when handoff rules are available to the worker. | Human handoff wording or boundaries need repository-specific guidance. |
| `followup-recommendation-guidance` | `workflow_closing` only when source `followup.proposalPolicy` is not `off`. | Automatic follow-up recommendations need repository-specific judgment about useful post-completion work. |
| `event-hook-create` | Prompt-mode `alpaca event-hook create/update --prompt` hook authoring. | Generated event hook files need durable repository conventions. |
| `merge-guidance` | Merge integration. | Merge behavior, integration evidence, or PR finalization guidance needs repository-specific wording. |

Run the narrowest eject target that matches the asset you intend to edit. Ejected system assets override packaged fallbacks for that repository; deleting the ejected copy returns the repository to the packaged default. Use `--force` only when replacing an existing ejected file with the packaged version is intentional.

`alpaca detach` unregisters a repo from service management. Without `--purge`, it leaves local files in place. With `--purge`, it can delete AlpacaLoop-managed repo files, repo-local `.alpaca` files, and the project workspace root after confirmation. `--force` allows deleting modified managed files and should be reserved for disposable local edits.

`alpaca cleanup` removes machine-local state or, with `--workspaces`, cleans eligible worker workspaces for closed or finished work.

## Worker Workspace Setup

Use `workspaces.setupCommand` when issue workspaces need dependencies before a worker can run:

```json
{
  "workspaces": {
    "setupCommand": "pnpm install --frozen-lockfile",
    "setupFrequency": "when_changed",
    "setupWatchPaths": "auto",
    "setupTimeoutSec": 600
  }
}
```

`setupCommand` runs inside the issue workspace before worker execution. `setupWatchPaths: "auto"` fingerprints common dependency files for Node, Python, PHP, Ruby, Go, Rust, and Deno. Explicit watch paths must be repo-relative files or directories without `.` or `..` path segments. AlpacaLoop stores setup metadata in Git-private workspace storage, not in tracked files. It does not symlink dependency directories such as `node_modules`, `vendor`, or virtualenvs. `once` skips after the first successful setup, while `always` runs before every worker attempt. Setup failures leave the last-successful metadata unchanged, write redacted stdout/stderr summaries to the issue log, stop before worker launch, and hand the issue back for human repair without counting an AI run.

## Watch Outs

- Do not assume `alpaca init` migrated old tracker labels. If label names changed, run `alpaca labels sync`; existing issues with old labels are not renamed automatically.
- Do not put secrets into config, issue text, catalog entries, or workflow templates.
- Use `alpaca publish` after local workflow, prompt, or catalog changes need to become visible to service automation.

## Related Docs

- `alpaca docs show config`
- `alpaca docs show quick-start`
- `alpaca docs show install`
- `alpaca docs show service-runtime`
- `alpaca docs show capabilities`
- `alpaca docs show maintenance`
