# docker compose run: One-Off Service Commands

> How docker compose run works: starting a one-off container for a service, --rm, dependencies, and running tests in CI.

Source: https://latchkey.dev/learn/command-reference/docker-compose-run  
Updated: 2026-06-25

Start a fresh one-off container for a service - perfect for test commands.

docker compose run starts a new container for a service to run a one-off command, alongside its dependencies. This page covers --rm, --no-deps, and CI test patterns.

## What it does

docker compose run creates a new container for a service (not the long-running one) to run a command, starting linked dependencies first. It is ideal for tests, migrations, and tasks. --rm cleans up the container afterward.

## Common usage

```Terminal
docker compose run --rm api npm test
docker compose run --rm --no-deps api ./lint
docker compose run -T --rm api ./migrate
```

## Common errors in CI

Unlike up, run does not publish the service ports by default (use --service-ports if you need them). Without --rm, one-off containers accumulate on a runner - always pass --rm in CI. Like exec, run allocates a TTY; pass -T in non-interactive pipelines. The command exit code is the run exit code, so CI can gate on docker compose run --rm api npm test.

## FAQ

### docker compose run: One-Off Service Commands?

docker compose run starts a new container for a service to run a one-off command, alongside its dependencies. This page covers --rm, --no-deps, and CI test patterns.

### What it does?

docker compose run creates a new container for a service (not the long-running one) to run a command, starting linked dependencies first. It is ideal for tests, migrations, and tasks. --rm cleans up the container afterward.

### Common errors in CI?

Unlike up, run does not publish the service ports by default (use --service-ports if you need them). Without --rm, one-off containers accumulate on a runner - always pass --rm in CI. Like exec, run allocates a TTY; pass -T in non-interactive pipelines.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt