Docker Setup – Xedant

Don’t want to read all this?

Just drop a link to https://xedant.com/agents/agent/docker.md or to https://xedant.com/llms.txt into any AI chat (Claude, ChatGPT, etc.) and ask it to generate the config files and commands. It will read the docs, ask you a few questions about your setup, and hand you a ready-to-use configuration. Save time — let the model do the reading for you.

You can also reach me on Telegram — I’m always glad to help. And that’s not just politeness — I genuinely enjoy talking to like-minded people, especially if you love coding as much as I do.

Docker is a container technology: the app runs in a fully isolated environment where all the tools it needs are prepared in advance. One container per project. It is safe: even if an AI model starts misbehaving, only its own container can suffer — not your server or computer. A broken container is recreated in seconds. One more benefit: tools and settings can be added for a specific project, instead of bloating a universal image.

Minimum system requirements

The minimal Docker image runs confidently even on a single-CPU VPS with 2 GB of RAM — alongside other services like Apache, PHP, MySQL or nginx on a live site:

1 GB RAM — the container uses ~430 MB at idle, up to 800 MB under active work (depending on the tools called)
1 CPU core — ~6% at idle, up to 80% of one core under active work (depending on the tools called)

Docker Desktop users: if you prefer a graphical interface for Docker, use the guide for your platform: Windows Docker Desktop or Mac Docker Desktop.

We publish two ready-made Docker images: registry2.xedant.com/agent:latest and registry2.xedant.com/agent-min:latest. The difference is the set of tools — and the size follows from it.

The dev image (2.8 GB) contains Xedant Agent and everything needed to develop and build it — first of all the .NET build toolchain (ASP.NET Core SDK) and Node.js with build and code-checking tools. Pick it if you build client-server apps on ASP.NET Core and Node.js.

What is inside the dev image

ASP.NET Core 9.0 SDK — building and running .NET apps
Node.js (LTS) — the JavaScript runtime with the npm package manager
Python 3 — the Python language with pip and venv
Claude Code CLI — the console agent Xedant Agent runs on
dotnet-ef — managing Entity Framework Core database migrations
JetBrains ReSharper CLI — inspecting and cleaning .NET code
flake8 — Python code style checks
Docker + Docker Compose — managing containers from inside the container
git — version control
mc — the Midnight Commander file manager
ncdu — disk usage analysis
sqlite3 — working with the SQLite database from the command line
curl, wget, rsync, zip, unzip — network utilities and archivers

The minimal image (570 MB) contains Xedant Agent with Python and all the tools it needs to work — a full-featured image for projects that don’t need .NET builds. It is noticeably smaller, yet everything the agent needs is already there. Missing a library? Ask the agent to install it right in the container. Or build your own image on top of it, tailored to your tasks. If you need help with that, message us on Telegram.

What is inside the minimal image

ASP.NET Core 9.0 Runtime — running .NET apps (no builds needed, so no SDK)
Node.js (LTS) — the JavaScript runtime with the npm package manager
Python 3 — the Python language with pip and venv
Claude Code CLI — the console agent Xedant Agent runs on
flake8 — Python code style checks
Docker + Docker Compose — managing containers from inside the container
git — version control
mc — the Midnight Commander file manager
ncdu — disk usage analysis
sqlite3 — working with the SQLite database from the command line
curl, wget, rsync, zip, unzip — network utilities and archivers

Framework-specific images are on the roadmap. Message us on Telegram about the stack you use — building and maintaining new images is easy for us; we mainly need to know what you actually use in practice.

Extending the image with your own tools

Both images already contain everything the agent needs to work. But if your project uses specific languages or tools, you can build your own image on top of registry2.xedant.com/agent-min:latest — with exactly the tools you need. Every new container then starts with a ready environment, instead of installing packages on every recreate.

Creating your own Dockerfile

Next to your docker-compose.yml, create a Dockerfile — the build recipe for the image, listing which packages to add:

FROM registry2.xedant.com/agent-min:latest

# Add system packages
RUN apt-get update && apt-get install -y \
    ruby \
    default-jdk \
    && rm -rf /var/lib/apt/lists/*

# Add Python packages
RUN python3 -m pip install --break-system-packages \
    fastapi \
    pytest

# Add Node.js packages (Node.js is pre-installed in min image)
RUN npm install -g \
    typescript \
    @angular/cli

# Add global tools
RUN dotnet tool install -g Your.Tool.Name

Then point docker-compose.yml at your own image instead of the ready one — Docker builds it from your Dockerfile:

services:
  my_project:
    container_name: my_project
    build: .                    # builds from Dockerfile in this directory
    image: my-project:latest    # tag for the built image
    ports:
      - "5001:80"
    volumes:
      - "./MyProject:/project"
    environment:
      - AGENT_LOGIN=agent
      # ... rest of your environment variables
    restart: unless-stopped
    working_dir: /app

Build and start:

docker compose up -d --build

The --build flag rebuilds your image when the Dockerfile changes; without it, Docker uses the last finished build.

Or just ask the model

You don’t have to fiddle with a Dockerfile: you can simply ask the agent to install the packages you need inside the running container — it has sudo access and knows how to install through apt, pip or npm. The downside is that the installs are lost when the container is recreated — your own image makes them permanent.

services:
  xedant_agent_demo: # rename to match your project name
    container_name: xedant_agent_demo # rename to match your project name
    image: registry2.xedant.com/agent:latest
    ports:
      - "5001:80"
    volumes:
      - "./DemoProject:/project" # replace ./DemoProject with your project folder
    environment:
      - AGENT_LOGIN=agent
      - AGENT_PASSWORD=5694d08a2e53ffcae0c3103e5ad6f6076abd960eb1f8a56577040bc1028f702b # SHA256 hash of the password `agent`
      - JWT_SECRET_KEY= # must be a unique, hard-to-guess random string (at least 32 characters). Anyone who knows this key can generate valid authentication tokens. If omitted, the key is generated automatically but is lost when the container is recreated, forcing every user to sign in again
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:80 # port inside the container
      - AGENT_PROJECT_PATH=/project # project path inside the container
      - AGENT_GIT_USER_NAME=User # your name for git commits
      - AGENT_GIT_USER_EMAIL=me@gmail.com # your email for git commits
      - AGENT_GIT_URL=https://github.com/Xedant/DemoProject.git # replace with your project's git URL
      - AGENT_GIT_LOGIN= # your git login
      - AGENT_GIT_PASSWORD= # your personal access key for git
      # optional: internet access through a proxy (for example, in a corporate network)
      # - HTTP_PROXY=http://proxy.company.local:3128
      # - HTTPS_PROXY=http://proxy.company.local:3128
      # - NO_PROXY=localhost,127.0.0.1,.company.local
      # optional: store data in Postgres instead of local SQLite. Separate databases for each of your projects are recommended.
      # - AGENT_DATABASE=Server=postgres;Port=5433;User Id=code;Password=code;Database=code;Pooling=false;Timeout=600;CommandTimeout=600;KeepAlive=600;
      # optional: send chat statistics to ClickHouse for visualization in Grafana
      # - AGENT_CLICKHOUSE_URL=Host=clickhouse;Port=8127;Protocol=http;Database=code;Username=code;Password=code
      # optional: your license key, if you have one
      # - AGENT_LICENSE=
    restart: unless-stopped
    working_dir: /app

This is a complete, ready-to-run example — swap in your project name, folder, git address and credentials. ports are the outer and inner ports: the app opens in the browser on the first, the second is the port inside the container. volumes is the project folder: it is mounted into the container, so all files and the database survive restarts.

If the server reaches the internet through a proxy (typical in a corporate network), add three variables to the container environment: HTTP_PROXY and HTTPS_PROXY — the proxy address for plain and secure connections, and NO_PROXY — the list of addresses that should bypass the proxy (local services, for example). All agent engines receive these variables, so requests to AI providers and tool installs go through the proxy automatically. The full list of variables is on the Models page.

Docker CLI with a .env file

You can also start Xedant Agent with a plain docker run command, moving the environment variables into a .env file. That keeps secrets out of config files and the command line.

Create a .env file next to your project folder:

# .env
AGENT_LOGIN=agent
AGENT_PASSWORD=5694d08a2e53ffcae0c3103e5ad6f6076abd960eb1f8a56577040bc1028f702b
JWT_SECRET_KEY=
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:80
AGENT_PROJECT_PATH=/project
AGENT_GIT_USER_NAME=User
AGENT_GIT_USER_EMAIL=me@gmail.com
AGENT_GIT_URL=https://github.com/Xedant/DemoProject.git
AGENT_GIT_LOGIN=
AGENT_GIT_PASSWORD=
# optional: internet access through a proxy
# HTTP_PROXY=http://proxy.company.local:3128
# HTTPS_PROXY=http://proxy.company.local:3128
# NO_PROXY=localhost,127.0.0.1,.company.local

Then start the container:

docker run -d \
  --name xedant_agent_demo \
  --env-file .env \
  -p 5001:80 \
  -v ./DemoProject:/project \
  --restart unless-stopped \
  -w /app \
  registry2.xedant.com/agent:latest

The --env-file flag reads all variables from the file. Individual values can be overridden with extra -e flags — for example, -e AGENT_LICENSE=your-key.

Automatically generated credentials

If you leave AGENT_LOGIN and AGENT_PASSWORD unset, the app generates temporary credentials at startup: the login is code, and a random password appears in the container console. See it with:

docker logs xedant_agent_demo

These credentials last until the app restarts. The login page shows a notice about the temporary credentials — and a prompt to set permanent ones through environment variables.

Generating the password hash

AGENT_PASSWORD takes not the password itself but its SHA256 hash — a fingerprint of the password that cannot be reversed into the original. Keeping an open-text password in config files is unsafe: one glance at the file is enough to steal it. The login page has a built-in generator: click the “▾ SHA256 generator” link under the sign-in button. It runs entirely on your device: type the password, copy the hash and paste it into your environment configuration.

Security recommendations

The .xedant/models.yml file inside the project is meant for version control — so every installation gets identical settings. Secrets (API keys, license keys and the like) should not be committed: pass them as environment variables in the Docker container and reference them by name with the $VARIABLE_NAME syntax in models.yml. The full list of variables and how they work is on the Models page:

# .xedant/models.yml
environments:
  production:
    variables:
      API_KEY: $MY_API_KEY          # resolved from the container's environment at runtime
      LICENSE_KEY: $MY_LICENSE_KEY   # not committed to git
      PUBLIC_URL: https://example.com # non-sensitive values are fine to commit directly

This way the actual secret values live only in the Docker environment configuration (compose file, .env or -e flags), while models.yml is safe to commit to version control.

Hosting in a subfolder of your site (nginx)

Xedant Agent is a web app, so it can live in a subfolder of an existing site — no separate domain or subdomain required. From any device it opens as usual, and on a phone or desktop it can be installed as an app. The hosting is configured in nginx with reverse proxying into the subfolder:

location /agent/ {
    proxy_pass http://127.0.0.1:5001/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";   # SignalR WebSocket
}

location /api/ {
    proxy_pass http://127.0.0.1:5001;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

The AGENT_BASE_PATH environment variable sets the path prefix for when part of the app’s resources must point at the subfolder. Thanks to it, the same instance can run on a root domain or inside any site.

SSL certificates

Xedant Agent can issue free Let’s Encrypt certificates right from the interface — no certbot and no manual steps. Open the /ssl page in the app, enter your domain and email, and the certificate is obtained automatically. Details are on the SSL Certificates page.