Containers

View Source

To isolate the agent environment from your local machine, you can use containers. Because Tidewave runs within your web application, running your app in a container automatically isolates Tidewave as well, this makes Tidewave simpler to containerize than other agents.

One popular solution for this is Visual Studio Code's dev containers. Tidewave works out of the box when using devcontainers. In the section below, we'll be looking at a minimal, devcontainer-like, setup.

Build your own dev container

Windows users

This guide assumes that if you are using Windows, you're also using WSL.

Docker familiarity

This guide assumes some familiarity with using Docker.

When you use another editor than VSCode, you can build a similar experience to devcontainer, with your web app and Tidewave running inside Docker, but your editor on your local machine.

First, because you usally have some external systems you depend on, for example a Postgres database, let's define a docker-compose.dev.yml file inside your project:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: my_app_dev
    volumes:
      - ./db:/var/lib/postgresql/data
    networks:
      - my_app

networks:
  my_app:
    name: my_app

Next, create a new Dockerfile.dev file, which will contain all the tools you need to run your dev server. We have some examples based on your web framework below:

Ruby on Rails

FROM ruby:3.2

RUN apt update && apt -y install git bash inotify-tools socat
RUN <<EOF cat >> /run.sh
#!/bin/sh

socat TCP-LISTEN:3001,fork TCP:localhost:3000 > /dev/null 2>&1 &
socat TCP-LISTEN:localhost:5432,fork TCP:db:5432 > /dev/null 2>&1 &

bash
EOF
RUN chmod +x run.sh

Phoenix

FROM hexpm/elixir:1.18.4-erlang-27.3.4-ubuntu-noble-20250529

RUN mix local.hex --force
RUN mix local.rebar --force

RUN apt update && apt -y install git bash inotify-tools socat
RUN <<EOF cat >> /run.sh
#!/bin/sh

socat TCP-LISTEN:4001,fork TCP:localhost:4000 > /dev/null 2>&1 &
socat TCP-LISTEN:localhost:5432,fork TCP:db:5432 > /dev/null 2>&1 &

bash
EOF
RUN chmod +x run.sh

We install a couple of tools, notably git for fetching git dependencies inside of the container as well as socat. socat is needed to forward traffic to our development server, which by default only listens on localhost. When using Docker's built-in port forwarding this would not work, because Docker accesses the container through a different IP.

You could configure your project to listen on all addresses in development, but this could lead to security issues if you sometimes also run your project outside of Docker. If you are using databases or other resources, such as Redis, you must also forward them. The examples above assume there is a PostgreSQL instance running on port 5421 and therefore we also use socat to forward any traffic from port 5432 to the db container.

To comfortably start the container with all network settings, let's also create a dev.sh script:

#!/bin/sh
docker compose -f docker-compose.dev.yml up -d
docker build -f Dockerfile.dev -t tidewave-devcontainer .
docker run --rm -w $(pwd) \
  -v $(pwd):$(pwd) \
  -p 127.0.0.1:3000:3001 \
  -it tidewave-devcontainer /run.sh

This script starts the compose project and builds our custom container image. Then, it starts an ephemeral dev container, mapping the current working directory.

Also pay close attention to the -p parameter above:

  • This configuration allows you to access your web app in your browser using localhost as usual.

  • We used ports 3000:3001 but you need to adapt them to your web framework (such as 4000:4001 for Phoenix).

  • We only bind to 127.0.0.1 for security purposes. Don't use -p 3000:3001, otherwise anyone on your local network can access your web app and Tidewave.

Compared to VSCode's devcontainers, this setup still runs your editor outside of the container. So while Tidewave will be constrained to the container, any tools your editor might bring to edit files and run terminal commands are still potentially dangerous if you let the agent use those without supervision.

If you prefer to not run your web app on localhost, check the installation steps for each framework on GitHub to learn how to customize them.