A Snake That Learns: Battlesnake AI with Candle

The game is simple: a snake moves around an 11×11 board, eating food while avoiding walls, its own body, and other snakes. Your server receives the board state and responds with a move. That’s it.

The interesting part is how to decide which move to make. A naive approach works okay — always go toward the nearest food, avoid the nearest wall. But a naive approach dies fast against anything competitive. This tutorial is about building a snake that learns.

We’ll use two tools for this:

Candle is a Rust machine learning library from Hugging Face. It’s lightweight, no Python required, and runs on CPU or GPU. We’ll use it to build the neural network that takes the board state and outputs a move decision.

Battlesnake is the game — it’s a hosted competitive programming game where your server is a web endpoint that gets called every turn. The docs are at docs.battlesnake.com. You don’t need to understand the game deeply to start; we’ll cover the parts that matter.

We start with the board as data and a first network, build a heuristic baseline, then move through imitation learning and reinforcement learning to self-play and deployment. The heuristic from the early parts becomes the foundation for everything that follows — we touch on both imitation learning and reinforcement learning, but always grounded in the concrete problem rather than abstract ML theory.

Version note. This tutorial uses candle-core 0.6 and candle-nn 0.6. Candle is pre-1.0 and the API has changed significantly since 0.6 (the current version is 0.11). The concepts — tensor operations, gradient tracking, training loops, policy gradients — are the same across versions. The specific method names and module paths may differ. If you’re on a newer version, check docs.rs for the current API.

Prerequisites

• Rust (1.70+) — rustup.rs
• mdBook — cargo install mdbook

What we’re building

The project is a Rust workspace with two crates:

battlesnake/           ← workspace root
├── Cargo.toml         ← workspace definition
├── snake-ml/          ← ML library (encoding, network, training)
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs
└── snake-server/       ← HTTP server (serves /move, runs the snake)
    ├── Cargo.toml
    └── src/
        └── main.rs

Every file is created in this tutorial. No external repositories.

Next: Part 1 — Your Snake’s First Move — We start with what Battlesnake sends you and what a move response looks like. No ML yet — enough to have a working web server that the game engine can call.