Skip to content
Kod Docs

Installation & Quickstart

Prerequisites

Section titled “Prerequisites”
  • Node.js 24 or later
  • Basic comfort with the command line

Installation

Section titled “Installation”
Terminal window
curl -sSL https://releases.itskod.com/install.sh | bash

Verify the installation:

Terminal window
kod --version

Quickstart

Section titled “Quickstart”

  1. Start the server

    Start Kod with an admin token. This token is used for all administrative operations.

    Terminal window
    KOD_ADMIN_TOKEN=kod_my_secret_token kod serve

    You can also pass it as a flag:

    Terminal window
    kod serve --admin-token kod_my_secret_token

    The server starts on http://localhost:3000 by default.

  2. Configure the CLI

    In a new terminal, run kod init to set up the client:

    Terminal window
    kod init
    # Server URL: http://localhost:3000
    # API Token: kod_my_secret_token

    This saves your configuration to ~/.kod/config.json.

  3. Create a repository

    Terminal window
    kod repo create my-project

  4. Clone and push code

    The easiest way is with kod clone, which handles authentication automatically:

    Terminal window
    kod clone my-project
    cd my-project
    

    echo "# My Project" > README.md
    git add . && git commit -m "Initial commit"
    git push origin main

    Plain git clone also works. If you installed Kod globally, kod init configures a Git credential helper so authentication is automatic:

    Terminal window
    git clone http://localhost:3000/repos/my-project.git

    If the credential helper is not installed, Git will prompt for credentials. Use any username (e.g. git) and your API token as the password.

  5. Add a workflow (optional)

    Create .kod/workflows/build.toml in your repository:

    [step:test]
    run: npm test
    

    [step:build]
    run: npm run build

    Push again, and Kod will automatically run the workflow.

VM Deployment

Section titled “VM Deployment”

To deploy Kod on a VPS (DigitalOcean, Scaleway, Hetzner, etc.):

Terminal window
# Install Kod
curl -sSL https://releases.itskod.com/install.sh | bash


# Create a systemd service
sudo tee /etc/systemd/system/kod.service > /dev/null <<EOF
[Unit]
Description=Kod Git Server
After=network.target


[Service]
Type=simple
User=kod
Environment="KOD_ADMIN_TOKEN=kod_your_secret_token"
Environment="KOD_ENCRYPTION_KEY=your-encryption-key"
ExecStart=/usr/local/bin/kod serve --port 3000
Restart=always


[Install]
WantedBy=multi-user.target
EOF


sudo systemctl enable kod
sudo systemctl start kod

Next Steps

Section titled “Next Steps”