Skip to main content
Docker is the fastest way to get Codeg running in a reproducible environment. The official image uses a multi-stage build (Node.js for the frontend, Rust for the server binary) and a slim Debian runtime that includes git, ssh, python3, and curl — everything you need for coding workflows out of the box. Common use cases
  • Cloud VM or VPS hosting with a single command
  • Shared team instances with persistent data volumes
  • CI systems that need an isolated Codeg environment

​
Quick start with Docker Compose

Docker Compose is the recommended way to run Codeg. It handles the volume, port mapping, and restart policy for you.
1

Get the compose file

Download the docker-compose.yml from the repository, or create it with the following content:
docker-compose.yml
services:
  codeg:
    image: ghcr.io/xintaofei/codeg:latest
    ports:
      - "3080:3080"
    volumes:
      - codeg-data:/data
      # Mount your project directories (optional):
      # - /path/to/projects:/projects
    environment:
      - CODEG_TOKEN=${CODEG_TOKEN:-}
      - CODEG_PORT=3080
      - CODEG_HOST=0.0.0.0
    restart: unless-stopped

volumes:
  codeg-data:
2

Set your token

Export a fixed token before starting so it persists across container restarts:
export CODEG_TOKEN=your-secret-token
Or create a .env file in the same directory:
.env
CODEG_TOKEN=your-secret-token
3

Start Codeg

docker compose up -d
4

Open in your browser

Navigate to http://localhost:3080 and enter your token.

​
Run with Docker directly

Use docker run if you prefer not to use Compose or want to integrate Codeg into an existing setup. Minimal — ephemeral data: 
docker run -d -p 3080:3080 \
  -v codeg-data:/data \
  ghcr.io/xintaofei/codeg:latest
With a fixed token and mounted project directories: 
docker run -d -p 3080:3080 \
  -v codeg-data:/data \
  -v /path/to/projects:/projects \
  -e CODEG_TOKEN=your-secret-token \
  ghcr.io/xintaofei/codeg:latest

​
Get the auth token

If you did not set CODEG_TOKEN, Codeg generates a random token on startup and prints it to stderr. Retrieve it from the container logs: 
docker logs <container-name> 2>&1 | grep token
Replace <container-name> with the name shown in docker ps (e.g., codeg-codeg-1 for Compose deployments).
Without CODEG_TOKEN, a new random token is generated each time the container restarts. Always set CODEG_TOKEN in production so your sessions survive restarts.

​
Volume mounts

Mount pathPurpose
/dataCodeg’s SQLite database and settings. Persist this volume to keep your data across container updates.
/projects (or any path)Mount local directories you want to access from within the workspace. The path inside the container can be anything.
The image sets CODEG_DATA_DIR=/data by default, so the named volume codeg-data maps directly to the database location.

​
Configuration

All configuration is done through environment variables. Pass them with -e flags or in your docker-compose.yml environment block.
VariableDefaultDescription
CODEG_PORT3080HTTP port the server listens on
CODEG_HOST0.0.0.0Bind address
CODEG_TOKEN(random)Auth token — printed to stderr on start if not set
CODEG_DATA_DIR/dataSQLite database directory (pre-set in the image)
CODEG_STATIC_DIR/app/webFrontend assets directory (pre-set in the image)
CODEG_DATA_DIR and CODEG_STATIC_DIR are pre-configured in the Docker image. You only need to override them if you mount assets or data to different paths.

​
Update to the latest image

1

Pull the latest image

docker pull ghcr.io/xintaofei/codeg:latest
2

Restart the container

docker compose up -d
Compose detects the new image and recreates the container. Your data in the codeg-data volume is preserved.

​
Image details

  • Registry: ghcr.io/xintaofei/codeg:latest
  • Base OS: Debian slim runtime — small footprint, production-ready
  • Included tools: git, ssh, python3, curl — everything needed for coding workflows
  • Exposed port: 3080
  • Default data volume: /data
The image bundles both the server binary (/usr/local/bin/codeg-server) and the compiled frontend assets (/app/web), so no additional build steps are required.
In production, place Codeg behind a reverse proxy (nginx, Caddy, Traefik) to terminate TLS and serve it over HTTPS. Do not expose port 3080 directly to the public internet without a valid token and HTTPS in place.