Skip to content

This guide will get you from zero to a working Kizuna instance in under 10 minutes.

Option 1: Try Kizuna Cloud (Fastest) ​

The fastest way to experience Kizuna is with our managed cloud offering:

  1. Sign up at cloud.kizuna.codes
  2. Create an organization — your workspace for repositories
  3. Create your first repository — click "New Repository" and follow the prompts
  4. Clone and start coding:
    bash
    jj git clone https://cloud.kizuna.codes/your-org/your-repo
    cd your-repo
    # Start making changes — jj tracks everything automatically

Option 2: Self-Host with Docker ​

Run Kizuna OSS locally or on your own infrastructure:

Prerequisites ​

  • Docker 24.0+
  • Docker Compose 2.0+

1. Download the Compose File ​

bash
curl -O https://raw.githubusercontent.com/kizuna-platform/kizuna/main/docker-compose.yml

2. Start the Services ​

bash
docker-compose up -d

This starts:

  • Kizuna web application (port 4000)
  • PostgreSQL database
  • Valkey (Redis-compatible cache)

3. Create an Admin User ​

bash
docker-compose exec kizuna bin/kizuna eval "KizunaCore.Release.create_admin('admin@example.com', 'changeme')"

4. Access Kizuna ​

Open http://localhost:4000 and sign in with your admin credentials.

Your First Repository ​

Create via Web UI ​

  1. Click New Repository on the dashboard
  2. Enter a name (e.g., hello-kizuna)
  3. Choose visibility: Public, Internal, or Private
  4. Click Create Repository

Clone with Jujutsu ​

bash
# Clone the repository
jj git clone http://localhost:4000/your-org/hello-kizuna
cd hello-kizuna

# Make your first change
echo "# Hello Kizuna" > README.md

# The change is automatically committed in jj
jj log

# Push to the server
jj git push

Clone with Git ​

Kizuna is fully Git-compatible:

bash
git clone http://localhost:4000/your-org/hello-kizuna
cd hello-kizuna
echo "# Hello Kizuna" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Register Your First Agent ​

Kizuna treats AI agents as first-class participants:

  1. Go to Settings → Agents
  2. Click Register New Agent
  3. Enter:
    • Name: my-first-agent
    • Model Family: claude
    • Model Version: 3.5-sonnet
  4. Select Trust Level 1 (Restricted — draft changes only)
  5. Click Register

Your agent now has an AgentID and can interact with repositories via the MCP server.

Install the CLI (Optional) ​

The Kizuna CLI (kz) lets you manage everything from the terminal, including a full TUI:

bash
# macOS (Apple Silicon)
curl -L https://releases.kizuna.codes/cli/latest/kz-darwin-arm64 -o kz
chmod +x kz && sudo mv kz /usr/local/bin/

# Set up and authenticate
kz config init
kz auth login

See the CLI Overview for all platforms and build-from-source instructions.

Next Steps ​

Getting Help ​