# Write a Dockerfile for a Tokio Server

Yes. An agent writes a two-stage Dockerfile for your Tokio server, makes the listener reachable from outside the container, builds and runs it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dockerfile/tokio/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from how the binary is built and started, because a Dockerfile is only that written down. In a Tokio project like tokio-rs/mini-redis, `Cargo.toml` names the package `mini-redis` 0.4.1 on edition 2018 with two `[[bin]]` targets, `mini-redis-server` from `src/bin/server.rs` and `mini-redis-cli` from `src/bin/cli.rs`, and depends on `tokio` 1 with the `full` feature set, `clap` 4.2.7 with `derive`, `tracing` and `tracing-subscriber`. An `otel` feature pulls in four optional OpenTelemetry crates. `Cargo.lock` is committed, `.gitignore` lists only `/target` and `*.rs.bk`, and there is no Dockerfile, no `.dockerignore` and no `rust-version` field, so the agent has to choose a toolchain image itself and says which it chose and why.

Then it reads what the server binds to, which is the part a container breaks. `src/bin/server.rs` parses one `--port` flag with `clap`, falls back to `DEFAULT_PORT` (6379 in `src/lib.rs`), and calls `TcpListener::bind(&format!("127.0.0.1:{port}"))` before handing the listener and `signal::ctrl_c()` to `server::run`. Bound to loopback, the server inside a container answers nobody outside it, and `docker run -p 6379:6379` would connect to nothing. The agent adds a `--host` flag with `127.0.0.1` as its default, mirroring the `--hostname` flag `src/bin/cli.rs` already has, so `cargo run --bin mini-redis-server` behaves as before and only the image passes `--host 0.0.0.0`.

The Dockerfile has two stages. The build stage starts from the official `rust` image, copies `Cargo.toml`, `Cargo.lock` and `src`, and runs `cargo build --release --bin mini-redis-server --bin mini-redis-cli`, so both binaries come out of one compile. The runtime stage is a slim Debian image that copies the two binaries from the build stage, runs as a non-root user, exposes the port, sets `RUST_LOG=info` so the `tracing_subscriber::fmt::try_init()` call in `set_up_logging` prints something useful, and ends with `CMD ["mini-redis-server", "--host", "0.0.0.0"]`. A `HEALTHCHECK` runs `mini-redis-cli ping` against the local port, which is why the CLI binary is in the image too. A `.dockerignore` keeps `target/` and `.git` out of the build context, which otherwise makes every `docker build` ship a local debug build to the daemon.

The sandbox has no Docker, so the agent installs it (`sudo apt-get install -y docker.io`, then starts `dockerd`), builds the image, starts a container with the port published, and checks it the way `README.md` describes checking a local server: `cargo run --bin mini-redis-cli set foo bar` followed by `get foo`. It also runs what `.github/workflows/ci.yml` runs, `cargo build --verbose`, `cargo test --verbose` and `cargo fmt --all --check`, because the new flag touches `server.rs` and the existing tests in `tests/server.rs` and `tests/client.rs` bind their own `127.0.0.1:0` listeners and must stay green. It adds one job to that workflow that builds the image on `ubuntu-latest`, where Docker is already present, so a broken Dockerfile fails a pull request rather than a deploy.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Write a Dockerfile for this Tokio server. Read Cargo.toml, Cargo.lock, README.md, .gitignore, .github/workflows/ci.yml, src/lib.rs, src/bin/server.rs, src/bin/cli.rs and src/server.rs first. The server binds 127.0.0.1 and a hard-coded loopback address is unreachable from outside a container, so add a --host flag to src/bin/server.rs that defaults to 127.0.0.1 and have the image pass 0.0.0.0. Write a two-stage Dockerfile: build both binaries with cargo build --release in the official rust image, copy them into a slim Debian runtime image that runs as a non-root user, exposes the server port, sets RUST_LOG, and declares a HEALTHCHECK that runs mini-redis-cli ping. Add a .dockerignore that excludes target and .git. Docker is not installed here: install docker.io, start dockerd, build the image, run it with the port published and prove a set and get work from the host with mini-redis-cli. Run cargo build --verbose, cargo test --verbose and cargo fmt --all --check as ci.yml does, add a CI job that builds the image, and open a pull request that says which base images you chose and why.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `Dockerfile` and `.dockerignore`, changes `src/bin/server.rs` for the `--host` flag, and adds a job to `.github/workflows/ci.yml`. The description names the two base images, says why the runtime stage is Debian rather than `scratch` (the binary links against the system C library unless built for a musl target, and the agent did not change the target), and states that the default bind address for a local `cargo run` is unchanged.

The run's record holds the `docker build` output, the `docker run` line, the `set` and `get` round trip from the host, and the `cargo test` output, so a reviewer can see the image answered a client before reading a line of the Dockerfile.

Before merging, a reviewer decides whether to pin the `rust` image to a specific version rather than a floating tag, whether to add BuildKit cache mounts for the cargo registry to speed up rebuilds, and whether the `otel` feature should be built into the image or left out; the agent builds without it, as the default feature set does, and says so.

## Run it on every Tokio service without an image

A team with several Rust services starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. Each run installs Docker in its own sandbox and builds its own image, and the pull requests arrive independently.

To keep the image honest afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request changes Cargo.toml, Cargo.lock or the Dockerfile, build the image and comment with the result" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

The bind address is the kind of mistake a Dockerfile written without running it ships every time: the image builds, the container starts, the logs say it is listening, and the first client gets connection refused. The agent runs the container in its own sandbox and talks to it from outside, with Docker installed for that run alone, so the pull request carries a round trip and not a guess.

Every command stays with the run, from the `apt-get install` of Docker to the `cargo test` output, and the pull request can cite them. Doing the same for a dozen Rust services at once costs no more attention than one, because each run has its own machine and its own record.

## Frequently asked questions

### Why change the server code at all for a Dockerfile?

Because `src/bin/server.rs` hard-codes `127.0.0.1` in its `TcpListener::bind` call. Inside a container that address is the container's own loopback, so a published port forwards to nothing. A `--host` flag with the old default keeps local runs identical and lets the image bind `0.0.0.0`; the alternative, `--network host`, is a workaround the reader would have to remember every time.

### Why not a scratch image?

The default `x86_64-unknown-linux-gnu` target produces a binary that needs the system C library at run time, which `scratch` lacks. Building for `x86_64-unknown-linux-musl` would allow it, but that changes the build target for the whole project. The agent uses a slim Debian base and names the musl option in the pull request for the reviewer to pick.

### Does this build the otel feature?

No. `cargo build --release` without `--features otel` leaves the four OpenTelemetry crates out, matching the default feature set `.github/workflows/ci.yml` builds first. A build argument can turn it on later; the agent leaves the choice to the reviewer rather than adding an exporter the service has nowhere to send to.

### Does the agent need Docker in the sandbox?

It is not there by default, so the run installs the `docker.io` package and starts `dockerd` before building. That install is part of the run's record. The CI job it adds runs on GitHub's `ubuntu-latest`, which already has Docker, so nothing extra is installed there.

## More Tokio jobs

- [Add Fuzz Tests to a Tokio Protocol Parser](https://getrush.ai/run/add-fuzz-tests/tokio/)
- [Add Graceful Shutdown on SIGTERM to a Tokio Server](https://getrush.ai/run/add-graceful-shutdown/tokio/)
- [Add an MSRV Check to a Tokio Project](https://getrush.ai/run/add-msrv-check/tokio/)

## The same job on other stacks

- [Add a Dockerfile to a tRPC Next.js App](https://getrush.ai/run/add-dockerfile/trpc/)
- [Add a Dockerfile to an AdonisJS App](https://getrush.ai/run/add-dockerfile/adonisjs/)
- [Add a Dockerfile to an aiohttp App](https://getrush.ai/run/add-dockerfile/aiohttp/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
