DEV Community: Sanchit

Agent Harness Devlog #002

Sanchit — Thu, 11 Jun 2026 14:44:34 +0000

Building the Pluggable Sandbox

I'm building an agent harness, as a learning project and experimenting different ideas and implementations, along the way learning EffectTS, a lot of it is ideating with agents, agents do help a lot understanding libraries and frameworks which typically take more time and are involving.

Implementing Soft Sandbox

A soft sandbox solution is to implement some kind of application layered sandboxing, not hard sandbox and isolation solutions like VMs, containers, bubblewrap, etc.

This allows us to provided on-spot filesystem layer, for quick agentic workflows, without worrying about agent messing up the current filesystems.

I discovered @platformatic/vfs, a virtual filesystem provider for NodeJS, eventually vfs will be merged into official node, which is great.

The best part of using effect is composability, it's little magical and a blackbox, as I'm just learning about it, It's also very powerful.

The sandbox is just a layer which looks like

Layer<Provides> where Provides = Vfs | ChildProcessSpawner

If your layer provides the tags, it plugs it. These are parts I feel kinda magical!

VFS allows for different provider implementation, like real filesystem, sqlite based, and in-memory filesystem, It also allows for custom provider implementation, so in future I can have S3 filesystem provider, and others.

Integrating with Just Bash

One of the cool projects from Vercel is just-bash It allows for sandboxed bash interpreter for agents, it implements some or most of the required coreutils functionality like grep, cat, ls, etc.

It's really powerful because agents love bash, they've been trained on 40+yrs of unix shell commands.

just-bash also provides a filesystem layer, like VFS but I think sticking to VFS helps, as it will later allows for future proofing with node:vfs implementation and custom provider implementations, the most value from just-bash is the bash interpreter, so the underlying FS could just be VFS and that's what I did, creating VFS implementation that has interface that satisfies just-bash, basically building the bridge

// just-bash accepts a custom filesystem interface.
// Implement it on top of the sandbox's VFS — don't let it bring its own.
const bridge = (vfs: VirtualFileSystem): IFileSystem => ({
  readFile:  (path) => vfs.promises.readFile(path, "utf8"),
  writeFile: (path, content) => vfs.promises.writeFile(path, content),
  stat:      async (path) => toStat(await vfs.promises.stat(path)),
  ...

Bash is just a layer

const shell = Layer.effect(
  Shell,
  Effect.gen(function* () {
    const vfs = yield* FileSystem.Vfs;            // the sandbox's own tree
    const bash = new Bash({ fs: bridge(vfs), cwd: "/" });
    ...

Composition is what really like with Effect like

EnvBash.layer(EnvInMemory.layer())        // bash over a throwaway memory tree
EnvBash.layer(EnvSqldb.layer("fs.db"))    // bash over a filesystem inside one sqlite file
...

The VFS and just-bash working together

const filesystem = yield* FileSystem.Service;
const shell      = yield* Shell;

yield* filesystem.writeFileString("/data.txt", "alpha\nbeta\nbeta\n");

const result = yield* shell.exec("grep beta /data.txt | wc -l");
...

So, if you like this scratchy non-edited, non-ai devlog, give it a like ;)

Next, I'm hoping to learn more about EffectTS and also go deep into building more!

Checkout the repo: https://github.com/codeworksh/codework
Other projects: https://codeworksh.github.io/aikit/

Agent Harness Devlog #001

Sanchit — Tue, 09 Jun 2026 07:25:09 +0000

I'm looking into building an agent harness, this is the first in series for devlog posts and are non-ai, human generated.

The Init

It starts with a working directory, provided by the current process or a custom path.

/app/codeworksh/codework

This seemingly simple filesystem path has a lot going for it, e.g this could be a git repo, nested module within a git repo, or no repo at all, etc.

The idea here is to start somewhere at a filesystem. The mental model of a filesystem is a view to some data on computer partitioned by the filesystem tree, you can walk this tree (will explore this later). This view should be pluggable allowing for custom implementations like VFS, a virtual filesystem whose underlying implementation can be real OS filesystem, in-memory, sqlite, or etc, providing a common interface irrespective of the underlying implementation. see vfs

Location

The location data model represents the instance of working location aka directory example

interface Location {
    directory: string // directory path example os.cwd()
}

The directory path within a machine is always unique, no two paths exists within the same machine, the underlying OS filesystem makes those guarantees, with that knowledge we can also use the directory within a machine as unique key.

With this directory as the unique key, allows us to attach some runtime metadata to the location, allowing us to view the location as a world domain called Project.

Project

A project is a real world domain mental model representing metadata + location. The metadata can be:

a git repository
named directory meaning
some other identification
source files or some binary data, etc.

The most common way to think about a location with metadata is a git repository. Take an example

/app/codeworksh/codework
    .git // git@github.com/codeworksh/codework
    package.json
    ...

Git gives us the common location metadata like name of repository, unique identifier (repo URL), etc. With this we can build the domain model of a Project. Will be exploring more about Git later, there are lot of functionality for it.

Note: Git is just one example here, we can also have git like/specific protocol e.g Cloudflare Artifacts, svn, etc

Example

// git@github.com/codeworksh/codework

interface Project {
    id: string;
    name: string; // codework
    vcs: string; // git
    directories: ProjectDirectory[]
}

interface ProjectDirectory {
    id: string;
    directory: string;
    type: 'main' | 'root' | 'gitworktree'
    sandboxEnvID: string;
}

Project:

id - unique identifier generated via hash of git URL or some UUID see UUID7
name - generated via git repo name
vcs - defaults to git string

Project Directory:

id - unique identifier
directory - absolute path in the filesystem
type - type of directory
- main - The primary, first-seen clone of the repository.
- root - Any other independent clone of the exact same repository on your disk.
- gitworktree - A dynamically created linked copy spun off from one of the roots.

For a non git project a Project can be more simpler with static attributes
Example

interface Project {
    id: 'local';
    name: string; // directory name
    vcs: 'unknown';
    directories: ProjectDirectory[]
}

For non-git directory there is no single best way to globally identify the sources or at least cheaply. Versioned control systems like git allows you to have multiple copies on your machine with same .git it's easy to track hence having directories makes sense, all directories pointing to same project.

Next will be exploring more on this location, building the project domain, and also storing in sqlite DB.

If you like what you read checkout the repo: https://github.com/codeworksh/codework

PS: Would love some stars, keeps me motivated.