Use in your project

The Convoy dev container is also available as a standalone template you can install into any project — it does not require Convoy. You get Claude Code, Codex CLI, OpenCode CLI, and Cursor CLI preinstalled in an isolated container, with an optional outbound-network firewall (strict / open modes).

Install with the CLI

From your project root:

npx @useconvoy/cli devcontainer

Or, if you already have the CLI installed:

convoy devcontainer

This writes four files into ./.devcontainer/:

• devcontainer.json
• Dockerfile
• init-firewall.sh
• README.md

The command fetches the latest template from GitHub when reachable, and otherwise falls back to the copy bundled with the CLI package. Pass a directory argument to target another project (convoy devcontainer ../other-project) and --force to overwrite an existing .devcontainer/.

If a Convoy CLI profile resolves for the project, the command also prints the exact firewall value to export for strict network mode — CONVEX_DEPLOYMENT=<slug> for Convex cloud backends, or DEVCONTAINER_EXTRA_ALLOWED_DOMAINS=<host> for self-hosted ones — so you don't have to derive it from your backend URL.

Multiple Convoy projects

For a manually managed Linux VM, follow Isolated projects on Linux, including Ubuntu AppArmor setup, project registration, private Codex login and concurrent runs.

The experimental convoy devcontainer <parent-folder> --projects template uses a shared parent workspace with separate project identities and private runtime state. Inside the configured Linux environment, use convoy project add, convoy project list, convoy project remove and convoy connect --profile. convoy project shell <profile> opens the private shell for runtime login.

Each registration needs an API key restricted to that one project. Host runtime authentication is not mounted into these projects. Runtime execution starts disabled until the environment passes its isolation checks. Real runtime, Docker mount and Linux VM acceptance are pending. Follow the generated .devcontainer/README.md for setup, storage requirements and the acceptance procedure. The default single-repository template is unchanged.

Install manually

Copy the files from templates/devcontainer/ in the Convoy repository into a .devcontainer/ folder at your project root.

What's Convoy-specific

Nothing is required. Two things light up automatically for Convoy users:

• ~/.config/convoy is mounted into the container, so CLI profiles and API keys from the host work inside it
• setting CONVEX_DEPLOYMENT on the host adds your Convex backend to the strict-mode firewall allowlist

Everything else — agent installs, shared Codex/OpenCode auth mounts, network modes, DEVCONTAINER_EXTRA_ALLOWED_DOMAINS for your own API endpoints — is generic. The generated .devcontainer/README.md documents all environment variables and modes.

Next steps

• Setup and modes
• Troubleshooting

Browser testing

The updated image includes Chromium and its system libraries. See Browser automation for installation in an existing container, agent scripts and screenshots.