Matt Pocock built and open-sourced Sandcastle, a TypeScript library that runs Claude Code and other coding agents inside sandboxes to plan, implement, review, and merge whole GitHub issues without a human clicking approve.
Posted
2 months ago
Duration
Format
Tutorial
educational
Views
143.2K
4.7K likes
Big Idea
The argument in one line.
Running AI coding agents unattended requires real sandboxing, not YOLO-mode permission bypass, so Matt Pocock built Sandcastle, a TypeScript library that orchestrates planner, implementer, reviewer, and merger agents inside isolated Docker containers driven by GitHub issues.
Who This Is For
Read if. Skip if.
READ IF YOU ARE…
You run Claude Code or Codex agents unattended and are tired of babysitting permission prompts.
You're comfortable with TypeScript, Docker, and GitHub issues and want a programmatic way to run agent workflows instead of a hosted SaaS.
You want multiple agents working in parallel on a backlog with an automated review-and-merge step.
You're curious how to structure prompts for planner/implementer/reviewer/merger roles in a multi-agent pipeline.
SKIP IF…
You only run one agent interactively and are fine approving each action yourself.
You need a no-code or hosted solution rather than something you configure and self-host.
TL;DR
The full version, fast.
Running coding agents AFK means they need to act without a human approving every permission request, but bypassing permissions entirely risks disasters like a deleted home directory or exfiltrated code. The presenter built Sandcastle, an open-source TypeScript library that runs agents inside isolated Docker sandboxes with a simple `sandcastle.run()` primitive. Its GitHub-issues-driven templates set up a pipeline: a planner agent reads open issues and produces a JSON plan of unblocked work, implementer agents each work a separate branch inside their own sandbox, a reviewer agent checks the diff against project coding standards, and a merger agent reconciles multiple branches back into main — resolving merge conflicts itself. The whole flow is unopinionated: you can swap agents (Claude Code, Codex), change sandbox providers, or restructure the prompts, since Sandcastle just provides the run primitive and templates, not a prescribed workflow.
Free for members
Chat with this breakdown — free.
Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.
Coding agents need to run unattended, but permission prompts block that, and bypassing them entirely (YOLO mode) risks catastrophic actions like deleting a home directory or exfiltrating code.
00:51 – 02:03
02 · Why existing sandbox tools didn't work
Docker sandboxes alone caused too many problems running AFK; every third-party tool tried to sell a hosted service, so he built Sandcastle — a simple TypeScript function for running a prompt in a sandbox with a chosen agent.
02:03 – 02:14
03 · What Sandcastle can build
A single sandcastle.run() primitive can compose into complex systems: parallel agents, agents that review and merge their own code.
02:14 – 03:05
04 · Installing and initializing
npm install ai-hero/sandcastle, then npx sandcastle init walks through selecting an agent (Claude Code), a sandbox provider (Docker), and a backlog manager (GitHub issues).
03:05 – 03:25
05 · Choosing a template
Selects the most advanced built-in template: a parallel planner with a review step, and creates a 'sandcastle' GitHub label so only labeled issues get picked up.
03:25 – 03:45
06 · Inside the .sandcastle directory
Generated scaffolding includes a Dockerfile defining the sandbox image — installing GitHub CLI, renaming the home directory to 'agent', and installing Claude Code.
03:45 – 04:34
07 · Environment variables and building the image
Sets ANTHROPIC_API_KEY and a GitHub token in .sandcastle/.env, notes the option to use a Claude subscription instead (with caveats), then builds the Docker image.
04:34 – 04:58
08 · Filing a GitHub issue for the agent
Creates a GitHub issue asking for a basic TypeScript template with vitest, type checking, a commander CLI, and a CI script, to be picked up by the agent.
04:58 – 06:17
09 · Running the pipeline: planner and implementer kick off
Adds an npm script to run the sandcastle entry point; the planner agent finds the one open issue, produces a plan, and an implementer agent spins up in its own sandbox to build the scaffold using red-green-refactor.
06:17 – 07:18
10 · Walking through main.mts: planner logic
Shows the planner's sandcastle.run() call and its prompt file, which pulls all open, sandcastle-labeled issues plus their comments and outputs only unblocked issues as JSON.
07:18 – 07:59
11 · Walking through main.mts: implementer logic
For each planned issue, a separate sandbox runs an implementer agent with a prompt that includes the issue title, task ID, and target branch.
07:59 – 08:09
12 · Why a reviewer agent matters
The implementer can make mistakes that a reviewer generally catches; adversarial review (one agent reviewing another, e.g. Codex reviewing Claude Code) or multi-agent competition is possible.
08:09 – 08:39
13 · The review prompt and coding standards
Shows the review prompt's shell-execution syntax (borrowed from Claude skills) that injects a live git diff, and a coding-standards section meant to be filled in with project-specific rules.
08:39 – 10:09
14 · The merger agent
After all branches are reviewed, a merger agent takes every branch and its associated issue, resolves merge conflicts, and merges everything back into main — or could just as easily open PRs instead.
10:09 – 10:54
15 · Checking in on the run
Reviews the completed run's logs: reviewer found the code clean and well-structured; merger ran type checks, merged the branch, and closed the issue with a comment.
10:54 – 11:25
16 · Wrap-up and newsletter plug
Confirms the new files (tsconfig, vitest config, CLI files) landed in the repo, reflects on how happy he's been using Sandcastle, and points to his AI Hero newsletter for more agent workflows.
Atomic Insights
Lines worth screenshotting.
Bypassing permission prompts entirely (YOLO mode) risks an agent deleting your home directory or exfiltrating code — real AFK agents need sandboxing, not disabled safety checks.
Sandcastle is a TypeScript library, not a hosted service — you write scripts that call sandcastle.run(), passing an agent, a sandbox provider, and a prompt.
The default backlog manager is GitHub issues filtered by a single label, so only issues tagged 'sandcastle' get picked up by the agent pipeline.
A planner agent reads all open labeled issues, their comments, and builds a dependency graph to output only the issues that are currently unblocked.
Multiple implementer agents can run in parallel, each in its own Docker sandbox, each committing to its own branch.
A reviewer agent runs after implementation and checks the diff against project-specific coding standards defined in a prompt file, catching mistakes the implementer made.
You can make review adversarial by having one agent (e.g. Codex) review another agent's (e.g. Claude Code) code, or have multiple agents implement the same issue and have a reviewer pick or merge the best result.
A merger agent is used instead of a plain git merge because merge conflicts across parallel branches can be gnarly, and a capable agent can resolve them more reliably.
The review prompt template supports an exclamation-mark-plus-backticks syntax (borrowed from Claude skills) that executes a shell command like `git diff` when the prompt is resolved, injecting the actual diff into context.
The setup is unopinionated — you can swap Claude Code for Codex, swap Docker for another sandbox provider, or change agents into PR-branch workflows instead of merging straight to main.
The init flow scaffolds a `.sandcastle` directory with a Dockerfile, prompt files, and a `main.mts` entry point that you're expected to edit for your own project's workflow.
Using your Claude subscription instead of an API key inside a sandboxed agent is a gray area Anthropic has specific guidance on, which the repo links to rather than resolving directly.
The whole pipeline — plan, implement in parallel, review, merge — ran end to end on a real GitHub issue in the demo and produced a working TypeScript scaffold with vitest, type checking, and a commander-based CLI.
Takeaway
AFK coding agents need real sandboxes, not disabled permissions
WHAT TO LEARN
Letting an AI coding agent run unattended safely means isolating it in a real sandbox with a structured plan/implement/review/merge pipeline, not just switching off its permission prompts.
Bypassing an agent's permission prompts entirely (YOLO mode) removes the safety checks that stop it from doing destructive things like deleting a home directory or leaking code to a third party.
Real unattended automation requires isolating the agent in a sandbox (a Docker container in this case) so mistakes can't touch the host system.
Splitting agent work into distinct roles — planner, implementer, reviewer, merger — lets each step catch a different class of error instead of relying on one agent to get everything right in one pass.
A planner that reads a backlog (GitHub issues) and figures out which items are unblocked can safely run multiple implementers in parallel without them stepping on each other.
Adding an automated review step after implementation catches a meaningful share of mistakes, and that review can be made adversarial by using a different model or agent than the one that wrote the code.
Merging multiple parallel branches is a good candidate for its own dedicated agent step, since resolving real merge conflicts reliably is harder than a plain implementation task.
Building this kind of pipeline as a thin, unopinionated library (not a hosted platform) keeps you free to swap which agent, sandbox provider, or backlog system you use as better options appear.
Glossary
Terms worth knowing.
AFK agent
A coding agent that runs unattended (away from keyboard), picking up tasks, implementing them, and completing QA without a human approving each action.
Sandcastle
An open-source TypeScript library for orchestrating AI coding agents (like Claude Code or Codex) inside isolated sandboxes, built around a simple run() function.
Sandbox
An isolated execution environment (in this case a Docker container) where an agent can run commands and make changes without risk to the host machine.
Planner agent
An agent role that reads a backlog of tasks (GitHub issues), determines which ones are unblocked, and outputs a structured plan of what to work on next.
Implementer agent
An agent role that takes a single planned task and writes the actual code changes on its own branch inside its own sandbox.
Reviewer agent
An agent role that inspects a git diff produced by an implementer against project coding standards and flags or fixes problems.
Merger agent
An agent role that takes multiple completed branches and merges them back into the main branch, resolving any merge conflicts itself.
Backlog manager
The system Sandcastle uses to track what work is available — by default, GitHub issues filtered by a specific label.
“This is not Sandcastle giving you any kind of prescription on how you want to run it.”
crisp statement of the tool's philosophy — unopinionated primitive, not a framework→ newsletter pull-quote↗ Tweet quote
08:15
“It's just code. It is a programmatic way to run Claude code, to run Codex, and to build these workflows that turn into these mini software factories.”
names the video's title concept directly, good closing summary line→ IG reel cold open↗ Tweet quote
The Script
Word for word.
Read-along
Don't just watch it. Burn it in.
See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.
17px
metaphoranalogy
00:00One of my goals for the last six months have been trying to get my agents, my coding agents, to run totally AFK. These AFK agents have been picking up backlog tasks, have been implementing features for me, have been doing QA. And crucially, they have been running in parallel.
00:14So I've had lots of them running at the same time. However, in order to get them to run properly, you need to handle the permissions request that they make. And a question that you probably have right now is how do I get my agent to run without it constantly battering me with with requests for permissions?
00:29Now, of course, you could just go into YOLO mode and have it totally bypass any permissions requests. But if you do that, Claude will do mad things on your system, like delete your home directory. Or if you're in an enterprise setup, then it might be concerns about, you know, it exfiltrating data or sending your code off to a random third party.
00:47So in order to get agents to run properly AFK, you need them to be sandboxed. And there are a bunch of solutions for this.
00:54However, I was not particularly happy with any of them. The one I really tried to use and tried to make work was Docker sandboxes.
01:02However, there were just so many problems with running it AFK that I won't bore you with now. What I wanted was a simple TypeScript function that I could run and just say, this prompt inside this sandbox using this agent.
01:15And all the tools that I found were trying to sell me some third party service. So I realized I needed to build something here. And that thing is Sandcastle, a TypeScript library for orchestrating AI coding agents in isolated sandboxes.
01:27You can use this to build TypeScript scripts here where you simply say run, passing in the agent, passing in the sandbox, and passing in the prompt. If you look in any one of my open source repos, you'll see this little sand castle or dot sand castle directory here, which has a main dot t s file.
01:45And this is full of these sand castle dot run little functions here. With this simple function, you can build really, really complex systems.
01:53You can build systems that parallelize agents running side by side. You can have systems that review their own code and then merge it in.
02:01I've been really, really enjoying using this, and now I think it's time to make a video on it. Let me show you how to get this set up inside a repo. We first run n p m install a I hero sandcastle.
02:11Once that's done, we can run n p x sandcastle init, and you'll first be asked to select an agent. Let's select ClawCode.
02:18Why not? You can then select between one of the first class sandbox providers that we provide. My plan in the future is to add many many more of these, but and you can also implement your own if you like.
02:27For now, let's just choose Docker. Sandcastle also uses a backlog manager because AFK agents need some way of picking up tickets and knowing what to do next. My preferred way of doing this is GitHub issues.
02:39We also ship with five templates here currently. I mean, there may be many more by the time you run this. Let's actually max out here.
02:45Let's go for a parallel planner with a review step. And since we've chosen GitHub issues, we're going to create a sand castle GitHub label. The issues will be filtered by this label and it means that only things with the sand castle label on our GitHub issue list will be picked up by the agent.
03:00We can see at this stage that a bunch of stuff has been thrown into a dot sandcastle directory just up here.
03:07The thing to know about now is this Dockerfile here, which is essentially the Docker container or the instructions for setting up the Docker container that we're gonna be using. Sandcastle runs inside this Docker container, and it means that you can just install anything you like inside here. We're installing some important system dependencies.
03:23We're installing the GitHub CLI. We're doing a little bit of setup to rename the home directory to agent. We're installing Claw code, and then we're just ready to go.
03:33So let's go ahead and build this default Docker image now. That was really fast, and it has now completed. Our next steps are we need to set the required environment variables in dot sand castle forward slash dot n.
03:44If we have a look in dot sand castle where it is? Dot sand castle forward slash dot n dot example, we can see that we have an Anthropic API key and a GitHub token required.
03:54If you want to use your Claude subscription instead of an API key, then you can head to this issue here that will tell you more about it. If you don't know, Anthropic is a little bit funny about people using their subscription for these kind of things, and so there's some up to date advice there. For me, I'm gonna copy over some environment variables that I've had already.
04:11And once that's done, I'm going to go in to my source control. I'm gonna commit this code and I'm going to push it up because I'm gonna show you how we can use GitHub issues to schedule some work for this agent that we've created. So let's go to our repo and create a new issue.
04:26Let's say scaffold me a basic TypeScript template in the repo. Give me a basic TypeScript application that uses v test, that uses type checking, that has a very very simple CLI that I can call.
04:38Use commander for the CLI, add a CI script that does type checking and runs the tests. So now I'm going to create that issue and we can now run our agent to see what happens. So after that, it should be ready to be picked up.
04:50First, I'm going to add this little piece of code to my package dot JSON here, which is just going to allow me to run a script here. So let's say scripts and then add this sandcastle script here.
05:01This is just going to run n p x t s x, and t s x is just a way that you can run TypeScript as a script. And it's going to run this file dot sandcastle forward slash main dot m t s. So let's actually go ahead and run this and see what happens.
05:14We can see immediately that it's kicked off a planner agent here, and we can control click these logs to see what it's up to. We can see that it successfully set up the sandbox. It's the planner agent running on Docker, and it's looking at the open issues here.
05:27And it sees that there's only one open issue. It then spits out this plan here, which is a set of issues which are going to be worked on. Finally, the bottom here, it shows the amount of context window that it used.
05:37If we zoom back to our terminal here, we can see that an implementer agent was kicked off too. Let's control click these logs and take a look at them. And we can see that it called GitHub issue view one.
05:48It has a clear picture, and it asked for a basic TypeScript script app, v test for testing, type checking, simple CLI using commando. Great. We can see that it's running bash commands inside here.
05:58It's doing okay. Good dependencies installed. And I've even got it prompted, so it's doing a little bit of red green refactor here where it's writing the test first, v test run, etcetera.
06:07We can see it all happening. It's now moved on a little bit further and we can sit and watch this if we want to or, you know, we can go and have a cup of tea. We can relax and this will just do its work without us.
06:18So while this is running, why don't we go and have a look at the main dot m t s file here? We can see the planner that we saw earlier is just down here where we have a sandcastle dot run command that takes in a name of planner. It takes in an agent here, so we can just change this if we want to.
06:33If we want to do planning with codecs, let's say, instead of Claude code, we totally can. And it's also using this prompt file here. So plan prompt in here.
06:42This is scaffolded by the template and you can totally edit this as much as you want to to run anything inside a sandbox. This one is taking all of the open issues from the repo that have the label sandcastle. It's grabbing all of the labels, all the comments, grabbing all of the comments body as well.
06:57And then it's working out which ones can be done right now. So it's only looking for unblocked issues here. And finally, we tell it to output its plan in adjacent objects wrapped in plan tags.
07:07If we go back to main dot m t s, we can see that this thing gets picked up here. We then grab the JSON out of the plan here and figure out the issues. And then for each of the issues, we run a a separate sandbox here.
07:19We run an implementer. And this one has an implement prompt that's just inside here. So implement prompt.
07:25This one takes in some prompt arguments here. So it takes in an issue title. It takes in the task ID, which is the issue ID.
07:31Then it says you're gonna be working on a specific branch. Again, all of this is just a setup that I cooked up really. This is not Sandcastle giving you any kind of prescription on how you want to run it.
07:43This is just a really cool workflow that I tend to use in my repos, so I figured it belonged in a template. If we zoom back to main dot m t s, we can see that the results here is captured in a variable. And if there are more than one commits here, we then run a reviewer.
07:57This pattern has been incredibly powerful because the implementer can make mistakes, but the reviewer generally picks it up. And, of course, if you want to do an adversarial review where you have one agent run or review another agent's code, then you can just do sandcastle dot codex.
08:13If you want to have multiple different agents spawn at the same time, come up with an implementation, and then some other reviewer takes all of those branches, chooses the best one, or makes a, like, a mix of them, you can. That's the power of having a totally agnostic setup to what agent you're running. That's the power of using your or owning your own process.
08:30Anyway, let's take a look at the review prompt here. It's worth noting this little syntax here because this is really nice. This is something I copied from Claude skills, where if you specify an exclamation mark before a bunch of backticks here, it will run this when it's resolving the prompt.
08:46And so it will actually execute git diff source branch branch here. This review prompt just uses a very basic process, understands the change, analyze it for improvements, check correctness, maintain balance.
08:56And crucially, it's a great step for, like, adding your own project standards. So for instance, I've added this coding standards in here that you can fill in with any project standards that you want to be added. Let's look back at main.mts, and we can see what happens after all of these branches get created.
09:11We can see that they then get passed into a merger agent down the bottom. And this one takes all of the branches, takes all of the resulting issues, so it understands the changes that were made, and then merges them back to the main branch. The reason we use an agent for this is that there might be merge conflicts between them.
09:27And I usually like to have a really powerful agent handling those merge conflicts for me because they can sometimes be pretty gnarly. And so at the end of this, we have had multiple agents running at the same time, all committing to their branches, and then we get a, like, a senior merger developer to pull them back into main.
09:42Just this setup has massively increased my velocity, and it works super duper well. And again, Sandcastle is not opinionated here. If you wanted to make these into PR branches, you totally could.
09:52Okay. Let's go and check-in with our running process, and let's see what happened. Alright.
09:56We can see that we had an implementer kick off here, then a reviewer. Let's check the logs for the reviewer. We can see that it found that the code was already clean and well structured, minimal scaffold template naming clear.
10:07And then let's see what happened in the merge. So we can just pull up the merger here, and the merger ran the type checks. It merged in the branch, and it also closed the issue with a comment.
10:18Beautiful. We can see too that if we go and have a look at the rest of our code base here, woah, we now have a bit more code going on. We have a t s config dot json.
10:26We have a v test dot config dot t s, and we have a few files knocking about inside the CLI here. So you can start to see how sandcastle is working here. You can build these relatively complicated flows using a simple primitive using really nice ergonomic markdown prompts.
10:40You can get it to run on different branches and just merge that back into main, or you can get it to do really nice PR flows as well. You know, it's just code. It is a programmatic way to run Claude code, to run Codex, and to build these workflows that turn into these mini software factories.
10:57I've been incredibly happy with it, and I'm really excited to see what you build with it too. If you're thinking about these hard problems too, then you should check out my newsletter for AI skills for real engineers. These follow the skills repo that went absolutely viral a few days ago.
11:10And I also post tips and tricks there for getting the most out of agents using good old software fundamentals. So thanks for watching folks. I'm really excited about this tool.
11:17I think it's gonna be a really nice contribution to the ecosystem, and I've been loving using it. So nice work, and I'll see you in the next one.
The Hook
The bait, then the rug-pull.
Matt Pocock spent six months trying to get his coding agents to run completely unattended, and the blocker was always the same: permission prompts. Rather than bypass them with a dangerous YOLO-mode flag, he built Sandcastle, a self-hosted TypeScript library for running agents inside real sandboxes.
Frameworks
Named ideas worth stealing.
09:38model
Sandcastle's four-agent pipeline
Planner
Implementer
Reviewer
Merger
Sandcastle's flagship template chains four agent roles: a planner reads GitHub issues and produces an unblocked-work plan, implementer agents build each issue in parallel on isolated branches, a reviewer checks each diff against coding standards, and a merger agent resolves conflicts and merges everything back to main.
Steal forany multi-agent backlog-processing pipeline, not just Sandcastle itself — the plan/implement/review/merge separation of concerns generalizes to other agent orchestration setups
CTA Breakdown
How they asked for the click.
VERBAL ASK
11:25newsletter
“If you're thinking about these hard problems too, then you should check out my newsletter for AI skills for real engineers.”
Soft, single mention at the very end after the demo fully lands; ties directly to the video's subject (agent skills) rather than a generic subscribe ask.
A creator builds daemon, a single Mac app that runs every AI coding agent he owns, by giving Claude Fable 5 four rounds of blunt feedback instead of writing a line of the UI himself.
Andrew Warner spends a day cramming on "agent loops," then brings Matthew Berman on screen-share to react to five other creators' examples before showing off — and fixing — his own.
A 13-minute breakdown of the Chinese open-source model that nearly matches Opus 4.8 intelligence at one-fifth the price, and the four-step setup to wire it into Claude Code.