Skip to main content

Develop in a Devcontainer

The Framework M devcontainer is a zero-config environment for Framework M development. It bundles Python, Node, PostgreSQL, Redis, and NATS, so you do not need to install the services locally.

This page covers opening the environment with either VS Code Dev Containers or Devsy. For creating and running an app, follow Getting Started.

What you get​

ComponentDetails
Python3.12 with uv and the m CLI linked
Node24 with pnpm
PostgreSQL16 (db service)
Redis7 (redis service)
NATS2 (nats service)
Ports8000 (m prod), 8888 API, 5173 Vite, 9999 Studio
VS CodePython, Pylance, Prettier, ESLint

The devcontainer runs in enterprise mode: DATABASE_URL, REDIS_URL, and NATS_URL point at the bundled services.

Database note: the container uses PostgreSQL, not SQLite. When following Getting Started, skip its SQLite .env step and use a Postgres + server extra (for example [server-granian,postgres]) plus psycopg2-binary for migrate sync/all. The container's DATABASE_URL is already set.

Option 1 — VS Code Dev Containers extension​

Prerequisites​

Open the container​

  1. Clone the devcontainer repository and open it in VS Code:

    git clone https://github.com/framework-m/framework-m-devcontainer.git
    cd framework-m-devcontainer
    code .

  2. Open the Command Palette (Ctrl/Cmd + Shift + P) and run:

    Dev Containers: Reopen in Container

    VS Code builds the Compose stack, runs postCreateCommand (uv sync), and links the m CLI.

  3. Wait for the build to finish. The first build takes longer because it downloads the base image and installs Python, Node, and pnpm.

  4. Verify the environment:

    m --version
    uv --version
    node --version
    pnpm --version

  5. Open the Ports panel. The container forwards:

    PortService
    8000m prod
    8888Framework M API (m dev)
    5173Vite frontend
    9999Studio UI

Next: follow Getting Started to create an app. The container root is already a uv project with framework-m and framework-m-studio, so skip Getting Started's initial uv init/uv add steps and start at creating the app. The container already sets DATABASE_URL, REDIS_URL, and NATS_URL; do not add a SQLite .env unless you intentionally want to switch.

Option 2 — Devsy​

Devsy is a community fork of DevPod. It runs the same .devcontainer/devcontainer.json on local Docker, a remote host, Kubernetes, or a cloud machine. Use the desktop app for everyday work or the CLI for automation.

Desktop​

  1. Install Devsy Desktop for your platform.

  2. Open Providers and click + Add. Choose Docker, then Add Provider.

  3. Open Workspaces and click + Create. The wizard has five steps:

    • Provider: select the Docker provider.
    • Source: enter https://github.com/framework-m/framework-m-devcontainer.
    • IDE: choose VS Code (Remote - SSH), VS Code Browser, or None.
    • Review: check the workspace name and configuration.
    • Launch: Devsy builds the devcontainer and opens your IDE.

  4. If you chose None, connect over SSH:

    ssh <workspace>.devsy

    Devsy adds a <workspace>.devsy entry to ~/.ssh/config.

CLI​

Install the CLI and start the same workspace from a terminal:

curl -L https://devsy.sh/install.sh | sh

devsy provider add docker
devsy workspace up github.com/framework-m/framework-m-devcontainer --ide vscode

Use --ide openvscode for VS Code in the browser, or --ide none for SSH only. Add --id framework-dev to give the workspace a stable name.

Ports​

The devcontainer declares 8000, 8888, 5173, and 9999. Use your editor's Ports panel to open them. If you connect over plain SSH, forward them manually:

ssh -L 8000:localhost:8000 \
    -L 8888:localhost:8888 \
    -L 5173:localhost:5173 \
    -L 9999:localhost:9999 \
    <workspace>.devsy

Next: follow Getting Started. As with VS Code, skip the initial project-setup steps because the container is already configured.

MCP server​

Devsy exposes workspace control to MCP-capable AI clients:

devsy mcp serve

Configure the client to launch that command. A typical configuration:

{
  "mcpServers": {
    "devsy": {
      "command": "devsy",
      "args": ["mcp", "serve"]
    }
  }
}

Available tools:

  • workspace_list, workspace_status, workspace_create, workspace_start, workspace_stop, workspace_delete
  • workspace_exec — run a one-shot command in a running workspace
  • provider_list, provider_add, provider_delete, provider_use

workspace_status returns the saved configuration, not whether the workspace is running. Use devsy workspace status <name> --result-format json for live state.

workspace_exec is bounded by devsy mcp serve flags: --exec-timeout-default (5m), --exec-timeout-max (30m), --exec-output-cap (100 KiB per stream), and --mcp-max-concurrent-ops (8).

The MCP server has the same authority as your local Devsy CLI: it can create/delete workspaces, run commands, and manage providers. Only connect clients you trust.

Agent skill​

Devsy also publishes an agent skill that teaches an agent how to choose workspaces and providers, run commands, and recover from timeouts:

npx skills add devsy-org/devsy --skill devsy

Add -g to install it for all projects, or --agent to target a specific agent. The skill requires Node.js for npx. Installing the skill is separate from running the MCP server; configure both independently.

Notes​

  • Rebuild the container after changing .devcontainer/:
    • VS Code: Dev Containers: Rebuild Container
    • Devsy: devsy workspace up <workspace> --recreate
  • If a port is not reachable, check the editor's Ports panel or use the SSH forwarding command above.
  • The devcontainer repository's README is intentionally minimal and links back here and to Getting Started.