For the complete documentation index, see llms.txt.
Skip to main content

Docker Compose

Learn how to run reShapr locally using Docker Compose for development and testing purposes.

Prerequisites​

Before you begin, make sure you have the following installed on your machine:

  • Docker (with Docker Compose v2)
  • Node.js (v18 or later) needed for the reShapr CLI
  • The reShapr CLI installed globally:
npm install -g @reshapr/reshapr-cli

Quick start with the CLI​

The simplest way to run reShapr locally is through the reshapr run command. It automatically downloads the correct Docker Compose file from GitHub, configures the container images for the requested release, and starts everything in the background.

reshapr run
ℹī¸  Resolved 'latest' to release '0.0.10'.
ℹī¸  Downloading compose file from https://raw.githubusercontent.com/reshaprio/reshapr/refs/tags/0.0.10/install/docker-compose-all-in-one.yml...
✅ Compose file saved to /Users/you/.reshapr/docker-compose-0.0.10.yml
ℹī¸  Starting Reshapr containers (release: 0.0.10)...
✅ Reshapr containers started successfully.

By default this pulls the latest stable release. You can also target a specific release or use the nightly build:

Run a specific release:

reshapr run --release 0.0.10

Run the nightly build (latest from main branch):

reshapr run --release nightly

The compose file is cached at ~/.reshapr/docker-compose-<release>.yml, so subsequent runs reuse it without re-downloading.

Check status​

Once the containers are running, verify their status:

reshapr status
ℹī¸  Reshapr containers (release: 0.0.10, started at: 2026-04-01T10:30:00.000Z)
NAME                           IMAGE                                        ...   STATUS
reshapr-ctrl-1                 registry.reshapr.io/reshapr/reshapr-ctrl:0.0.10           ...   Up 2 minutes
reshapr-proxy-1                registry.reshapr.io/reshapr/reshapr-proxy:0.0.10          ...   Up 2 minutes
reshapr-db-1                   postgres:17                                  ...   Up 2 minutes

The control plane is available at http://localhost:5555 and the MCP gateway at http://localhost:7777.

Log in with the CLI​

With your user created, authenticate the CLI against your local control plane:

reshapr login --server http://localhost:5555

You'll be prompted for your username and password. Once authenticated:

info

The default username is admin, and the default password is password.

reshapr login --server http://localhost:5555
ℹī¸  Enter your credentials
✅ Login successful!
ℹī¸  Welcome, admin!
ℹī¸  Organization: reshapr
✅ Configuration saved to /Users/you/.reshapr/config

From here, you can follow the Getting Started tutorial to import services, create configuration plans, and expose MCP endpoints just point everything at your local instance.

Stop the containers​

When you're done, shut everything down:

reshapr stop
ℹī¸  Stopping Reshapr containers (release: 0.0.10)...
✅ Reshapr containers stopped successfully.

This runs docker compose down on the saved compose file and cleans up the run state.

Manual setup (without the CLI)​

If you prefer to manage Docker Compose directly, clone the reShapr repository and use the provided scripts:

git clone https://github.com/reshaprio/reshapr.git
cd reshapr/install

Start all services (control plane, gateway, and database) at once:

docker compose -f docker-compose-all-in-one.yml up

The install/ folder also includes helper scripts:

  • start-all.sh- a simple script to run the docker compose command above

Or start components separately, the control plane first:

docker compose up

Then the gateway proxy in a separate terminal:

docker run -it --rm -p 7777:7777 \
  -e RESHAPR_CTRL_HOST=host.docker.internal \
  --add-host=host.docker.internal:host-gateway \
  registry.reshapr.io/reshapr/reshapr-proxy:nightly

The install/ folder also includes helper scripts:

  • start-control-plane.sh - a simple script to run the docker compose command above
  • start-proxy.sh - a simple script to run the docker run command above
info

The host.docker.internal mapping lets the proxy container reach the control plane running on your host machine.

Next steps​

Agent View