Deploy · Claudear Docs

#Deployment checklist

Run claudear seed so Claudear starts from now, not your entire backlog
Confirm the dashboard loads at your configured port
Trigger a test issue with claudear trigger to verify the full cycle
Tune max_concurrent and per-source limits for your volume
Enable regression monitoring and scheduled reports

#Background daemon

Start Claudear as a long-running background process:

claudear start --poll --port 3100

Flags:

--poll — enables polling for new issues on a timer
--port — sets the dashboard and webhook listen port
--no-webhooks — disables the webhook server
--no-dashboard — disables the web dashboard

Control a running daemon with:

claudear status     # check if the daemon is running
claudear pause      # pause issue processing
claudear resume     # resume issue processing
claudear stop       # gracefully shut down

#macOS (launchd)

Create a plist at ~/Library/LaunchAgents/com.claudear.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.claudear.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/claudear</string>
    <string>start</string>
    <string>--poll</string>
    <string>--port</string>
    <string>3100</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/your/project</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>CLAUDEAR_GITHUB_TOKEN</key>
    <string>ghp_...</string>
    <key>CLAUDEAR_LINEAR_API_KEY</key>
    <string>lin_api_...</string>
  </dict>
  <key>StandardOutPath</key>
  <string>/tmp/claudear.out.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/claudear.err.log</string>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

Load and start the service:

launchctl load ~/Library/LaunchAgents/com.claudear.daemon.plist
launchctl start com.claudear.daemon

#Linux (systemd)

Create a unit file at /etc/systemd/system/claudear.service:

[Unit]
Description=Claudear daemon
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/your/project
EnvironmentFile=/etc/claudear/env
ExecStart=/usr/local/bin/claudear start --poll --port 3100
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Store secrets in /etc/claudear/env:

CLAUDEAR_GITHUB_TOKEN=ghp_...
CLAUDEAR_LINEAR_API_KEY=lin_api_...

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable claudear
sudo systemctl start claudear
sudo journalctl -u claudear -f   # follow logs

#Docker

Compose (recommended)

If your project includes a docker-compose.yml, this is the simplest path:

docker compose up -d
docker compose logs -f claudear
docker compose down

Standalone

Run the container directly:

docker run -d --name claudear \
  -v $(pwd)/claudear.toml:/app/claudear.toml:ro \
  -v claudear-data:/app/data \
  -p 3100:3100 \
  ghcr.io/abnegate/claudear:latest start --poll --port 3100

Health check: GET /api/health returns 200 when Claudear is up.

#Environment variables

You can override any secret in claudear.toml with an environment variable. This is the recommended approach for production so secrets stay out of config files.

Variable	Overrides
`CLAUDEAR_LINEAR_API_KEY`	`issues.linear.api_key`
`CLAUDEAR_SENTRY_AUTH_TOKEN`	`issues.sentry.auth_token`
`CLAUDEAR_GITHUB_TOKEN`	`scm.github.token`
`CLAUDEAR_JIRA_API_TOKEN`	`issues.jira.api_token`
`CLAUDEAR_DISCORD_BOT_TOKEN`	`notifiers.discord.bot_token`
`CLAUDEAR_SLACK_BOT_TOKEN`	`notifiers.slack.bot_token`
`CLAUDEAR_TLS_ENABLED`	`tls.enabled`
`CLAUDEAR_TLS_DOMAINS`	`tls.domains` (comma-separated)
`CLAUDEAR_TLS_EMAIL`	`tls.email`
`CLAUDEAR_TLS_PRODUCTION`	`tls.production`
`CLAUDEAR_GITLAB_TOKEN`	`scm.gitlab.token`
`CLAUDEAR_GITLAB_WEBHOOK_SECRET`	`scm.gitlab.webhook_secret`
`CLAUDEAR_JIRA_API_TOKEN`	`issues.jira.api_token`
`CLAUDEAR_DISCORD_BOT_TOKEN`	`notifiers.discord.bot_token`
`CLAUDEAR_SLACK_BOT_TOKEN`	`notifiers.slack.bot_token`
`CLAUDEAR_EMBEDDING_MODEL`	Embedding model (`nomic`, `minilm`, `bge`)
`CLAUDEAR_EMBEDDING_CACHE_DIR`	Embedding model cache directory
`CLAUDEAR_VECTORLITE_PATH`	Path to vectorlite SQLite extension
`CLAUDEAR_SENTRY_DSN`	Sentry DSN for backend error reporting
`CLAUDEAR_TLS_CACHE_DIR`	`tls.cache_dir`
`CLAUDEAR_TLS_HTTPS_PORT`	`tls.https_port`
`CLAUDEAR_TLS_HTTP_REDIRECT_PORT`	`tls.http_redirect_port`

#Tips for production

Log rotation — set up log rotation or use --log-dir with daily rotation to avoid unbounded disk usage
Reply-capable notifications — use a reply-capable notification channel so you can answer AI questions directly from chat
Health monitoring — monitor the /api/health endpoint with your existing uptime checker or alerting tool
Concurrency — start with conservative max_concurrent (1–2) and increase as needed once you are confident in the pipeline
Native TLS — set tls.enabled = true with your domain in tls.domains to auto-provision Let’s Encrypt certificates without a reverse proxy. Test with tls.production = false (staging) first, then switch to production once verified
Security headers — the API server includes HSTS, X-Content-Type-Options, X-Frame-Options, and CSRF protection (double-submit cookie) by default. Idle sessions are automatically cleaned up
Local LLM — enable [llm] for offline repo classification and code chat. Set gpu_layers = 99 for GPU acceleration. The model auto-downloads on first use if model_url is configured