> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getgaal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Short answers to questions that come up a lot.

## Does gaal upload my configuration anywhere?

No. gaal is local-only today. The only outbound network calls are to the URLs you list in `gaal.yaml` (`skills[].source`, `mcps[].source`) and, if you opted in, anonymous telemetry events. See [Telemetry](https://docs.getgaal.com/concepts/telemetry.md).

## Is gaal a daemon?

It can be. `gaal sync` is one-shot by default; `gaal sync --service --interval 5m` keeps it running in a loop. See [Sync vs. service mode](https://docs.getgaal.com/workflows/sync-vs-service.md).

## Can I use gaal without git?

Yes. The `git` repository type uses a pure-Go backend, so you don't need a system `git` binary. `hg`, `svn`, and `bzr` *do* require their respective system binaries. `tar` and `zip` only need an HTTPS connection.

## Can I run gaal in CI?

Yes. The recommended pattern is `gaal --sandbox $RUNNER_TEMP/gaal-sb sync --dry-run` to validate your config without touching the runner. See [Sandbox mode](https://docs.getgaal.com/workflows/sandbox-mode.md).

## Will gaal overwrite my hand-edited Claude / Cursor / VS Code config?

No. gaal only touches the `mcpServers` keys it manages inside each target file. Other top-level keys, and any MCP entries not in `gaal.yaml`, are preserved. See [The upsert guarantee](https://docs.getgaal.com/concepts/mcp-servers.md#the-upsert-guarantee).

## Will gaal delete a skill if I remove it from gaal.yaml?

Not by default. Skills you remove from the config are left in place. To clean them up, run `gaal sync --prune`. See [Pruning](https://docs.getgaal.com/workflows/pruning.md).

## Why isn't my gaal.yaml being picked up?

gaal searches in this order: `--config` → `./gaal.yaml` → `~/.config/gaal/config.yaml` → `/etc/gaal/config.yaml`. Run `gaal doctor`, the output names the source file for every setting. If it's not finding your file, you're probably in the wrong directory or your file is named something other than `gaal.yaml`.

## Can I use gaal across multiple machines?

Yes, that's the main use case. Commit your `gaal.yaml` (and your user-scope config, if you keep one) to a dotfiles repo, clone it on every machine, run `gaal sync`. See [Sharing across machines](https://docs.getgaal.com/workflows/sharing-across-machines.md).

## Can gaal manage agents I haven't installed yet?

Yes, pass `--force` to `gaal sync` and skill directories will be created for every registered agent regardless of installation. Useful for pre-staging fresh machines.

## How do I add an agent gaal doesn't support?

Write a custom registry file at `~/.config/gaal/agents.yaml`. See [Custom agents](https://docs.getgaal.com/configure/custom-agents.md).

## How do I keep secrets out of gaal.yaml?

Reference environment variables in `args:` and `env:` blocks. gaal writes them through verbatim; the agent process resolves them when launching the MCP server. See [Environment & secrets](https://docs.getgaal.com/configure/environment-and-secrets.md).

## What's the difference between gaal and Community Edition?

gaal today is the single-user CLI documented on this site. Community Edition (in development) adds a shared registry, drift detection, and approval workflows for teams. The `gaal migrate` command is the graduation path. See [`gaal migrate`](https://docs.getgaal.com/cli/migrate).

## Is gaal open source?

Yes. gaal is licensed under [AGPL-3.0](https://github.com/getgaal/gaal/blob/main/LICENSE).

## Where can I report a bug?

[github.com/getgaal/gaal/issues](https://github.com/getgaal/gaal/issues). Include the output of `gaal version` and `gaal doctor -o json`.

## Related

> [card] [gaal doctor](https://docs.getgaal.com/troubleshooting/doctor.md)

> [card] [Common errors](https://docs.getgaal.com/troubleshooting/common-errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.