Quick Start

Requirements

• Docker (Docker Desktop on macOS / Windows, or Docker Engine on Linux)
• A terminal. For copying text out of tmux, see the host terminal settings in tmux.

The image supports linux/amd64 and linux/arm64, so it runs natively on Intel / AMD machines and on Apple Silicon.

1. Pull the image

docker pull yeciorg/yeci

The same image is also available from two mirrors, if Docker Hub's yeciorg/yeci is slow or unreachable for you:

docker pull ghcr.io/yeciorg/yeci    # GitHub Container Registry
docker pull tourcoder/yeci          # Docker Hub, original repository

If you pull from a mirror, use that image name in the docker run command below as well.

2. Start a container for your project

Run this from your project directory:

PROJECT_NAME=$(basename "$PWD")

docker run -d \
--rm \
--name "yeci-$PROJECT_NAME" \
--network host \
-v "$PWD":/workspace \
docker.io/yeciorg/yeci > /dev/null

What the options do:

Option	Meaning
-d	Run in the background. The container keeps running until you stop it.
--rm	Delete the container when it stops. Your project files are not affected (see below).
--name "yeci-$PROJECT_NAME"	One container per project, named after the project directory.
--network host	Share the host network, so dev servers started in the container are reachable on localhost. On Docker Desktop (macOS / Windows), host networking has to be enabled in Docker Desktop's settings first.
-v "$PWD":/workspace	Mount the current directory at /workspace, the container's working directory.

3. Open a shell

docker exec -it "yeci-$PROJECT_NAME" /bin/bash

You land in /workspace, which is your project directory. Everything you change there is changed on your machine.

To work with several panes (for example an AI agent on one side and a shell on the other), start tmux:

tmux

See tmux for the key bindings.

4. Start an AI agent

claude    # or: codex, gemini, grok

The first run asks you to sign in. See AI Coding Agents.

5. Stop the container

docker stop "yeci-$PROJECT_NAME"

Because of --rm, the container is deleted when it stops. Files in /workspace are safe, because they live on your machine. Everything else inside the container is gone, including agent logins. To keep logins across restarts, see Data & Persistence.