Skip to main content Skip to navigation Skip to footer

Claude Code Setup Guide

Step-by-step guide to configuring Claude Code for autonomous Rediacc infrastructure management.

Claude Code works natively with Rediacc through the rdc CLI. This guide covers setup, permissions, and common workflows.

Safety first: Before wiring an agent into anything that touches secrets, read AI Agent Safety & Guardrails. Claude Code running under rdc is detected as an agent. Sensitive mutations require either --current <previous-value> (passwd-style precondition) or --rotate-secret (acknowledged rotation, audited). Symmetric for humans and agents. Interactive editor, --reveal, and direct machine SSH are refused by default unless you explicitly open them via REDIACC_ALLOW_CONFIG_EDIT. When a precondition fails, the JSON envelope’s errors[].next.options[].run field tells the agent the exact CLI command to suggest the user run. Relay it verbatim.

Quick Setup

  1. Install the CLI: curl -fsSL https://www.rediacc.com/install.sh | bash
  2. Copy the AGENTS.md template to your project root as CLAUDE.md
  3. Start Claude Code in the project directory

Claude Code reads CLAUDE.md on startup and uses it as persistent context for all interactions.

CLAUDE.md Configuration

Place this at your project root. See the full AGENTS.md template for a complete version. Key sections:

# Rediacc Infrastructure

## CLI Tool: rdc

### Common Operations
- Status: rdc machine query --name <machine> -o json
- Deploy: rdc repo up --name <repo> -m <machine> --yes
- Containers: rdc machine containers --name <machine> -o json
- Health: rdc machine health --name <machine> -o json
- SSH: rdc term connect -m <machine> [-r <repo>]

### Rules
- Always use --output json when parsing output
- Always use --yes for automated confirmations
- Use --dry-run before destructive operations

Tool Permissions

Claude Code will request permission to run rdc commands. You can pre-authorize common operations by adding to your Claude Code settings:

  • Allow rdc machine query *, read-only status checks
  • Allow rdc machine containers *, container listing
  • Allow rdc machine health *, health checks
  • Allow rdc config repository list, repository listing

For destructive operations (rdc repo up, rdc repo delete), Claude Code will always ask for confirmation unless you explicitly authorize them.

Example Workflows

Check Infrastructure Status

You: "What's the status of prod-1?"

Claude Code runs: rdc machine query --name prod-1 -o json
→ Shows machine status, repositories, containers, services

Deploy a Repository

You: "Deploy the mail repo to prod-1"

Claude Code runs: rdc repo up --name mail -m prod-1 --dry-run -o json
→ Shows what would happen
Claude Code runs: rdc repo up --name mail -m prod-1 --yes
→ Deploys the repository

Diagnose Container Issues

You: "Why is the nextcloud container unhealthy?"

Claude Code runs: rdc machine containers --name prod-1 -o json --fields name,status,repository
→ Lists container states
Claude Code runs: rdc term connect -m prod-1 -c "docker logs nextcloud-app --tail 50"
→ Checks recent logs

File Sync

You: "Upload the local config to the mail repo"

Claude Code runs: rdc repo sync upload -m prod-1 -r mail -l ./config --dry-run
→ Shows files that would be synced
Claude Code runs: rdc repo sync upload -m prod-1 -r mail -l ./config
→ Syncs the files

Tips

  • Claude Code auto-detects non-TTY and switches to JSON output, no need to specify -o json in most cases
  • Use rdc agent capabilities to let Claude Code discover all available commands
  • Use rdc agent schema "command name" for detailed argument/option info
  • The --fields flag helps keep context window usage low when you only need specific data