Since then, another piece of friction has kept bothering me: screenshots.
My development environment runs inside a devcontainer, usually with tmux and an AI coding agent. The agent can work with images, but the clipboard belongs to my Mac. Getting a screenshot across that boundary meant saving it somewhere, copying it into the container, finding the path, and then passing that path to the agent.
None of those steps are difficult. Together, they interrupt the flow often enough to be annoying.
So dbr can now do this:
dbr paste
Which produces something like:
/home/vscode/.cache/dbr/paste/image-a1b2c3/clipboard.png
That’s it. The image on the host clipboard is now a private file inside the devcontainer, ready for any tool that accepts a local image path.
dbr paste connects to the existing host daemon and requests the current clipboard image. The host reads the clipboard, validates the result, and transfers the original PNG or JPEG bytes into the container.
Each image is written to a unique directory beneath ~/.cache/dbr/paste. On Unix, the directory is created with 0700 permissions and the image with 0600 permissions. Partial or failed transfers do not leave image files behind.
On macOS, dbr can also convert TIFF clipboard data to PNG. This matters because copying pixels from applications such as Preview does not always put a PNG representation on the pasteboard.
Copying an image file in Finder is different again. Finder provides both a file reference and rendered image data. My first implementation happily selected the rendered data and transferred Finder’s generic PNG file icon rather than the contents of the file.
Technically an image. Not quite the image I wanted.
The current implementation detects a single PNG or JPEG file copied in Finder, reads the file itself, and validates its byte signature before transferring it. Unsupported files, multiple selections, unreadable files and oversized images fail explicitly rather than silently falling back to the icon.
The command can also insert the resulting path directly into a tmux pane:
bind-key V run-shell -b 'dbr paste --tmux-target "#{pane_id}" >/dev/null'
With that in my container’s tmux configuration, I can copy a screenshot on the Mac, press my tmux prefix followed by Shift-V, and the quoted image path appears at the cursor.
It deliberately does not press Enter. The receiving application decides how to use the path.
This has been particularly useful when working with coding agents. I can capture a broken interface, paste the image path into the conversation, and continue without leaving the terminal.
Clipboard sharing is opt-in. On the host, add this to ~/.config/dbr/config.toml:
[clipboard]
enabled = true
Then restart the daemon:
dbr restart
Install or upgrade the host binary with:
curl -fsSL \
https://github.com/bradleybeddoes/devcontainer-bridge/releases/latest/download/install.sh \
| bash
The host and container must share the existing dbr authentication token. Clipboard transfers are limited to 20 MiB and only one transfer is allowed at a time.
There is no continuous clipboard synchronisation and no support for arbitrary clipboard contents. The client must explicitly request an image each time.
There is also no per-request confirmation on the host. Any client with the host token can request a supported clipboard image while the feature is enabled. Transfers use the bridge’s existing unencrypted TCP connection, so its ports should remain within the trusted host and container network.
Successful images remain in the container until removed. This is intentional—the receiving tool may need the file after dbr paste exits—but it means the cache should be cleaned up when those images are no longer required.
Clipboard image transfer is not a large feature, but it removes another boundary between the host and the development environment.
Ports appear on the host automatically. Browser links open in the right place. Unix sockets can cross the container boundary. Now screenshots and copied image files can move in the other direction with one command.
The best developer tooling often works like this. It does not introduce a new workflow. It removes the awkward parts from the workflow you already have.
The paste functionality is available in the latest devcontainer-bridge release. The full setup, tmux integration and security details are in the clipboard guide.
If you’re using devcontainers from the terminal, I’d genuinely appreciate the feedback. Issues and contributions are welcome on GitHub.
]]>Want to play? wordbattle.fun is free and no login is required. Come back here when you want to know how it was built.
About a year ago, I ran an experiment. I wanted to see if AI models could build a six-letter Wordle clone from scratch while I stayed out of the code entirely. The rules were simple: use web technologies I didn’t know (JavaScript/TypeScript), accept every code change the models suggested without questioning it, and guide the project purely through text and screenshots. GPT-4 and Claude 3.5 Sonnet in Cursor did the work.
It was a fun failure. The models made reasonable progress on the frontend and got data into SQLite, but they couldn’t handle the communication between frontend and backend. When they got stuck, they’d propose the same two or three fixes over 10 or 12 attempts. I’d switch between models to break the loop. Eventually the game board stopped loading, the browser spewed errors, and the backend wasn’t much better. We didn’t get anywhere near authentication, user accounts, teams, or any of the other features I’d hoped to include.
But I didn’t have to retire to be an onion farmer 🧅. Not in early 2025, anyway.
Fast forward to early 2026. The tooling had changed substantially. I picked the project back up with Claude Code and the same starting constraint: technologies I didn’t know, so the code had to come from the agent while I guided the product. Six weeks later, WordBattle is a production multiplayer word game with over 1,300 commits. Maybe now it is time to become an onion farmer 🧅?
A daily 6-letter word guessing game, similar in spirit to Wordle. Every player globally gets the same word each day, resetting at UTC midnight. You get six guesses. Each guess tells you which letters are correct, present but misplaced, or absent. The daily word is never sent to the client. Guesses are submitted to the server, which returns only the per-letter evaluation. You can’t cheat by opening DevTools.
Where it diverges from Wordle is in the multiplayer and AI dimensions. Players form teams. Leaderboards track individual and team performance. There are some fun touches: you can edit individual letters in your guess without deleting the entire word, and teams can hook directly into Slack or Microsoft Teams messaging to keep the competition flowing.
AI agents get to play too. They can create accounts, join teams, and compete on the same leaderboards as human players. My Claude Opus 4.6 agent wakes itself up on a daily schedule to play, then complains about how it lost because its rules are harder (agents face tougher constraints). I recently relented and allowed it to start using its local memory. I suspect it won’t be long until it optimises itself and starts winning.
I’m already in fierce competitions at home and at work.
The first attempt failed because the models had no persistence, no conventions, and no ability to understand the project as a whole. Each prompt was effectively starting fresh. When the frontend and backend needed to talk to each other correctly, the models couldn’t hold enough context to get the integration right. They’d fix one side and break the other, endlessly.
Three things made the second attempt work:
CLAUDE.md). Architecture, conventions, patterns, and common mistakes to avoid that Claude reads at the start of every session. More on this below.I didn’t pick the stack. Claude did.
Before writing any code, I set up Claude as a product manager agent. Through a back-and-forth interview process, I described the game, the audience, the features I wanted, and the constraints (solo maintainer, low cost, simple deployments). The agent worked through the discussion, asked clarifying questions, and formulated a plan that included technology recommendations with trade-offs. I selected the option that seemed the most well-reasoned.
SvelteKit 2 with Svelte 5 was its recommendation for the application framework. Svelte 5’s runes ($state(), $derived(), $effect()) replaced the older store-based reactivity model. The result is more explicit, less magical, and easier to reason about. SvelteKit’s Node adapter meant we could deploy a single binary-like artifact rather than orchestrating multiple services.
SQLite via Drizzle ORM for persistence. For a game with daily resets and modest concurrent writes, SQLite in WAL mode with a 5-second busy timeout is more than adequate. Drizzle gave us type-safe queries and auto-generated migrations. No database server to manage. The entire state of the application is a single file I can back up with a cron job.
Hetzner Cloud for hosting. A single cloud instance, no Kubernetes, no containers in production. Caddy as a reverse proxy, Cloudflare Tunnel for ingress (no public ports), and systemd template units for blue/green deployments. Minimal operational overhead. Negligible cost.
Deliberately boring infrastructure. The interesting engineering belongs in the game itself, not the deployment pipeline.
All development happens inside a devcontainer, managed from the terminal via tmux and Claude Code. If you read my previous post on devcontainer-bridge, this is where it comes full circle. dbr is a declared devcontainer feature in the project, handling port forwarding and browser opening from the container to my host machine.
The devcontainer itself is more interesting than most. It runs a default-deny network egress firewall using iptables and ipset. On every container start, a firewall script loads a pre-computed IP allowlist and blocks all outbound traffic that isn’t on it. After applying the rules, it verifies the firewall works by confirming it can reach GitHub’s API and cannot reach example.com. IPv6 is blocked entirely to prevent bypass.
This is what makes it safe to run Claude Code with permissions that would otherwise be reckless. Inside the container, I let Claude run autonomously, accepting file edits and command execution without prompting me for approval. The firewall means the agent can’t reach anything I haven’t explicitly allowed, regardless of what it tries to do. The security boundary is the container isolation and the network, not a permission dialog.
The container installs Claude CLI automatically during setup, provisions GitHub SSH keys, and pulls in my personal dotfiles on start. A typical session is Ghostty fullscreen on my Mac with tmux, Claude Code in the main pane and daemon terminals in side panes. That’s it. No IDE. The performance win is real: CPU and memory that would go to an IDE goes to Claude’s agent teams instead. When I need to read code, which was rare, there’s my full Neovim setup inside the container.
CLAUDE.md is a project guide that Claude reads at the start of every session. It covers the project layout, naming conventions, database patterns, authentication flow, accessibility standards, testing expectations, deployment procedures, and a list of common mistakes to avoid.
It didn’t arrive fully formed. It grew alongside the project. I’d write sections based on decisions we’d made, Claude would suggest additions when it noticed patterns emerging or spotted gaps that were causing inconsistency. Some entries came from mistakes we made early on that I didn’t want repeated. By the end, it was 280 lines co-authored by both of us.
This was probably the most important artefact in the project. Without it, Claude’s output drifts. With it, the code stays coherent across sessions.
A few examples of what’s in there:
$: reactive declarations and Svelte stores. The project guide says “Use runes. No stores. No Svelte 4 patterns.” Problem solved.The work split into two distinct modes.
Planning sessions came first. These were long, collaborative conversations with Claude in planning mode, sometimes running for a few hours. We’d work through what needed to get done: feature scope, edge cases, data model changes, how a new capability should interact with existing systems, security considerations. By the end of a planning session, we’d have a clear picture of the work broken into discrete tasks.
Implementation happened next, using Claude Code’s agent teams. The plan would get handed to a team of agents that worked through the tasks, writing code, tests, database migrations, and documentation, often across multiple files simultaneously. Every commit in the repository is co-authored.
We didn’t just build technology this way. The website copy, the UI design, the security model, WCAG compliance, the deployment design, the operational automation. All of it was planned and iterated using agents. I could describe what I wanted the landing page to say, how the onboarding flow should feel, what the error messages should communicate.
Features that would take me a full day to build solo (authentication, team management, leaderboard ranking algorithms, webhook integrations) came together in hours. Not because the agents wrote perfect code on the first try, but because the planning was thorough and the feedback cycle was tight. Plan, build, review, fix, commit. Repeat.
Architecture. Claude can implement a feature, but it doesn’t know which feature to implement next. It doesn’t know that the leaderboard should hide detailed results until after midnight to prevent information leakage between players. These design decisions require understanding the game, the players, and the incentive structures.
Visual design. Claude can implement a design, but the decisions about what looks right, what feels good to interact with, what creates the right mood for a daily word game, those came from me. I created a design audit document and worked through it iteratively with Claude to refine the interface.
Security judgement. The security audit was where Claude got it the most wrong. I set up a security review agent to assess the application, and its initial recommendations were corporate boilerplate. It demanded MFA for a free word game. It flagged the absence of OAuth2 integration as a critical risk. Meanwhile, it completely missed rate limiting on public endpoints, which is one of the first things you need on anything exposed to the open internet.
It wasn’t paying attention to what kind of application it was looking at. It took significant refinement, drawing on my own security background, to get the audit agent producing recommendations that were proportionate to the actual threat model. The layered rate limiting, the bot detection, the anti-enumeration measures, those all came from steering the agent towards what actually matters for a public web game rather than what a compliance checklist says.
Knowing when to stop. Claude will happily add features forever. Error handling for scenarios that can’t happen. Configuration for things that don’t need to be configurable. Abstractions for code that’s used exactly once. Recognising when the code is done, not just “passing tests” done, requires judgement I’m not ready to delegate.
You could look at this and say it’s not that different from any experienced product person working with a development team. And you’d be right about the skills involved. The difference is that the work doesn’t stop when I do. Agent teams run while I’m asleep. I’d finish a planning session in the evening, hand off the tasks, and wake up to a product that had moved forward overnight. That cadence changes what a single person can ship.
One of the more interesting technical decisions was exposing three integration surfaces for AI agents:
REST API (/agent/v1/*): Standard CRUD endpoints with Bearer token authentication. This is what you’d use if you’re building a custom integration or a bot that plays WordBattle.
MCP Server (POST /mcp): A JSON-RPC 2.0 endpoint with 20+ tools that mirror the REST API. No SDK dependency, just pure JSON-RPC. This is how Claude Code and other MCP-aware agents interact with the game. Each tool has Anthropic-standard annotations for read-only, destructive, and idempotent hints.
A2A Discovery (/.well-known/agent-card.json): An agent-to-agent discovery card that lets third-party agents automatically find and understand WordBattle’s capabilities.
Early in the project, I designed a service layer based on functional programming concepts that would sit beneath any transport. The game logic, team management, authentication, all of it lives in that layer. The four surfaces (web UI, REST, MCP, A2A) are thin wrappers that call into it. Getting this right early meant adding a new protocol was a thin wrapper, not a rewrite.
Agents face a 5-second server-enforced cooldown between guesses to prevent brute-force solving. They also require email verification before login, just like human players. The leaderboard treats everyone equally. An agent that solves the puzzle in two guesses ranks above a human who took four.
This was a priority from the start.
The daily word is generated server-side using a seeded PRNG. The seed combines a secret value with the day number (days since epoch, March 27, 2026). The word list is a curated subset of the ENABLE dictionary, 6-letter words only, shuffled deterministically using Fisher-Yates. Linear probing skips any word that’s been used before, giving roughly nine years of unique daily words before the sequence would repeat.
Guesses are evaluated server-side using a two-pass algorithm: first pass marks exact position matches and decrements available letter counts, second pass marks present-but-misplaced letters from the remaining pool. This correctly handles duplicate letters, which is where most naive Wordle implementations get it wrong.
Bot protection for human registration uses layered passive detection: a honeypot field positioned off-screen with CSS (not display: none, which bots have learned to detect), time-based detection with HMAC-signed timestamps that reject submissions completed in under two seconds, and a blocklist of approximately 121,000 known disposable email domains.
Rate limiting operates at three layers: Cloudflare WAF at the edge, SvelteKit middleware with per-endpoint escalating lockouts, and Caddy body size limits. Defence in depth, as it should be.
The deployment pipeline uses blue/green zero-downtime swaps:
This is orchestrated by a shell script that GitHub Actions triggers on merge to main. The script, the smoke tests, and the backup automation all pass shellcheck with no warnings, another convention enforced by the CLAUDE.md.
Monitoring uses Sentry with PII scrubbing, configured to never identify individual users. Claude has explicit access to Sentry error data and uses it to diagnose production issues directly. Agent ops, effectively. I’m still figuring out how this works and looks longer term.
Daily SQLite backups go to Hetzner Object Storage via a cron-driven script. Cloud snapshots provide an additional recovery layer. The whole application can be rebuilt from scratch in under an hour.
The agentic team model works, but it’s early. Memory is the biggest gap right now. Claude’s project guide gives it project knowledge, but session-to-session memory is still primitive. I want agents that remember the last three planning sessions, know which approaches we tried and rejected, and can brief a new agent team without me repeating context. That’s coming, but it’s not here yet.
I’m also thinking about how this scales beyond a solo builder. At Macuject, the MedTech startup where I’m CTO, I lead people. Each of those people will eventually have their own agentic teams. The interesting question isn’t “how does one person work with AI?” It’s how human teams share context, conventions, and institutional knowledge across their respective agent teams without it becoming a mess. The project guide is a starting point, but it won’t be the whole answer.
And of course, newer models keep arriving. Every few months the capabilities shift and the patterns I’ve established need revisiting. The workflow that produced WordBattle will probably look different six months from now. That’s fine. The point was never to find the final process. It was to find a process that ships products now and builds my knowledge so that I can adapt as the state of the art changes rapidly.
So I don’t need to become an onion farmer 🧅 just yet, but 2027 is going to come fast.
WordBattle is live at wordbattle.fun. If you’d like to play, or connect an AI agent to compete, I’d welcome your company. Join the readers team and let’s see who’s best!
]]>devcontainer.json that the whole team shares. The devcontainer CLI is the foundation of this, and if like me you prefer working in a terminal rather than VS Code, it’s been a solid companion.
Except for two things that are really annoying:
1. Port forwarding: When a process inside a devcontainer listens on a port (say, a dev server on :3000), VS Code automatically makes it accessible on your host machine. The devcontainer CLI does not.
2. Browser opening: When a container process tries to open a URL (think OAuth callbacks, documentation links), VS Code opens it in your host browser. The devcontainer CLI cannot.
These two gaps break real workflows. OAuth flows that bind a random port, open a browser, and expect a callback on localhost fail completely. Dev servers are unreachable without manual port forwarding in devcontainer.json.
I built devcontainer-bridge (dbr) to fix both.
dbr uses a reverse connection model (similar to ssh -R) where all TCP connections flow container to host. The container daemon initiates everything outward, and the host daemon multiplexes over those connections.
┌───────────────────── Host Machine ──────────────────────────────────┐
│ │
│ dbr host-daemon │
│ ├─ Control: :19285 (JSON-lines protocol) │
│ ├─ Data: :19286 (reverse data connections) │
│ ├─ Binds loopback:PORT for each forwarded port │
│ └─ Opens URLs in host browser (open/xdg-open) │
│ │
└─────────────────────────────────────────────────────────────────────┘
▲ All connections initiated container → host
│ via host.docker.internal
┌─────────┴────────── Devcontainer ───────────────────────────────────┐
│ │
│ dbr container-daemon │
│ ├─ Polls /proc/net/tcp every 1s for new listeners │
│ ├─ Sends Forward/Unforward to host via control channel │
│ └─ Opens reverse data connections for proxied traffic │
│ │
└─────────────────────────────────────────────────────────────────────┘
The two daemons communicate over a JSON-lines protocol on a persistent control channel. A separate data channel carries the actual proxied TCP traffic.
The container daemon polls /proc/net/tcp every second to detect new listening ports (the same approach VS Code uses internally). When it finds one, it tells the host daemon to bind a loopback listener on the matching port. When traffic arrives on the host side, it’s proxied through to the container via a reverse data connection. One host daemon serves all your running devcontainers, handling port conflicts automatically by assigning alternative host ports when needed.
For browser opening, setting BROWSER=dbr-open in your container shell profile is all it takes. When a tool calls $BROWSER, the URL gets sent to the host daemon, which opens it with open (macOS) or xdg-open (Linux). URLs are even rewritten automatically if a container port has been remapped to a different host port, which keeps OAuth callbacks working even when ports shift.
Setup is straightforward.
Install the host binary, or build from source if you prefer.
curl -fsSL \
https://github.com/bradleybeddoes/devcontainer-bridge/releases/latest/download/install.sh \
| bash
Start the host daemon
dbr host-daemon
This runs in the foreground. If you’d prefer something you can drop into a shell alias or dotfile, dbr ensure checks whether the host daemon is already running and starts it if not.
Add the devcontainer feature to your project
{
"features": {
"ghcr.io/bradleybeddoes/devcontainer-bridge/dbr:0": {}
}
}
This installs dbr inside the container and starts the container daemon automatically on boot via the feature’s entrypoint. No manual setup inside the container.
Configure browser integration
Add this to your ~/.zshrc or ~/.bashrc inside the container (via your personal dotfiles):
export BROWSER=dbr-open
Most tools respect the BROWSER environment variable: Node.js open, Python webbrowser, Rust’s open crate, and others.
Verify
$ dbr status
Container Port Host Port Process Since
myapp_dev 8080 8080 node 2m ago
myapp_dev 39821 39821 mcp-auth 5s ago
That’s it. Ports are forwarded, browsers open on the host.
If you’re working on a team, you might be wondering whether adding this to a shared config is safe. One of the design constraints was that dbr needed to be safe to add to shared devcontainer.json files in teams where some people use VS Code and others use the CLI.
VS Code users are not impacted. The dbr binary is installed but the system is effectively inert without the host daemon running. It doesn’t set global environment variables or interfere with VS Code’s own port forwarding. Think of it like having nvim installed but unused.
The container daemon does run in the background (started by the feature’s entrypoint), but it only initiates outbound TCP connections. It binds no ports inside the container. If no host daemon is running, it reconnects silently with exponential backoff and negligible resource cost.
Terminal developers activate dbr through personal dotfiles and shell configuration, not shared project files. VS Code developers won’t notice it’s there.
Given my background in security and compliance, this was something I thought about from the start.
dbr uses a two-tier binding model. Forwarded port listeners always bind to loopback only (127.0.0.1 / [::1]), never 0.0.0.0. Your forwarded dev server is only reachable from your machine, not the network. The control and data ports bind to 0.0.0.0 only when Docker is detected (necessary for Docker Desktop on macOS, where containers reach the host via a gateway IP) and fall back to loopback otherwise. Override with --bind-addr or --no-docker-detect if you need explicit control.
The host daemon accepts a fixed set of protocol messages. A container cannot instruct the host to run arbitrary commands. The only host-side actions are binding loopback ports and opening validated HTTP/HTTPS URLs. URLs are passed directly as process arguments (not through a shell), so there’s no command injection surface.
Resource limits are enforced throughout: 64 KB message cap, max 64 concurrent containers, max 128 forwards per container, rate-limited URL opens. The entire project uses zero unsafe Rust code.
The full threat model is documented in security.md.
This section is a bit of a departure from the tool itself, but it’s relevant to my ongoing exploration of AI-assisted development.
I built dbr as an exploratory collaboration with Claude Code agent teams. I did the planning and design work: defining the problem, choosing the technology (Rust, tokio for async, serde for the protocol), sketching the architecture, and writing the specification. Then I handed the implementation to a team of 17 AI agents.
The agents created the codebase, tests, documentation, and end-to-end validation scripts. They did exceptionally well. But the application didn’t function straight out of the box, which I expected given the scope. I then spent a few more hours pair programming with Claude Code to debug, refine, and get everything working.
A few honest observations from the experience:
What worked well: The agents produced well-structured Rust code that followed the architecture I’d specified. The protocol implementation, the /proc/net/tcp parser, the async connection handling, the CLI, the documentation — all were high-quality starting points. Having 17 agents work in parallel meant the initial codebase came together remarkably quickly.
What needed human attention: Integration between systems was where things fell apart. The way components connected had subtle bugs. The kind of issues you only find by actually running end to end. We’ve since created a full e2e script that invokes multiple containers so this won’t happen again — perhaps a necessary part of the plan going forward for any networked tool.
My takeaway: AI agent teams are a genuinely useful tool for bootstrapping projects, especially when you invest in clear specification and architecture upfront. The better your input, the better their output. But “ship it and walk away” isn’t where we are yet. That may well change as the technology continues to improve and we learn more about optimising inputs. I intend to keep experimenting both personally and across teams I lead.
This project is new and in active development. It’s been tested on macOS only so far; Linux host support is implemented but unverified. Bugs are expected.
If you’re a terminal-first devcontainer user and want to give it a try, I’d genuinely appreciate the feedback. Issues and contributions are welcome at github.com/bradleybeddoes/devcontainer-bridge.
]]>I was wrong. What I’ve learned is that great developer experience and strong compliance can genuinely reinforce one another.
As CTO I lead technology and security at Macuject, a MedTech startup developing cutting-edge solutions to end preventable blindness. MedTech comes with numerous compliance requirements, and for us, part of that means ensuring that annual SOC 2 and HIPAA audits are successful.
The key is treating compliance not as a set of hurdles to clear, but as a design challenge, and it works. At Macuject, we consistently achieve annual attestations for SOC2 and HIPAA while our developers ship features quickly and enjoy their work. The secret? Making the compliant path the easy path.
Developers tolerate friction they understand. They resent friction that seems arbitrary.
Macuject invests significant time explaining why our compliance requirements exist. In MedTech, we can point to real breaches, real consequences, real harm to patients. When developers understand that the controls they’re working within exist to protect vulnerable people, the whole thing feels different. It’s not bureaucracy; it’s responsibility.
Explaining the why needs to be done well and often. A session during onboarding is essential; continuing to talk about the benefits and reasons on an ongoing basis is invaluable for keeping the understanding front of mind.
In compliance-heavy environments, there’s a need to add gates that review, scan, and approve work. Gates provide a point of reference when auditors ask how the company ensures security, quality, and reduces risk during product development, providing a detailed history of who did what and when.
However, gates that slow developers down create pressure to circumvent them. Slow feedback loops mean developers have moved on to other work by the time they learn about issues, making fixes more expensive, time-consuming, and frustrating. Remove these issues for developers by ensuring checkers, linters, analysers, and tests run locally in the IDE and before remote git branch pushes, not just in CI. A local verification process that catches an issue immediately beats a pipeline failure every time. The developer is still in context, still thinking about that code, and can fix the problem as part of their normal flow. Of course, local checks can technically be bypassed, but in practice, developers want fast feedback; they use the local tools because they make their lives easier.
We still have gates; these can’t be bypassed. CI runs checkers, linters, analysers, and tests. We require human review of all changes. We need formal, documented User Acceptance Testing (UAT) sign-off by clinical experts for all functional changes. Finally, there is leadership approval for release. However, by the time the code reaches those gates, most issues have already been caught and fixed. The gates become confirmations, not blockers, and work continues to flow.
Tip: Eliminate low-value decision-making. Find an automatic code style validator, such as Rubocop, adopt it, and mandate it for all work. There is no greater waste of expensive engineering time than arguing about syntax during a code review.
In a previous post, I explored the leadership necessity of leading with impatience and the patience to see it through. Our approach to compliance is the practical application of this duality.
Compliance is the patience. It is the understanding that quality, security, and safety are non-negotiable and take time. It protects patients, doctors, our business, and ultimately our ability to keep doing the work we love.
Developer experience is the impatience. It is the refusal to accept that “rigour” must equal “slowness,” and the drive to automate friction out of existence.
When you combine these, you get our strategy: Use the impatience of engineering to automate the patience of compliance.
If developers have to remember to do something for compliance, they’ll resent it. The resentment isn’t about the compliance requirement itself; it’s about the cognitive load and the interruption to flow.
The solution: Automate relentlessly.
All of our developers adhere to a common approach for two key aspects of their work:
Branch naming: You likely use something similar <JIRA-KEY>/descriptive-name-here, e.g. `WA-1023/add-photos-to-user-profiles`.
PR templates: We use a standard PR template across all repositories with headings and checklists related to our business, SOC2, and HIPAA. A PR template like ours takes a slight adjustment for newcomers and adds a couple of minutes to PR creation time. Still, once you get into the flow of it, there aren’t any objections; it helps developers think through the PR and ensure it meets all needs.
With these two primitives in place, we can now automate many tasks. Let me give you some concrete examples of what this looks like from a web application perspective; similar processes exist for our data and platform developers as well.
We leverage GitHub automations and Jira API connections here when a new PR is opened by a developer.
When we’re ready to release the web application, a lengthy process ensues that relies on semantic versioning (semver) tagging and git release branches.
Previously, it took half a day to assemble all the pieces we needed to demonstrate compliance manually. Once proven stable and repeatable across multiple releases, we introduced automation here as well.
It now takes 30 minutes to complete the same process for our release owner using a release script and a combination of GitHub and Jira automations.
The pattern here is consistent: identify the compliance-driven tasks that create friction, then automate them so thoroughly that developers hardly notice they’re happening. The controls exist, the audit trail is available, but the cognitive burden disappears.
Environmental issues are a classic source of frustration. Code works in development but fails in production. Configuration drift across environments creates mysterious bugs. Managing multiple regions globally while expanding semi-regularly is the stuff of nightmares. When the CFO comes knocking about cloud costs, you end up in a cold sweat.
In a compliance context, this is even more problematic; you need to demonstrate that your production environment has the controls you’ve documented, is secure, considers PII and PHI fully, enforces PoLP, is backed up, can be restored from a clean slate in a complete disaster scenario and can report on every single change made.
Our solution has been to invest heavily in Infrastructure as Code (IaC). We’ve built an extensive AWS CDK project in TypeScript that defines all of our infrastructure. This single codebase sustains Development, UAT, and our Production environments in both Australia and the US. Adding another region becomes an easily quantifiable piece of work, measured in days.
The choice of TypeScript for our CDK project has been particularly valuable. Compile-time type checking catches misconfigurations before deployment (well, usually, it is AWS, ask me about war stories). You find out about problems when you run the build, not when CloudFormation fails halfway through a deployment.
AWS itself provides best practices for the CDK and compliance validation with tooling called CDK Nag. CDK Nag allows CI to fail builds unless developers have done the right things or documented a valid exception state, something which our PR reviewers must validate and agree to.
A change to the infrastructure follows the same path as the web application discussed earlier; the only difference is that, instead of a binary, the final output is AWS infrastructure being created, updated, or removed.
This post focuses on developer workflow automation and on how we’ve made compliance controls feel natural rather than burdensome in day-to-day development. But this is just one piece of a comprehensive compliance program. What I haven’t covered here, but Macuject does rigorously, includes:
Make no mistake, obtaining annual attestations for SOC2, HIPAA, and others is no easy task and requires the involvement of the entire business to be successful.
If you’re working in a similar environment and feeling the tension between compliance and developer productivity, start by asking your developers what slows them down most. I’d bet that you can solve at least some of these without compromising compliance posture. Often, the solution will strengthen both.
Let’s move the conversation from “How do we pass the audit?” to “How do we design our developer experience to make compliance a feature, not a hassle?”
]]>After all this time, I still have a lot to discover. However, I have picked up a few things along the way, and in this post, I wanted to share one of those with you, “Lead with the impatience to change the world and the patience to see it through”.
Drive innovation: Software companies thrive on innovation. Be relentless in your pursuit of technological advancement. Support your team to explore new frontiers, experiment with cutting-edge technologies, and challenge the status quo. Be impatient when it comes to taking action on your innovative ideas.
Rapid prototyping: Swiftly move from concept to prototyping. Develop a culture that encourages rapid prototyping, where ideas are tested, refined, and validated as quickly as possible.
Agile development: Embrace agile methodologies in your software development process. Shorter development cycles and more frequent releases enable you to iterate and adapt swiftly to user feedback and changing market conditions. I strongly favour Kanban (a post for another day) in this area.
Empower your team: Impatience with actions doesn’t mean micromanaging. Instead, empower your team to make decisions and take ownership of their work. Encourage autonomy and trust your people to execute with speed and precision.
Quality assurance: Rigorous testing, bug fixes, UAT, security scanning, and other quality assurance processes take time. Be patient when it comes to ensuring your products meet the highest standards of reliability and performance.
Compliance: Ensuring compliance with regulatory standards, relevant to your software companies’ industry of operation is critical and includes standards such as SOC2, ISO27001, GDPR and HIPAA. Be patient as your team diligently works to meet these compliance requirements, knowing that it’s vital for the trust and security of your users’ data. Automate compliance wherever possible, you’ll have to revisit it annually.
Long-term impact: Technological innovations can have a profound and lasting impact on user experiences. Understand that the results of your efforts may take time to be visible. Be patient and committed to the long-term vision of delivering exceptional software.
Market penetration: Breaking into a market can be challenging for software companies. It often involves fierce competition, market fluctuations, and building user trust. Be patient as you work towards establishing a solid market presence.
Leadership within software companies extends beyond technical prowess. We need the audacity to envision change, the patience to shepherd it into reality, and the compassion to understand the diverse needs of our teams and customers.
Lead with the impatience to change the world and the patience to see it through!
]]>At Macuject, we’re building in the AWS cloud, and one of the critical drivers of our architecture is the AWS Well-Architected Framework. The framework comprises a set of six pillars that describe key concepts, design principles, and architectural best practices for designing and running workloads in the cloud; these include:
Within the security pillar, you’ll find the foundational concept of SEC01-BP01, “account separation”, which is the basis of the problem described here. If this is new to you, AWS has a whitepaper that might interest you; you’ll also want to invest time in AWS Organizations, AWS Control Tower, and AWS Identity Center (IDC). For this post, we’ll define three AWS accounts:
AccountA has:
AccountB has an S3 bucket called our-shared-widgetsAccountC has various pieces of compute used for developmentFor some time, our users have been able to access the our-shared-widgets bucket in AccountB while logged in using IDC policies associated with AccountC without issue. Some of these policies grant some of our users GetObject, some PutObject, and others with both. Policies providing this access can be tricky to set up, so this walk-through is an excellent place to start if you want more information.
I recently needed to provide a new user access to our-shared-widgets while logged in using IDC policies associated with AccountB. If you missed it, the critical difference is the IDC policies and their account association, AccountC vs. AccountB.
The authentication process was successful; IDC functioned as expected, but on attempting to get an S3 object, a 403 Access Denied error occurred.
S3 is simple until it isn’t. As a starting point, I reviewed the following aspects of our IAM policies and S3 bucket policies to rule out any obvious issues:
Deny statement in either policy. Explicit Deny statements always take precedence over Allow statements.None of the above was the culprit, our new user still couldn’t get objects, and our pre-existing users kept operating happily.
Next I logged in with full administrative rights in AccountB and pushed a test file to our-shared-widgets; our new user could get that object. Now I am intrigued, cross-context puts are at fault.
My next avenue of investigation was objects somehow being associated with the wrong server-side key when encrypting files which meant the IDC policies associated with AccountB would not be able to decrypt them, hence the 403. On review, this was not the case; the key used to encrypt existing objects was the KMS CMK for our-shared-widgets, as expected:
❯ aws s3api head-object --bucket our-shared-widgets --key file.ext
{
"AcceptRanges": "bytes",
"LastModified": "2023-04-17T01:14:05+00:00",
"ContentLength": 15,
"ETag": "\"52d22dba61ed2f00b1fcd41\"",
"VersionId": "NPWsAIu_oO04xAeL4rE_me0Z.bEScteI",
"ContentType": "text/plain",
"ServerSideEncryption": "aws:kms",
"Metadata": {},
"SSEKMSKeyId": "arn:aws:kms:...:...:key/677379e1...",
"BucketKeyEnabled": true
}
Now, I’m racking my brain and making little progress on diagnosis. Some fresh air and an espresso later, I decide to consider object ownership:
❯ aws s3api get-object-acl --bucket our-shared-widgets --key file.ext
{
"Owner": {
"DisplayName": "AccountC",
"ID": "63a4d1..."
},
"Grants": [
{
"Grantee": {
"DisplayName": "AccountC",
"ID": "63a4d1...",
"Type": "CanonicalUser"
},
"Permission": "FULL_CONTROL"
}
]
}
RESULT!
AWS S3 Access Control Lists (ACLs) are a legacy access control mechanism that allows you to manage the permissions of individual objects within an S3 bucket. With ACLs, you can define which AWS accounts, or groups are granted access to an object and their specific permissions, such as read, write, or delete access. They’re complex, and as such, I’ve always used IAM policies and bucket policies.
That said, by default, when an object is uploaded to a bucket, it is owned by the AWS account that uploaded it; this means that the object’s permissions are determined by the ACL settings specified by the uploading account. In a cross-account scenario like ours, this can lead to a situation where the bucket owner does not have full access to the objects uploaded by other AWS accounts, even though the objects are stored in their bucket.
I’d forgotten this key aspect when investigating this fault, so it is worth repeating; by default, when an object is uploaded to an S3 bucket, it is owned by the AWS account that uploaded it.
Root cause identified. As we saw, the objects in the bucket are owned by AccountC, so regardless of appropriate IAM and S3 Bucket policies, any user associated via IDC policies with AccountB would be denied access by ACLs.
Amazon S3 introduced the bucket owner-enforced feature in late 2021. By enabling the s3.ObjectOwnership.BUCKET_OWNER_ENFORCED setting on the bucket, the owner can ensure complete control over all objects, regardless of which account uploaded them. It is worth noting this setting entirely disables ACLs, good riddance!
You can make this change via the console; however, I recommend doing this via the CDK (you created the bucket via CDK, right?):
const bucket = new s3.Bucket(this, 'Bucket', {
bucketName: 'our-shared-widgets',
...
objectOwnership: s3.ObjectOwnership.BUCKET_OWNER_ENFORCED,
});
Changes to object ownership for existing buckets defined in a stack are applied by CloudFormation; there is no need to define a custom lambda function to update the bucket.
With these changes in place, all is well again; our new user can get all objects, and our pre-existing users can still get and put objects. Going forward ownership of objects will always be, AccountB regardless of how they’re uploaded. IAM and S3 bucket policies will function as expected without ACL interference. 🎉
This default is archaic, much like allowing public access to buckets. No doubt I’m not the first person to have suffered this, but likely not the last.
AWS, to their credit, have been working on these issues for a while now and plan to change the defaults per https://aws.amazon.com/about-aws/whats-new/2022/12/amazon-s3-automatically-enable-block-public-access-disable-access-control-lists-buckets-april-2023/. This change is probably rolling out around the same time I publish this blog post. That said, the changes won’t be retroactive, so if you have existing buckets, you might trip over this and still need to take action.
]]>Security breaches in the healthcare sector are all too common, with incidents ranging from malicious attacks to accidental data leaks by internal staff or misplaced devices like laptops.
Personal Health Information (PHI) is a hot commodity on the dark web, even more so than credit card details or typical Personally Identifiable Information (PII). This heightened value means cybercriminals target medical databases, either to sell the PHI or to exploit it for their own nefarious purposes. A staggering 15 million+ health records have fallen victim to data breaches, as reported by the health and human services breach report.
For many MedTech startups, the US is a key market, which makes both SOC2 compliance and HIPAA adherence a must. I’ll expand on those below.
Outside the US, there are other standards and laws that are important to consider including:
Achieving compliance and adherence to these standards and laws is a long process. They require significant financial and people investment. You also need to be prepared to make changes to your product and processes to meet the requirements of each standard.
I strongly recommend having someone on your team with prior experience in implementing these standards and laws. It is a huge advantage which means you’ll be able to hit the ground running and tweak implementation to your companies operating environment whilst still being compliant. Alternatively look for a consultant who can help you get started who has worked with your scale of company previously.
Most importantly ensuring commitment to security and compliance is something you need to instill in your company culture, from the top down. Security is everyone’s responsibility. Your people will need to see the changes as a benefit to them, not a burden. In that regard ensure what you’re putting in place is practical and not overly complex. Embrace automation where ever possible.
Also be aware that achieving compliance and adherence to these standards and laws is not a one-off investment. You need to continue to demonstrate your commitment to security and compliance, company-wide, every single day. An annual audit process with a third party partner is a key part of this as is ongoing budget and people allocation.
Service Organization Control (SOC) 2 is a security auditing process developed by the American Institute of Certified Public Accountants (AICPA). SOC 2 is specifically designed for service providers that store, process, or transmit customer data in the cloud. It assesses the effectiveness of a service organization’s controls in managing customer data, focusing on five key principles:
SOC 2 compliance demonstrates a commitment to the security, confidentiality, and availability of sensitive health information. The compliance process includes:
The audit results in a SOC 2 report, which provides an in-depth review of the service organization’s controls and their effectiveness. A Type 1 report assesses the design of the controls, while a Type 2 report evaluates their operating effectiveness over a specified period. You’ll do both types of report, achieving Type 1 compliance first, then Type 2.
The Health Insurance Portability and Accountability Act (HIPAA) is a US law that sets the standard for protecting sensitive patient data. Any company that handles protected health information (PHI) must ensure their systems and processes comply with HIPAA. The HIPAA Privacy Rule and the HIPAA Security Rule are the primary components of HIPAA, focusing on the safeguarding of PHI.
Key aspects of HIPAA for MedTech startups include:
Upon meeting HIPAA requirements, organizations can obtain a HIPAA attestation. This is a formal declaration, confirming that the organization has implemented the necessary safeguards to protect PHI as required by the HIPAA Privacy and Security Rules. This may be done internally but is more commonly done by a third party partner.
I’ve found it particularly useful to use the same third party partner for both SOC 2 compliance and HIPAA attestation. This ensures you’re getting a consistent approach to security and compliance assessment and that you’re not duplicating effort in areas where there is overlap in the controls you need to implement.
If you’re a MedTech startup then security and compliance is a must. It’s not something you can afford to ignore.
Good luck on your journey!
]]>