How It Works

The virtual sandbox is the lightest environment: a filesystem CodeWork keeps in its own process, paired with just-bash, a bash emulator written in TypeScript. No real process is ever spawned on your machine.

Two properties define it:

It’s isolated. Commands are emulated in-process, so the model can’t reach your files, processes, environment variables, or the network.
It’s ephemeral. It starts empty and disappears with the CodeWork process that created it.

Driver	Filesystem
`memory`	An in-memory tree
`sqldb`	A tree stored in SQLite

Both are built in. All tools act on the same tree, so a file from write is there for cat.

From the CLI or the RPC server, sqldb keeps its database in memory, so today it behaves like memory.

It Starts Empty

Nothing is copied in: the session starts at / in an empty filesystem. Put what the agent needs in the prompt, or have it write the files first.

What Works

Bash syntax (pipes, redirects, variables, loops, functions) and common commands:

Files: ls, cat, cp, mv, rm, mkdir, touch, find, tree, tar, gzip
Text: grep, rg, sed, awk, sort, uniq, cut, diff, head, tail, wc, xargs
Data: jq, yq, sqlite3, xan

Run help or <command> --help inside the sandbox for the full list.

What Doesn’t

No real programs. No git, node, pnpm, python, compilers, or test runners. They fail with “command not found”.
No network. curl isn’t available.
No processes. A plugin tool that spawns a process through the sandbox fails. Plugin code that calls Node APIs directly still works.
No hard links. ln -s works; ln without it fails.

How Long It Lasts

codework run: gone when the run ends. A continued session can’t find its files.
codework serve: lives as long as the server, so sessions can share it with --sandbox-id.

When to Use It

It’s enough for any work that only needs files and text:

Writing or reshaping text, docs, config, or data.
Scratch work you’ll throw away.
Trying a model or prompt you don’t trust.
Testing a plugin tool without touching your machine.

Virtual