Quickstart

Requirements

Use a Linux host with Docker Compose, a GitHub account, a public HTTPS address, and credentials for at least one agent. The images support ARM64 and AMD64.

To let a coding agent do these steps, open the repository in Claude Code or Codex and ask it to set up CroCode. The crocode-setup skill in .agents/skills/ guides the agent. It asks before sudo commands and never shows secrets.

1. Prepare the environment

git clone https://github.com/kacigaya/crocode.git
cd crocode
cp .env.example .env
chmod 600 .env
stat -c '%g' /var/run/docker.sock

1. Set separate POSTGRES_PASSWORD and CROCODE_DB_PASSWORD values in .env. Match the first to MIGRATION_DATABASE_URL and the second to DATABASE_URL.
2. Set the model credentials for your agent. For a Claude subscription, set CLAUDE_CODE_OAUTH_TOKEN and leave ANTHROPIC_API_KEY empty. For a ChatGPT subscription, follow the Codex login steps.
3. Set DOCKER_GID to the socket group ID printed by the command above.
4. Leave the GitHub App values empty. The setup page creates them.

The example enables Claude and OpenCode. Enable Codex only after you verify its bubblewrap sandbox on your Docker host.

2. Build and start CroCode

Create the work directory with the worker UID and GID. Its absolute path must match on the host and inside the worker.

sudo install -d -m 0755 -o 10000 -g 10000 /var/lib/crocode/work
sudo docker build -t crocode-sandbox:latest docker/sandbox
sudo docker compose --profile dashboard up -d --build

Postgres stores review jobs and findings. The API and worker wait for the GitHub App credentials from setup. Do not put dashboard secrets in the backend .env.

3. Set up HTTPS

Put an HTTPS reverse proxy in front of the services. Use one public origin for setup and sign-in.

Preserve the public Host or X-Forwarded-Host header. The dashboard checks request origins for sign-in and settings changes.

4. Create the GitHub App

sudo docker compose logs web | grep setup

1. Open the setup link on your public address. Keep its token private.
2. Confirm the public address and app name. Select Create the GitHub App.
3. Confirm the app creation on GitHub. CroCode saves the credentials.
4. Follow the done page to install the app, upload the logo, and sign in.
5. Open a small pull request in an installed repository. Check its review history in the dashboard.

To use an existing app or keep its private key out of the dashboard, follow manual GitHub App setup.