I Migrated a Cloudflare Agents Workspace and Measured Everything: What Changes When the Storage Format Changes?
> The difference was not the table names.
TL;DR
On October 20, 2026, Cloudflare Agents switched its Workspace implementation from @cloudflare/shell to @cloudflare/computer. The change is not just a new API name. It changes how files are stored. The old implementation stored one row per path, with the file contents base64-encoded in that same row. The new one separates inodes and chunks, storing content-addressed blobs in 512 KiB pieces.
I ran the old and new implementations in the same Durable Object and compared the data before and after migration.
- The tables are different, so old files are invisible after switching without migration. They are still there, though.
- Storing a whole file in one row changes the size limit and performance. The old implementation hit a limit at about 6 MiB, and its 1 MB read/write cycle was 13.5 times slower.
- The schema is versioned, so it migrates forward automatically but cannot go backward.
| Aspect | Old @cloudflare/shell | New @cloudflare/computer |
| --- | --- | --- |
| Tables | cf_workspace_<namespace> | vfs_* / _vfs_* |
| Representation of one file | One row (path TEXT PRIMARY KEY) | Inode + 512 KiB chunks |
| Where content lives | Base64 in the same row's content column | Blob addressed by SHA-256 |
| Observed file-size limit | About 6 MiB without R2 | No single-row limit; content is chunked |
| 1 MB write + read | 87.25 ms | 6.45 ms |
| Same content at two paths | Stored twice | Both paths share one blob row |
| Reopen with old implementation | Works | Fails with EIO |
Test code: GitHub repository
Here is the main point upfront.
The old and new implementations differ in storage format, not API. Once you understand that, the reason files disappear after switching without a migration, why the file-size limit changes, why the new implementation is faster, and why you cannot switch back all follow from the same underlying change. The migration guide says to copy files manually because the tables differ. The deeper difference is their structure, not their names.
> This article expands on my talk about migrating a Cloudflare Agents Workspace with measurements I could not fit into the presentation. It is for people using Cloudflare Agents who are preparing to move to @cloudflare/computer.
---
1. The announcement
On October 20, 2026, Cloudflare posted this changelog:
> Think and Agent Skills now use the workspace from @cloudflare/computer as well as the filesystem tools.
> @cloudflare/shell is deprecated, and so is Think's createExecuteTool. These will no longer be developed nor supported from today onwards.
On the same day, Cloudflare published @cloudflare/think@0.21.0, @cloudflare/computer@0.6.0, and agents@0.29.0. @cloudflare/shell also received version 0.5.0 that day to announce its deprecation. npm's deprecated flag applies retroactively to earlier versions too, so 0.4.3 shows the same warning.
The migration guide itself had landed earlier, in PR #2564 on October 14. It did not arrive at the same time as the announcement.
The Changelog also says:
> This is a breaking change. @cloudflare/computer stores files in different tables from @cloudflare/shell, and there is no automatic data migration between workspace formats.
“Different tables.” That is where I started. Let's see how different they are.
2. The old Workspace stored one file per row
A Workspace is where an agent stores its files. A model interacts with them through read, write, edit, and ls; the files themselves live in Durable Object SQLite.
The old @cloudflare/shell schema is included in the migration guide:
CREATE TABLE cf_workspace_default (
path TEXT PRIMARY KEY,
parent_path TEXT NOT NULL,
name TEXT NOT NULL,
type TEXT NOT NULL CHECK(type IN ('file','directory','symlink')),
mime_type TEXT NOT NULL DEFAULT 'text/plain',
size INTEGER NOT NULL DEFAULT 0,
storage_backend TEXT NOT NULL DEFAULT 'inline' CHECK(storage_backend IN ('inline','r2')),
r2_key TEXT,
target TEXT,
content_encoding TEXT NOT NULL DEFAULT 'utf8',
content TEXT,
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
modified_at INTEGER NOT NULL DEFAULT (unixepoch())
);
It is straightforward: the path is the primary key, and the metadata and content live in the same row. The content column holds file contents, base64-encoded for binary files.
Large files are handled separately. The default threshold is 1,500,000 bytes. Files above that threshold are moved to R2, leaving only an r2_key in the row. If no R2 bucket is provided, the implementation logs a warning and keeps the file inline:
if (size >= this.threshold && !r2)
console.warn(`[Workspace] File ${path} is ${size} bytes but no R2 bucket was provided. Storing inline.`);
This “put everything in one row” design matters later.
3. The new Workspace separates inodes and chunks
The new @cloudflare/computer uses several tables:
| Table | Stores |
| --- | --- |
| vfs_dirents | Parent inode + name → child inode |
| vfs_nodes | Inode metadata (type / mode / mtime / size / link_target) |
| vfs_chunks | Inode + chunk index → blob SHA-256 |
| vfs_blobs | SHA-256 → size and last-reference time |
| vfs_blob_bytes | SHA-256 → actual bytes |
| vfs_meta | schema_version and revision counter |
Path resolution walks vfs_dirents from the root (inode = 1). File contents are split into 512 KiB chunks, each stored in vfs_blob_bytes as a blob keyed by SHA-256:
const CHUNK_SIZE = 524288;
The tables start with vfs_ or _vfs_, so they do not collide with cf_workspace_*. Both formats can coexist during migration.
From here, I measured what follows from the structural difference.
4. Consequence #1: switching does not make old files visible
I put both implementations on the same Durable Object. Splitting them across two DO namespaces would not test migration on the same storage. I switched between them inside one class.
I wrote 13 items with the old implementation, initialized the new one, and tried reading them:
Read through old Workspace before switch → {found: true, length: 23}
Initialize new Workspace
Read /workspace/notes.md through new → ENOENT no such file
Read /notes.md through new → ENOENT no such file
New-side tree → [{path: "/workspace", type: "dir"}]
The new implementation could not see the files.
If I stopped here, the article would say “the data is gone.” That would be quick—and wrong.
Add two controls
“Not visible through the new implementation” does not tell us whether the original write failed. In the same run, I verified that the old Workspace could still read the file both before and after switching:
Read through old before switch → {found: true, length: 23}
Read through old after switch → {found: true, length: 23}
Rows in cf_workspace_default → 14 (same as before)
The old implementation could still read the file after the switch. The row count had not changed either.
The data was not gone. The new implementation was looking somewhere else. A table listing showed both formats coexisting:
cf_workspace_default
computer_execution_runtime
sqlite_sequence
vfs_blob_bytes vfs_blobs vfs_changes vfs_chunks
vfs_dirents vfs_manifests vfs_meta vfs_nodes
_vfs_fetch_cursor _vfs_mounts _vfs_push_cursor
_vfs_sync_operations _vfs_sync_skips _vfs_watermark
I also learned that all vfs_* tables are created as soon as you call new Workspace(). They do not wait for the first filesystem operation. The schema_version was 10.
5. Consequence #2: the size limit changes when everything fits in one row
The old implementation base64-encodes file contents and puts them in one cell. A 4 MB file becomes 5,592,408 base64 characters.
Meanwhile, the Durable Objects Limits page says:
| Item | Documented limit |
| --- | --- |
| Maximum string, BLOB, or table row size | 2 MB |
| KV key size | Key and value combined cannot exceed 2 MB |
A 4 MB file should not fit in the old Shell. I predicted that while designing the benchmark and prepared files of 1 KB, 100 KB, 1 MB, and 4 MB.
They all worked.
My prediction was wrong.
4 MB → storage_backend=inline, content_encoding=base64,
content_len=5,592,408 → read-back SHA-256 matches
8 MB → Error: string or blob too big: SQLITE_TOOBIG
I got the same result in local Miniflare and a deployed production Durable Object.
Measurement: where is the actual limit?
Stepping through the library would only reveal its implementation constant, not the underlying limit, so I called ctx.storage.sql and ctx.storage.kv directly to find the boundary. Each probe used a new Durable Object.
Largest accepted 8,388,627 bytes
Smallest rejected 8,388,628 bytes
8 MiB is 8,388,608 bytes. TEXT, BLOB, and a KV value all failed at the same boundary.
That is four times the documented 2 MB. I repeated probes around the boundary on a new Durable Object and got the same result. I reported it in cloudflare-docs#34502. Since I could not rule out 2 MB being the guaranteed limit and 8 MiB merely an implementation allowance, I did not open a PR asserting a new limit; I attached a reference branch instead.
Why does the old implementation stop at 6 MiB?
The old Shell hit its own boundary below the raw SQL limit:
Largest file accepted by shell.writeFileBytes 6,291,408 bytes (8,388,544 base64 chars)
Smallest rejected 6,291,409 bytes (8,388,548 base64 chars)
Base64 expands the content by about 4/3, so that works out to roughly 6 MiB of file data.
I could not explain why the Shell fails earlier than raw SQL at 8,388,627 bytes. I reproduced its DDL, indexes, INSERT statement, ON CONFLICT DO UPDATE clause, and base64 string, then ran them against the same Durable Object. Raw SQL accepted the value. I also suspected that UPSERT might duplicate the value through excluded, but an UPSERT against an existing row accepted the same size.
The stack trace points to the Shell's INSERT:
Error: string or blob too big: SQLITE_TOOBIG
at Object.run (index.js:367:17)
at Workspace.writeFileBytes (index.js:652:22)
I stopped there. For practical purposes, remember that “without R2, the old Shell's file-size limit is about 6 MiB.”
The new Computer splits content into 512 KiB chunks, so this particular wall is gone. Files of 8 MB, 16 MB, and 32 MB all worked. Chunking may look like a performance design, but it also changes the size limit.
6. Consequence #3: base64 conversion on every operation is slower
I hit an oddity here: Date.now() does not advance inside a Worker. In production, even a 4 MB write was recorded as 0ms. It advanced in local Miniflare, so at first I thought I was misreading the production logs.
I measured from outside instead. I sent one request that repeated the operation 60 times and a control request that did nothing, then divided the difference by 60. The table shows the median of seven runs:
| Size | Old Shell | New Computer |
| --- | ---: | ---: |
| 1 KB | 1.58 ms | -0.75 ms |
| 100 KB | 4.92 ms | 0.80 ms |
| 1 MB | 87.25 ms | 6.45 ms |
I cannot draw conclusions from the 1 KB and 100 KB results. As the negative value shows, the differences are buried in HTTP round-trip variance.
At 1 MB, the gap was clear: 13.5×. The old Shell base64-encodes a 1 MB file into one row on every write and decodes it on every read, adding overhead. My measurement includes the write and the read together, so I cannot say which one is slower on its own.
7. Consequence #4: content addressing enables deduplication
The new implementation uses the blob's SHA-256 as its primary key. The same bytes can be shared by files anywhere in the tree.
I wrote the same 512 KiB of content to two paths and counted rows in vfs_blobs:
Initial blob count → 0
Write identical content to path 1 → 1
Write identical content to path 2 → 1 (no increase)
Control: write different content → 2 (increases)
Without the control, I could not distinguish deduplication from an implementation that never added a blob at all. The different byte sequence confirmed that a second row is created when the content differs.
The old implementation stores content per path, so putting the same file in two places uses storage twice.
8. Consequence #5: there is nowhere to put some metadata
The old FileInfo has mimeType, createdAt, and updatedAt. The new WorkspaceStatResult has only these fields:
{ name, inode, mode, mtime, size, isFile, isDirectory, isSymbolicLink }
There is no API in workspace.fs to read or write MIME types. There is only one timestamp, mtime.
The migration guide also says this metadata is not retained:
> Things the copy does not keep:
> - created_at and modified_at. Computer stamps the time of the copy.
> - mime_type. Computer does not store a MIME type per file.
In my measurements, every migrated file's mtime was the time the copy ran. It is not just that the data is “not retained”; the new schema has nowhere to store it.
9. Consequence #6: you can move forward, but not backward
The new implementation versions its schema. Its initialization code looks like this:
const onDiskVersion = db.one("SELECT v FROM vfs_meta WHERE k = ?", "schema_version")?.v ?? 0;
if (onDiskVersion > 10) throw createWorkspaceError("EIO", `Unsupported workspace filesystem schema version ${onDiskVersion}`);
if (onDiskVersion > 0 && onDiskVersion < 10) runMigrations(db, onDiskVersion, 10);
Migrations run forward automatically. There are nine registered migrations, from v1 to v10.
There is no migration backward.
Rather than deploying an old version, I changed the on-disk schema_version to 11 to simulate a database newer than the binary, then ran the same initialization path:
Current schema_version → 10
Control: reconstruct with same version → {read: "hello"}
Set schema_version to 11
Open again with older binary → EIO Unsupported workspace filesystem schema version 11
Set schema_version back to 10
Can it open now? → {read: "hello"}
What I measured is that the binary cannot open a database whose on-disk schema_version is newer than the version it supports. This means “you cannot roll back” only if a new release raises the schema version. It has already been raised nine times, so it is reasonable to expect that it could happen again.
Neither the migration guide nor the Changelog mentions this. There is one sentence in the implementation document 03_filesystem_schema.md:
> Open() refuses to run if the binary is older than the on-disk schema_version.
The old data remains, so if migration fails you can still read from the old tables. The inability to roll back is the less recoverable part.
10. Running the migration guide's script
Now that I understood the structural difference, I ran the migration.
The guide provides a copy function named copyShellWorkspace(). It walks the old Workspace with glob("/**") and writes the files through the new fs API. The destination is under /workspace, which Think also uses as its working directory.
I ran the script without changing it. My test data included UTF-8 Japanese text, TypeScript in a nested directory, JSON for exact-content comparison, 64 KB of binary data generated with a deterministic pseudorandom sequence, an empty directory, and four symlinks covering relative, absolute, and root-escaping targets.
comparison → {
total: 13, missing: [], typeChanged: [],
contentMismatch: [], extra: []
}
All 13 items existed after migration, their types had not changed, and the 64 KB binary's SHA-256 matched. The empty directory remained too. I got the same result in local wrangler dev and in a deployed production environment.
I also verified that the hash comparison could actually detect a mismatch. I changed one bit in a byte sequence and confirmed that it produced a different hash: af2ba40f… versus 73734ea1…. A comparison that cannot detect a mismatch does not prove that two files match.
I checked one assumption the script relies on as well. A comment says, “glob returns rows ordered by path, so parents come before children.” If that were false, writeFile could run before mkdir. In my tests, results were sorted lexicographically, so each parent appeared before its children.
Symlinks need one extra check
When I followed each link individually, one of them failed:
| Link | Target in Shell | Target after migration | Can follow it? |
| --- | --- | --- | --- |
| /links/rel.md | ../notes.md | /workspace/notes.md | Yes |
| /links/abs.md | /notes.md | /workspace/notes.md | Yes |
| /links/dotdot.md | /src/../notes.md | /workspace/src/../notes.md | Yes |
| /links/esc.md | /../notes.md | /workspace/../notes.md | ENOENT |
/workspace/../notes.md resolves to /notes.md, which is outside the migration destination /workspace.
The cause is in the script's resolveTarget():
// Shell resolves a relative target against the link's directory and never
// goes above `/`.
function resolveTarget(link: string, target: string): string {
if (target.startsWith("/")) return target; // Absolute paths pass through
const parts = link.split("/").slice(1, -1);
for (const part of target.split("/")) {
if (part === "..") parts.pop();
else if (part !== "" && part !== ".") parts.push(part);
}
return `/${parts.join("/")}`;
}
The @cloudflare/shell implementation (resolveSymlink) also sends absolute paths through normalizePath. normalizePath stops .. at the root, so /../notes.md becomes /notes.md in Shell. The migration script passes the path through unchanged. When it prefixes /workspace, the target escapes that directory.
The conditions are narrow. Relative paths all migrate correctly. Absolute paths containing ., //, or .. that does not go above the root also work. The only failure is an absolute path containing .. that goes above the root.
The script does not report an error. symlink() saves the target without validating it, and following it stops at the root rather than throwing. This is like a legal dangling link on POSIX. The copy completes successfully.
A path/type/hash comparison will not catch this. The link exists, so it is not missing. Its type is still symlink, so the type matches. It has no file content, so it is not included in the hash comparison. My own comparison script reported missing: [], contentMismatch: []. To catch this, you have to follow and read the link:
await to.fs.readFile(linkPath, "utf8"); // ENOENT if the target cannot be followed
A second issue is that the migration is not safe to rerun:
First migration → ok
Second migration → EEXIST path exists: /workspace/links/abs.md
mkdir({ recursive: true }) silently succeeds for an existing directory. writeFile overwrites unless exclusive is specified. symlink(target, path) has no equivalent of a force option; if the path already exists, it always throws EEXIST. That matches Node's fs.symlink behavior and is not a library bug.
The guide's onStart example sets a flag after copying completes. If the copy fails partway through, the flag is never set and the next startup fails again on the same link. Remove the link before recreating it:
const link = at(entry.path);
if (await to.fs.readlink(link).then(() => true, () => false)) {
await to.fs.rm(link);
}
await to.fs.symlink(at(target), link);
I reported these two issues in cloudflare/agents#2645. Before filing, I checked for duplicates and found that both had been raised in earlier reviews. One did not survive a PR replacement; the other had been marked resolved based on the incorrect assumption that absolute paths were already rebased. Checking first meant I did not present either as a new discovery.
If your Workspace has no symlinks, you will not hit this part.
11. Persistence survives hibernation
The storage format changed, but the files still live in Durable Object SQLite. I checked whether they survive restarts.
“Readable from another request” is not enough evidence. The same instance might still be in memory and return the file from there. I generated a crypto.randomUUID() in the constructor and included it in the response. If that value changes, the Durable Object is a new incarnation.
bootId Read
1. Write 1cadfbdd-7595-4879-94c1-43abca4688c0 ok
2. Read immediately 1cadfbdd-7595-4879-94c1-43abca4688c0 ok (same)
3. After 15 seconds e4f5f2ab-3d7d-4389-8e2d-ee32fdd97b02 ok (changed)
4. After 150 seconds c602f7f1-c9f6-465e-9b36-0c3259706d64 ok (changed again)
Reads 3 and 4 came from different incarnations. The file content included the old bootId from when it was written, showing it was the same data.
I decided which fields to record before running the test: a case number for writing back the verdict, bootId to show whether a restart happened, env to distinguish local from production, sha256 and size to identify the file, the operation's elapsed time, and ok and error fields that hold results instead of throwing exceptions.
This control proved useful. After redeploying, my first immediate read succeeded, but the bootId was unchanged. The DO was still in memory and running the old code; it had not restarted. Without the control, I might have concluded that the file persisted across a restart. I waited 15 seconds and tried again, then confirmed that the bootId changed and the file was still readable.
How long until hibernation?
I varied the wait time and checked bootId. The zero-second wait was the control:
Wait (s) Restarted Read
0 No ok (control)
3 No ok
6 No ok
9 No ok
11 Yes ok
13 Yes ok
15 Yes ok
The boundary is between 9 and 11 seconds, matching the documentation's “hibernate after 10 seconds of inactivity.”
12. Before you migrate
- Count your symlinks. Run glob("/**") and count entries with type === "symlink". If there are none, the official script should work as-is.
- If you have links, follow and read them after migration. Path/type/hash comparisons will not catch the issue.
- Check for files larger than 6 MiB. If the old implementation stored them in R2, pass the same r2 bucket and name during migration.
- Deploy assuming you cannot roll back. Once the new schema has been written, an older @cloudflare/computer cannot open that Durable Object.
- Do not delete the old data immediately. The old tables remain, so wait to DROP TABLE until your comparison is done.
The dependency arrangement changes too. In @cloudflare/think@0.20.2, @cloudflare/shell was a direct dependency; you did not install it yourself. In 0.21.0, @cloudflare/computer is a peer dependency. The mechanism behind “I upgraded and my Workspace is empty” is right there.
13. Conclusion
The storage format changed, and the rest followed from it:
- Different tables → files are invisible after switching without a migration, but the old tables remain and the old Workspace can still read them.
- One row versus chunks → the old implementation hits a limit at about 6 MiB; the new one accepts files of 32 MB.
- Base64 conversion on every operation → a 13.5× difference in the 1 MB read/write test.
- Content-addressed blobs → the same content at two paths takes one blob row.
- Fewer metadata columns → there is nowhere to store mime_type or created_at.
- A versioned schema → it migrates forward automatically and cannot be opened by an older implementation after the version changes.
The migration guide says to copy files manually because the tables differ. The difference is not just the table names; it is the structure. Understanding that structure tells you what to verify before you migrate.
I also found two mismatches with the documentation. The Durable Object SQLite value limit I tested was 8 MiB, not 2 MB, and the user-facing docs do not mention that an older implementation cannot open a Durable Object after its schema has been upgraded.
The most surprising result was that a 4 MB file worked. I had predicted the result from the official limit and got it wrong. Because I had trusted the documented number, I no longer trusted my other predictions once it failed. I ended up measuring both the size limit and performance myself. That took more time than the migration itself.
References
- Think agents now use a @cloudflare/computer workspace — The announcement, the lack of automatic migration, and deprecation of createExecuteTool.
- Migrating from @cloudflare/shell to @cloudflare/computer — Both schemas and the copy script discussed in §10.
- cloudflare/computer docs/03_filesystem_schema.md — All vfs_* table definitions, chunk size, and schema version behavior.
- Durable Objects — Limits — The documented 2 MB row-size limit tested in §5.
- Durable Objects — Lifecycle — Sources for the 10-second hibernation and 70–140-second eviction behavior.
- cloudflare/computer#217 / #219 — Acknowledgment that writing to R2 and namespaces are not supported yet.
- cloudflare/agents#2645 — Report about the symlink migration script in §10.
6 reactions · 2 comments
Cloudflare AgentsのWorkspaceを移行して測ってみる
> 違うのは、テーブル名ではありませんでした
この記事の結論
2026年10月20日、Cloudflare Agents の Workspace が @cloudflare/shell から @cloudflare/computer に切り替わりました。変わったのは API の名前ではなく、ファイルの持ち方です。旧はパス1本につき1行で、中身を同じ行に base64 で持っていました。新は inode とチャンクに分けて、512 KiB ごとの content-addressed な blob に置きます。
実際の Durable Object に新旧を同居させて、移行の前後を1件ずつ突き合わせました。
- テーブルが別なので、移行せずに切り替えると旧ファイルは見えない。 ただし消えてはいない
- 1行に全部入れるかどうかで、上限も速度も変わる。 旧は約 6 MiB で頭打ち、1MB の読み書きは 13.5 倍遅い
- スキーマにバージョンがあるので、前には自動で進むが後ろには戻れない
| 観点 | 旧 @cloudflare/shell | 新 @cloudflare/computer |
| --- | --- | --- |
| テーブル | cf_workspace_<namespace> | vfs_* / _vfs_* |
| 1ファイルの表現 | 1行（path TEXT PRIMARY KEY） | inode + 512 KiB のチャンク |
| 中身の置き場 | 同じ行の content に base64 | sha256 をキーにした blob |
| 実測の上限 | 約 6 MiB（R2 を渡さない場合） | チャンクに割れるので頭打ちなし |
| 1MB の書き込み+読み込み | 87.25ms | 6.45ms |
| 同じ内容を2箇所に置く | 2行ぶん | blob は1行を共有 |
| 古い実装に戻す | できる | EIO で開けない |
検証コードはこちらです: github.com/tanahiro2010/slides/tree/main/slides/s…
そして、この記事で一番伝えたいことを先に書いておきます。
新旧の差は、API ではなく保存形式です。 そこさえ押さえれば、移行しないと見えなくなる理由も、ファイルサイズの上限が変わる理由も、速くなる理由も、古い実装に戻せない理由も、すべて同じ1つの変更から導けます。移行ガイドは「テーブルが違うので手でコピーしてください」としか書いていませんが、違うのはテーブル名ではなく構造のほうです。
> この記事は「Cloudflare AgentsのWorkspaceを移行してみる」の登壇内容に、発表で話しきれなかった計測値を足したものです。対象は Cloudflare Agents を使っていて、これから @cloudflare/computer に移る人です。
---
1. 発端
2026年10月20日、Changelog が出ました。
> Think and Agent Skills now use the workspace from @cloudflare/computer as well as the filesystem tools.
> @cloudflare/shell is deprecated, and so is Think's createExecuteTool. These will no longer be developed nor supported from today onwards.
同じ日に @cloudflare/think@0.21.0、@cloudflare/computer@0.6.0、agents@0.29.0 が公開されています。@cloudflare/shell も同日に 0.5.0 が出ていて、これが非推奨を告知するリリースです。npm の deprecated フラグは過去のバージョンにも遡って付くので、0.4.3 を見ても同じ警告が出ます。
移行ガイド自体はもう少し前、10月14日の PR #2564 で入っていました。発表と同時にガイドが出たわけではありません。
そして Changelog にはこう書いてあります。
> This is a breaking change. @cloudflare/computer stores files in different tables from @cloudflare/shell, and there is no automatic data migration between workspace formats.
「テーブルが違う」。ここが出発点です。どう違うのかを見ていきます。
2. 旧 Workspace は、1ファイル1行だった
Workspace はエージェントのファイル置き場です。モデルが read write edit ls で触り、実体は Durable Object の SQLite に載っています。
旧 @cloudflare/shell の定義は移行ガイドに載っています。
CREATE TABLE cf_workspace_default (
path TEXT PRIMARY KEY,
parent_path TEXT NOT NULL,
name TEXT NOT NULL,
type TEXT NOT NULL CHECK(type IN ('file','directory','symlink')),
mime_type TEXT NOT NULL DEFAULT 'text/plain',
size INTEGER NOT NULL DEFAULT 0,
storage_backend TEXT NOT NULL DEFAULT 'inline' CHECK(storage_backend IN ('inline','r2')),
r2_key TEXT,
target TEXT,
content_encoding TEXT NOT NULL DEFAULT 'utf8',
content TEXT,
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
modified_at INTEGER NOT NULL DEFAULT (unixepoch())
);
素直です。パスが主キーで、メタデータも中身も同じ行に乗っています。content にはファイルの中身が入り、バイナリなら base64 です。
大きいファイルだけ別扱いになります。既定の閾値は 1,500,000 バイトで、これを超えると R2 に逃がし、行には r2_key だけ残ります。R2 を渡していない場合は警告を出して、そのまま inline に入れます。
if (size >= this.threshold && !r2)
console.warn(`[Workspace] File ${path} is ${size} bytes but no R2 bucket was provided. Storing inline.`);
この「1行に全部入れる」という性質が、後で響いてきます。
3. 新 Workspace は、inode とチャンクに分かれている
新 @cloudflare/computer はテーブルを分けます。
| テーブル | 持つもの |
| --- | --- |
| vfs_dirents | 親 inode + 名前 → 子 inode |
| vfs_nodes | inode のメタデータ（type / mode / mtime / size / link_target） |
| vfs_chunks | inode + 何番目のチャンクか → blob の sha256 |
| vfs_blobs | sha256 → サイズと最終参照時刻 |
| vfs_blob_bytes | sha256 → 実バイト列 |
| vfs_meta | schema_version とリビジョンカウンタ |
パスの解決は vfs_dirents をルート（inode = 1）から辿る形です。ファイルの中身は 512 KiB ごとに切られ、それぞれが sha256 をキーにした blob として vfs_blob_bytes に入ります。
const CHUNK_SIZE = 524288;
名前が vfs_ と _vfs_ で始まるので、cf_workspace_* とは衝突しません。移行の最中は両方が並んで存在できます。
ここから先は、この構造の違いから何が導けるかを1つずつ測りました。
4. 帰結①：切り替えても、旧ファイルは見えない
同じ Durable Object の上に新旧を並べました。別の DO namespace に分けると「同じストレージを使った移行」になりません。1つのクラスの中で切り替えています。
旧で13個書いてから、新を構築して読みます。
対照: 旧から読む → {found: true, length: 23}
新 Workspace を構築
新から読む /workspace/notes.md → ENOENT no such file
新から読む /notes.md → ENOENT no such file
新側のツリー → [{path: "/workspace", type: "dir"}]
新からは見えません。
ここで止めると「データが消えた」という記事になります。早い。そして違います。
対照を2本置く
「新から見えない」だけでは、そもそも書き込みが失敗していた可能性と区別できません。同じ run の中で、旧 Workspace から読めることを切り替えの前後で確認しました。
切り替え前に旧から読む → {found: true, length: 23}
切り替え後に旧から読む → {found: true, length: 23}
cf_workspace_default の行数 → 14（切り替え前と同じ）
切り替えた後も旧からは読めます。行数も減っていません。
消えてはいない。読みに行く先が変わっただけです。テーブル一覧を見ると、両方が同居しています。
cf_workspace_default
computer_execution_runtime
sqlite_sequence
vfs_blob_bytes vfs_blobs vfs_changes vfs_chunks
vfs_dirents vfs_manifests vfs_meta vfs_nodes
_vfs_fetch_cursor _vfs_mounts _vfs_push_cursor
_vfs_sync_operations _vfs_sync_skips _vfs_watermark
ついでに1つ分かりました。vfs_* は new Workspace() を呼んだ時点で全部作られます。最初の fs 操作を待ちません。schema_version は 10 でした。
5. 帰結②：1行に入れるかどうかで、上限が変わる
旧はファイルの中身を base64 にして1つのセルに入れます。4MB のファイルなら base64 で 5,592,408 文字です。
一方、Durable Objects の Limits ページにはこう書いてあります。
| 項目 | 記載値 |
| --- | --- |
| Maximum string, BLOB or table row size | 2 MB |
| Key size（KV） | Key and value combined cannot exceed 2 MB |
2 MB を超えるので、4MB のファイルは旧 Shell に保存できないはずでした。ベンチマークの設計でそう予測して、1KB・100KB・1MB・4MB を並べました。
通りました。
予測が外れました。
4MB → storage_backend=inline, content_encoding=base64,
content_len=5,592,408 → 読み戻しの SHA-256 も一致
8MB → Error: string or blob too big: SQLITE_TOOBIG
ローカルの miniflare でも、デプロイした本番の Durable Object でも同じです。
計測：本当の上限はどこか
段階的なプローブで止めると実装の定数が見えないので、ライブラリを通さず ctx.storage.sql と ctx.storage.kv を直接叩いて境界を詰めました。プローブごとに新しい Durable Object を使っています。
通る最大 8,388,627 バイト
落ちる最小 8,388,628 バイト
8 MiB は 8,388,608 です。TEXT も BLOB も KV の値も、同じところで落ちます。
ドキュメントの 2 MB とは4倍ちがいます。新しい Durable Object で境界の前後だけを叩き直して、同じ結果になることも確認しました。この件は cloudflare-docs#34502 に出しています。2 MB が保証値で 8 MiB が実装の緩さ、という可能性を潰せていないので、数値を断定する PR にはせず、参考ブランチを添えるだけにしました。
考察：なぜ旧だけ 6 MiB で止まるのか
旧 Shell 自身の境界は、素の SQL より低いところにありました。
shell.writeFileBytes が通る最大 6,291,408 バイト（base64 8,388,544 文字）
落ちる最小 6,291,409 バイト（base64 8,388,548 文字）
base64 が 4/3 に膨らむので、ファイルとしては約 6 MiB が上限です。
ただし、なぜ素の SQL（8,388,627）より手前で落ちるのかは分かりませんでした。Shell の DDL、インデックス、INSERT 文、ON CONFLICT DO UPDATE 句、そして Shell が実際に作る base64 文字列まで揃えて、同じ Durable Object で流しても、素の SQL は通ります。 UPSERT が excluded で値を二重に持つのではないかという仮説も立てましたが、行が既にある状態の UPSERT も同じサイズで通りました。
スタックトレースは Shell の INSERT を指しています。
Error: string or blob too big: SQLITE_TOOBIG
at Object.run (index.js:367:17)
at Workspace.writeFileBytes (index.js:652:22)
ここは諦めました。実用上は「旧 Shell に R2 を渡さない場合、ファイルは約 6 MiB が上限」と覚えておけば足ります。
新 Computer は 512 KiB のチャンクに割るので、この壁がありません。8MB も 16MB も 32MB も通りました。チャンク化は速度の工夫に見えますが、変わったのは上限のほうです。
6. 帰結③：毎回 base64 に変換するので、遅い
ここで1つ引っかかりました。Worker の中では Date.now() が進みません。 本番では 4MB の書き込みすら 0ms と記録されます。ローカルの miniflare では進むので、最初は本番のログを見て目を疑いました。
なので外から測り直しました。同じ操作を60回繰り返すリクエストと、0回で素通しするリクエストを投げて、その差を60で割ります。7回の中央値です。
| サイズ | 旧 Shell | 新 Computer |
| --- | ---: | ---: |
| 1KB | 1.58ms | -0.75ms |
| 100KB | 4.92ms | 0.80ms |
| 1MB | 87.25ms | 6.45ms |
1KB と 100KB は結論を出せません。負の値が出ている通り、HTTP の往復のばらつきに埋もれています。
1MB では差が出ました。13.5倍です。旧 Shell は毎回 1MB を base64 に変換して1行に入れ、読むときに戻しているので、その分が乗ります。書きと読みは分離していません。どちらが遅いかまでは言えません。
7. 帰結④：content-addressed なので、重複排除が効く
新は blob の主キーが sha256 です。同じバイト列はツリーのどこにあっても1行を共有します。
512 KiB の同じ内容を2つのパスに書いて、vfs_blobs の行数を数えました。
blobs 初期 → 0
同じ内容を1パス目 → 1
同じ内容を2パス目 → 1 ← 増えない
対照: 違う内容 → 2 ← 増える
対照を置かないと「そもそも blob が増えない実装」と区別できないので、違うバイト列で2行になることも確認しています。
旧はパスごとに content を持つので、同じファイルを2箇所に置けば2回分の容量を使います。
8. 帰結⑤：メタデータの置き場が無くなった
旧の FileInfo は mimeType createdAt updatedAt を持っています。新の WorkspaceStatResult はこれだけです。
{ name, inode, mode, mtime, size, isFile, isDirectory, isSymbolicLink }
MIME を読み書きする API が、workspace.fs のどこにもありません。時刻も mtime の1本だけです。
移行ガイドも「保持されない」と書いています。
> Things the copy does not keep:
> - created_at and modified_at. Computer stamps the time of the copy.
> - mime_type. Computer does not store a MIME type per file.
実測でも、移行後の mtime は全件コピー実行時刻になっていました。「保持されない」というより、新スキーマに置く場所がありません。
9. 帰結⑥：前には進めるが、後ろには戻れない
新はスキーマにバージョンを持ちます。初期化のコードはこうです。
const onDiskVersion = db.one("SELECT v FROM vfs_meta WHERE k = ?", "schema_version")?.v ?? 0;
if (onDiskVersion > 10) throw createWorkspaceError("EIO", `Unsupported workspace filesystem schema version ${onDiskVersion}`);
if (onDiskVersion > 0 && onDiskVersion < 10) runMigrations(db, onDiskVersion, 10);
前方への移行は自動です。v1 から v10 まで、マイグレータが9本登録されています。
後方はありません。
実際に古い版をデプロイする代わりに、on-disk の schema_version を 11 に書き換えて「このバイナリより新しい DB」を作り、同じ構築経路を通しました。
schema_version（現在） → 10
対照: 同じ版で再構築 → {read: "hello"}
schema_version を 11 に偽装
古いバイナリで開き直す → EIO Unsupported workspace filesystem schema version 11
schema_version を 10 に戻す
戻したら開けるか → {read: "hello"}
測ったのは「on-disk の schema_version がバイナリの対応版より新しいと EIO で開けない」ことです。これが「古い版にロールバックできない」を意味するのは、新しい版がスキーマを上げた場合に限ります。過去に9回上げているので、次も上がると見るのが自然です。
移行ガイドにも Changelog にも、この記述はありません。実装ドキュメントの 03_filesystem_schema.md に1行あるだけです。
> Open() refuses to run if the binary is older than the on-disk schema_version.
旧データは残るので、移行に失敗しても最悪は旧テーブルから読み直せます。戻れないほうは取り返しがつきません。
10. 移行ガイドのスクリプトを流す
構造の違いは分かりました。実際に移します。
移行ガイドに copyShellWorkspace() というコピー用のコードが載っています。旧を glob("/**") で歩いて、新の fs に書き直すだけのものです。移行先は /workspace 配下で、Think もそこを作業ディレクトリとして使います。
手を入れずにそのまま流しました。題材は、UTF-8 の日本語を含むテキスト、ネストしたディレクトリに置いた TypeScript、内容の完全一致を見るための JSON、決定的な疑似乱数で生成した 64KB のバイナリ、中身を持たない空ディレクトリ、そして相対・絶対・ルート超えを撃ち分けたシンボリックリンク4本です。
comparison → {
total: 13, missing: [], typeChanged: [],
contentMismatch: [], extra: []
}
13件すべて存在し、型も変わらず、64KB のバイナリも SHA-256 が一致しています。空ディレクトリも残りました。ローカルの wrangler dev でも、デプロイした本番でも同じ結果です。
ハッシュ比較が機能していることも確認しました。1ビットだけ変えたバイト列を用意して、ハッシュが別物になることを見ています。af2ba40f… と 73734ea1… です。比較が不一致を検出できないまま「一致した」と言っても、何も示したことになりません。
スクリプトが暗黙に頼っている前提も確かめました。コードのコメントに「glob returns rows ordered by path, so parents come before children」とあります。これが崩れると mkdir の前に writeFile が走ります。実測では辞書順でソートされていて、親は必ず子より先に来ていました。
ハマりポイント：シンボリックリンクだけ、別の扱いが要る
リンクを個別に辿ってみると、1本だけ落ちました。
| リンク | Shell でのリンク先 | 移行後のリンク先 | 辿れるか |
| --- | --- | --- | --- |
| /links/rel.md | ../notes.md | /workspace/notes.md | 辿れる |
| /links/abs.md | /notes.md | /workspace/notes.md | 辿れる |
| /links/dotdot.md | /src/../notes.md | /workspace/src/../notes.md | 辿れる |
| /links/esc.md | /../notes.md | /workspace/../notes.md | ENOENT |
/workspace/../notes.md は /notes.md に解決されます。移行先の /workspace の外です。
原因はスクリプトの resolveTarget() にあります。
// Shell resolves a relative target against the link's directory and never
// goes above `/`.
function resolveTarget(link: string, target: string): string {
if (target.startsWith("/")) return target; // 絶対パスは素通し
const parts = link.split("/").slice(1, -1);
for (const part of target.split("/")) {
if (part === "..") parts.pop();
else if (part !== "" && part !== ".") parts.push(part);
}
return `/${parts.join("/")}`;
}
@cloudflare/shell の本体（resolveSymlink）は、絶対パスも normalizePath に通します。normalizePath は .. をルートで止めるので、Shell にとって /../notes.md は /notes.md です。スクリプトはそれを素通しするので、/workspace を前置したときに外へ出ます。
条件は狭いです。相対パスは全件正しく、. や // を含む絶対パスも、ルートを超えない .. を含む絶対パスも正しく移ります。崩れるのは「絶対パスで、かつルートより上に登る .. を含む」場合だけです。
そして、これはエラーになりません。symlink() はリンク先を検証せずに保存し、辿るときも例外を投げずルートで止まります。POSIX のダングリングリンクが合法なのと同じです。コピーは正常終了します。
パス・型・ハッシュの照合では捕まりません。 リンクは存在するので欠落にならず、型は symlink のままなので型違いにもならず、中身を持たないのでハッシュ比較の対象にすら入りません。実際、私の照合スクリプトも missing: [], contentMismatch: [] を返しました。確かめるなら、辿って読むしかありません。
await to.fs.readFile(linkPath, "utf8"); // 辿れなければ ENOENT
もう1つ、再実行も止まります。
1回目の移行 → ok
2回目の移行 → EEXIST path exists: /workspace/links/abs.md
mkdir({ recursive: true }) は既存ディレクトリなら黙って返ります。writeFile は exclusive を指定しない限り上書きします。symlink(target, path) には force に相当するオプションがなく、パスが既にあれば必ず EEXIST を投げます。Node の fs.symlink と同じ挙動で、ライブラリ側のバグではありません。
ガイドの onStart の例はコピー完了後にフラグを立てるので、途中で落ちるとフラグが立たず、起動のたびに同じリンクで失敗します。張る前に消せば済みます。
const link = at(entry.path);
if (await to.fs.readlink(link).then(() => true, () => false)) {
await to.fs.rm(link);
}
await to.fs.symlink(at(target), link);
この2点は cloudflare/agents#2645 に出しました。出す前に重複を調べたら、どちらも過去のレビューで指摘されていました。片方は PR の差し替えで引き継がれず、もう片方は「絶対パスは既に rebase されている」という誤った前提のまま解決済みになっていました。新発見として書かずに済んだのは、調べたからです。
シンボリックリンクを含まない Workspace なら、ここは踏みません。
11. 永続化は保たれている
保存形式が変わっても、Durable Object の SQLite に載っている点は同じです。再起動をまたいで残るかを確かめました。
「別のリクエストから読めた」だけでは証拠になりません。同じインスタンスがメモリに残っていて、そこから返しただけかもしれないからです。コンストラクタで crypto.randomUUID() を1つ生成して、レスポンスに載せました。値が変わっていれば、新しい incarnation です。
bootId 読めたか
① 書く 1cadfbdd-7595-4879-94c1-43abca4688c0 ok
② 直後に読む 1cadfbdd-7595-4879-94c1-43abca4688c0 ok ← 同じ
③ 15秒後 e4f5f2ab-3d7d-4389-8e2d-ee32fdd97b02 ok ← 変わった
④ 150秒後 c602f7f1-c9f6-465e-9b36-0c3259706d64 ok ← また変わった
③と④は別の incarnation から読めています。④の中身には書いたときの古い bootId が入っていたので、同じデータだと示せます。
記録するフィールドは最初から決めておきました。判定を書き戻すための C 番号、再起動の有無を示す bootId、ローカルか本番かを示す env、ファイルの同一性を示す sha256 と size、操作そのものにかかった時間、そして例外を投げずに結果として持つ ok と error です。
この対照は実際に仕事をしました。再デプロイ後に読めるかを試したとき、1回目は待たずに読んで成功したのですが、bootId が同じでした。DO は旧コードのままメモリに居座っていて、再起動していません。対照が無ければ「再デプロイしても残る」と書いて終わっていました。15秒待ってから取り直して、bootId が変わったうえで読めることを確認しています。
計測：hibernate は何秒か
待ち時間を変えて bootId を見ました。対照は待ち0秒です。
待ち(s) 再起動 読めた
0 しない ok ← 対照
3 しない ok
6 しない ok
9 しない ok
11 する ok
13 する ok
15 する ok
境界は9秒と11秒の間にあります。ドキュメントの「無活動10秒で hibernate」と一致しました。
12. 移行する前にやること
- シンボリックリンクがあるか数える。 glob("/**") して type === "symlink" を数えるだけです。0本なら公式スクリプトをそのまま使って構いません
- リンクがあるなら、移行後に辿って読む。 パス・型・ハッシュの照合では捕まりません
- 6 MiB を超えるファイルがないか確認する。 旧で R2 に逃がしていたなら、移行時も同じ r2 と name を渡します
- 古い実装に戻せない前提でデプロイする。 新スキーマを一度書いたら、その Durable Object は古い @cloudflare/computer では開けません
- 旧データはすぐ消さない。 旧テーブルは残るので、照合が終わるまで DROP TABLE を待ちます
依存の形も変わっています。旧 @cloudflare/think@0.20.2 では @cloudflare/shell が直接依存で、自分でインストールするものではありませんでした。0.21.0 では @cloudflare/computer が peer dependency になります。「上げたら Workspace が空になった」が起きる構造が、ここにそのまま出ています。
13. まとめ
変わったのは保存形式です。そこから全部が導けました。
- テーブルが別 → 移行せずに切り替えると見えない。ただし旧テーブルは残り、旧 Workspace からは読める
- 1行に全部入れる / チャンクに割る → 旧は約 6 MiB で頭打ち。新は 32MB でも通る
- 毎回 base64 に変換する → 1MB の読み書きで 13.5 倍の差
- blob が content-addressed → 同じ内容を2箇所に置いても1行で済む
- メタデータの列が減った → mime_type と created_at は置く場所がない
- スキーマにバージョンがある → 前には自動で進み、後ろには戻れない
移行ガイドは「テーブルが違うので手でコピーしてください」としか書いていません。違うのはテーブル名ではなく構造のほうで、そこを見ておくと、移行のときに何を確かめればいいかが先に分かります。
ドキュメントとずれていた点も2つ出ました。Durable Object SQLite の値の上限は 2 MB ではなく 8 MiB でしたし、新スキーマを書いた Durable Object が古い実装で開けないことは、ユーザー向けのどこにも書かれていません。
一番こたえたのは、4MB が通ったところです。公式の数字から予測を立てて、外しました。前提を公式に置いていたぶん、崩れたときに他の予測まで信用できなくなって、上限も速度も結局は自分で測り直しています。移行そのものより、そっちに時間を使いました。
参考
- Think agents now use a @cloudflare/computer workspace — 切り替えの告知。自動移行が無いことと createExecuteTool の非推奨
- Migrating from @cloudflare/shell to @cloudflare/computer — 新旧両方の DDL と、10章で流したコピースクリプト
- cloudflare/computer docs/03_filesystem_schema.md — vfs_* の全テーブル定義。チャンクサイズとスキーマバージョンの扱い
- Durable Objects — Limits — 行サイズ 2 MB の記載元。5章で突き合わせた相手
- Durable Objects — Lifecycle — hibernate 10秒、eviction 70〜140秒の出典
- cloudflare/computer#217 / #219 — R2 への書き出しと namespace が未対応であることの自己申告
- cloudflare/agents#2645 — 10章のシンボリックリンクの件を報告したもの
Mentions
@SwiftOnSecurity Try cloudflare computer cloudflare/computer
@mattzcarey @eastdakota @CloudflareDev @Cloudflare thanks Matt, here is the issue: computer#236
I Migrated a Cloudflare Agents Workspace and Measured Everything: What Changes When the Storage Format Changes? > The difference was not the table names. TL;DR On October 20, 2026, Cloudflare Agents switched its Workspace implementation from @cloudflare/shell to @cloudflare/computer. The change is not just a new API name. It changes how files are stored. The old implementation stored one row per path, with the file contents base64-encoded in that same row. The new one separates inodes and chunks, storing content-addressed blobs in 512 KiB pieces. I ran the old and new implementations in the same Durable Object and compared the data before and after migration. - The tables are different, so old files are invisible after switching without migration. They are still there, though. - Storing a whole file in one row changes the size limit and performance. The old implementation hit a limit at about 6 MiB, and its 1 MB read/write cycle was 13.5 times slower. - The schema is versioned, so it migrates forward automatically but cannot go backward. | Aspect | Old @cloudflare/shell | New @cloudflare/computer | | --- | --- | --- | | Tables | cf_workspace_<namespace> | vfs_* / _vfs_* | | Representation of one file | One row (path TEXT PRIMARY KEY) | Inode + 512 KiB chunks | | Where content lives | Base64 in the same row's content column | Blob addressed by SHA-256 | | Observed file-size limit | About 6 MiB without R2 | No single-row limit; content is chunked | | 1 MB write + read | 87.25 ms | 6.45 ms | | Same content at two paths | Stored twice | Both paths share one blob row | | Reopen with old implementation | Works | Fails with EIO | Test code: GitHub repository Here is the main point upfront. The old and new implementations differ in storage format, not API. Once you understand that, the reason files disappear after switching without a migration, why the file-size limit changes, why the new implementation is faster, and why you cannot switch back all follow from the same underlying change. The migration guide says to copy files manually because the tables differ. The deeper difference is their structure, not their names. > This article expands on my talk about migrating a Cloudflare Agents Workspace with measurements I could not fit into the presentation. It is for people using Cloudflare Agents who are preparing to move to @cloudflare/computer. --- 1. The announcement On October 20, 2026, Cloudflare posted this changelog: > Think and Agent Skills now use the workspace from @cloudflare/computer as well as the filesystem tools. > @cloudflare/shell is deprecated, and so is Think's createExecuteTool. These will no longer be developed nor supported from today onwards. On the same day, Cloudflare published @cloudflare/think@0.21.0, @cloudflare/computer@0.6.0, and agents@0.29.0. @cloudflare/shell also received version 0.5.0 that day to announce its deprecation. npm's deprecated flag applies retroactively to earlier versions too, so 0.4.3 shows the same warning. The migration guide itself had landed earlier, in PR #2564 on October 14. It did not arrive at the same time as the announcement. The Changelog also says: > This is a breaking change. @cloudflare/computer stores files in different tables from @cloudflare/shell, and there is no automatic data migration between workspace formats. “Different tables.” That is where I started. Let's see how different they are. 2. The old Workspace stored one file per row A Workspace is where an agent stores its files. A model interacts with them through read, write, edit, and ls; the files themselves live in Durable Object SQLite. The old @cloudflare/shell schema is included in the migration guide: CREATE TABLE cf_workspace_default ( path TEXT PRIMARY KEY, parent_path TEXT NOT NULL, name TEXT NOT NULL, type TEXT NOT NULL CHECK(type IN ('file','directory','symlink')), mime_type TEXT NOT NULL DEFAULT 'text/plain', size INTEGER NOT NULL DEFAULT 0, storage_backend TEXT NOT NULL DEFAULT 'inline' CHECK(storage_backend IN ('inline','r2')), r2_key TEXT, target TEXT, content_encoding TEXT NOT NULL DEFAULT 'utf8', content TEXT, created_at INTEGER NOT NULL DEFAULT (unixepoch()), modified_at INTEGER NOT NULL DEFAULT (unixepoch()) ); It is straightforward: the path is the primary key, and the metadata and content live in the same row. The content column holds file contents, base64-encoded for binary files. Large files are handled separately. The default threshold is 1,500,000 bytes. Files above that threshold are moved to R2, leaving only an r2_key in the row. If no R2 bucket is provided, the implementation logs a warning and keeps the file inline: if (size >= this.threshold && !r2) console.warn(`[Workspace] File ${path} is ${size} bytes but no R2 bucket was provided. Storing inline.`); This “put everything in one row” design matters later. 3. The new Workspace separates inodes and chunks The new @cloudflare/computer uses several tables: | Table | Stores | | --- | --- | | vfs_dirents | Parent inode + name → child inode | | vfs_nodes | Inode metadata (type / mode / mtime / size / link_target) | | vfs_chunks | Inode + chunk index → blob SHA-256 | | vfs_blobs | SHA-256 → size and last-reference time | | vfs_blob_bytes | SHA-256 → actual bytes | | vfs_meta | schema_version and revision counter | Path resolution walks vfs_dirents from the root (inode = 1). File contents are split into 512 KiB chunks, each stored in vfs_blob_bytes as a blob keyed by SHA-256: const CHUNK_SIZE = 524288; The tables start with vfs_ or _vfs_, so they do not collide with cf_workspace_*. Both formats can coexist during migration. From here, I measured what follows from the structural difference. 4. Consequence #1: switching does not make old files visible I put both implementations on the same Durable Object. Splitting them across two DO namespaces would not test migration on the same storage. I switched between them inside one class. I wrote 13 items with the old implementation, initialized the new one, and tried reading them: Read through old Workspace before switch → {found: true, length: 23} Initialize new Workspace Read /workspace/notes.md through new → ENOENT no such file Read /notes.md through new → ENOENT no such file New-side tree → [{path: "/workspace", type: "dir"}] The new implementation could not see the files. If I stopped here, the article would say “the data is gone.” That would be quick—and wrong. Add two controls “Not visible through the new implementation” does not tell us whether the original write failed. In the same run, I verified that the old Workspace could still read the file both before and after switching: Read through old before switch → {found: true, length: 23} Read through old after switch → {found: true, length: 23} Rows in cf_workspace_default → 14 (same as before) The old implementation could still read the file after the switch. The row count had not changed either. The data was not gone. The new implementation was looking somewhere else. A table listing showed both formats coexisting: cf_workspace_default computer_execution_runtime sqlite_sequence vfs_blob_bytes vfs_blobs vfs_changes vfs_chunks vfs_dirents vfs_manifests vfs_meta vfs_nodes _vfs_fetch_cursor _vfs_mounts _vfs_push_cursor _vfs_sync_operations _vfs_sync_skips _vfs_watermark I also learned that all vfs_* tables are created as soon as you call new Workspace(). They do not wait for the first filesystem operation. The schema_version was 10. 5. Consequence #2: the size limit changes when everything fits in one row The old implementation base64-encodes file contents and puts them in one cell. A 4 MB file becomes 5,592,408 base64 characters. Meanwhile, the Durable Objects Limits page says: | Item | Documented limit | | --- | --- | | Maximum string, BLOB, or table row size | 2 MB | | KV key size | Key and value combined cannot exceed 2 MB | A 4 MB file should not fit in the old Shell. I predicted that while designing the benchmark and prepared files of 1 KB, 100 KB, 1 MB, and 4 MB. They all worked. My prediction was wrong. 4 MB → storage_backend=inline, content_encoding=base64, content_len=5,592,408 → read-back SHA-256 matches 8 MB → Error: string or blob too big: SQLITE_TOOBIG I got the same result in local Miniflare and a deployed production Durable Object. Measurement: where is the actual limit? Stepping through the library would only reveal its implementation constant, not the underlying limit, so I called ctx.storage.sql and ctx.storage.kv directly to find the boundary. Each probe used a new Durable Object. Largest accepted 8,388,627 bytes Smallest rejected 8,388,628 bytes 8 MiB is 8,388,608 bytes. TEXT, BLOB, and a KV value all failed at the same boundary. That is four times the documented 2 MB. I repeated probes around the boundary on a new Durable Object and got the same result. I reported it in cloudflare-docs#34502. Since I could not rule out 2 MB being the guaranteed limit and 8 MiB merely an implementation allowance, I did not open a PR asserting a new limit; I attached a reference branch instead. Why does the old implementation stop at 6 MiB? The old Shell hit its own boundary below the raw SQL limit: Largest file accepted by shell.writeFileBytes 6,291,408 bytes (8,388,544 base64 chars) Smallest rejected 6,291,409 bytes (8,388,548 base64 chars) Base64 expands the content by about 4/3, so that works out to roughly 6 MiB of file data. I could not explain why the Shell fails earlier than raw SQL at 8,388,627 bytes. I reproduced its DDL, indexes, INSERT statement, ON CONFLICT DO UPDATE clause, and base64 string, then ran them against the same Durable Object. Raw SQL accepted the value. I also suspected that UPSERT might duplicate the value through excluded, but an UPSERT against an existing row accepted the same size. The stack trace points to the Shell's INSERT: Error: string or blob too big: SQLITE_TOOBIG at Object.run (index.js:367:17) at Workspace.writeFileBytes (index.js:652:22) I stopped there. For practical purposes, remember that “without R2, the old Shell's file-size limit is about 6 MiB.” The new Computer splits content into 512 KiB chunks, so this particular wall is gone. Files of 8 MB, 16 MB, and 32 MB all worked. Chunking may look like a performance design, but it also changes the size limit. 6. Consequence #3: base64 conversion on every operation is slower I hit an oddity here: Date.now() does not advance inside a Worker. In production, even a 4 MB write was recorded as 0ms. It advanced in local Miniflare, so at first I thought I was misreading the production logs. I measured from outside instead. I sent one request that repeated the operation 60 times and a control request that did nothing, then divided the difference by 60. The table shows the median of seven runs: | Size | Old Shell | New Computer | | --- | ---: | ---: | | 1 KB | 1.58 ms | -0.75 ms | | 100 KB | 4.92 ms | 0.80 ms | | 1 MB | 87.25 ms | 6.45 ms | I cannot draw conclusions from the 1 KB and 100 KB results. As the negative value shows, the differences are buried in HTTP round-trip variance. At 1 MB, the gap was clear: 13.5×. The old Shell base64-encodes a 1 MB file into one row on every write and decodes it on every read, adding overhead. My measurement includes the write and the read together, so I cannot say which one is slower on its own. 7. Consequence #4: content addressing enables deduplication The new implementation uses the blob's SHA-256 as its primary key. The same bytes can be shared by files anywhere in the tree. I wrote the same 512 KiB of content to two paths and counted rows in vfs_blobs: Initial blob count → 0 Write identical content to path 1 → 1 Write identical content to path 2 → 1 (no increase) Control: write different content → 2 (increases) Without the control, I could not distinguish deduplication from an implementation that never added a blob at all. The different byte sequence confirmed that a second row is created when the content differs. The old implementation stores content per path, so putting the same file in two places uses storage twice. 8. Consequence #5: there is nowhere to put some metadata The old FileInfo has mimeType, createdAt, and updatedAt. The new WorkspaceStatResult has only these fields: { name, inode, mode, mtime, size, isFile, isDirectory, isSymbolicLink } There is no API in workspace.fs to read or write MIME types. There is only one timestamp, mtime. The migration guide also says this metadata is not retained: > Things the copy does not keep: > - created_at and modified_at. Computer stamps the time of the copy. > - mime_type. Computer does not store a MIME type per file. In my measurements, every migrated file's mtime was the time the copy ran. It is not just that the data is “not retained”; the new schema has nowhere to store it. 9. Consequence #6: you can move forward, but not backward The new implementation versions its schema. Its initialization code looks like this: const onDiskVersion = db.one("SELECT v FROM vfs_meta WHERE k = ?", "schema_version")?.v ?? 0; if (onDiskVersion > 10) throw createWorkspaceError("EIO", `Unsupported workspace filesystem schema version ${onDiskVersion}`); if (onDiskVersion > 0 && onDiskVersion < 10) runMigrations(db, onDiskVersion, 10); Migrations run forward automatically. There are nine registered migrations, from v1 to v10. There is no migration backward. Rather than deploying an old version, I changed the on-disk schema_version to 11 to simulate a database newer than the binary, then ran the same initialization path: Current schema_version → 10 Control: reconstruct with same version → {read: "hello"} Set schema_version to 11 Open again with older binary → EIO Unsupported workspace filesystem schema version 11 Set schema_version back to 10 Can it open now? → {read: "hello"} What I measured is that the binary cannot open a database whose on-disk schema_version is newer than the version it supports. This means “you cannot roll back” only if a new release raises the schema version. It has already been raised nine times, so it is reasonable to expect that it could happen again. Neither the migration guide nor the Changelog mentions this. There is one sentence in the implementation document 03_filesystem_schema.md: > Open() refuses to run if the binary is older than the on-disk schema_version. The old data remains, so if migration fails you can still read from the old tables. The inability to roll back is the less recoverable part. 10. Running the migration guide's script Now that I understood the structural difference, I ran the migration. The guide provides a copy function named copyShellWorkspace(). It walks the old Workspace with glob("/**") and writes the files through the new fs API. The destination is under /workspace, which Think also uses as its working directory. I ran the script without changing it. My test data included UTF-8 Japanese text, TypeScript in a nested directory, JSON for exact-content comparison, 64 KB of binary data generated with a deterministic pseudorandom sequence, an empty directory, and four symlinks covering relative, absolute, and root-escaping targets. comparison → { total: 13, missing: [], typeChanged: [], contentMismatch: [], extra: [] } All 13 items existed after migration, their types had not changed, and the 64 KB binary's SHA-256 matched. The empty directory remained too. I got the same result in local wrangler dev and in a deployed production environment. I also verified that the hash comparison could actually detect a mismatch. I changed one bit in a byte sequence and confirmed that it produced a different hash: af2ba40f… versus 73734ea1…. A comparison that cannot detect a mismatch does not prove that two files match. I checked one assumption the script relies on as well. A comment says, “glob returns rows ordered by path, so parents come before children.” If that were false, writeFile could run before mkdir. In my tests, results were sorted lexicographically, so each parent appeared before its children. Symlinks need one extra check When I followed each link individually, one of them failed: | Link | Target in Shell | Target after migration | Can follow it? | | --- | --- | --- | --- | | /links/rel.md | ../notes.md | /workspace/notes.md | Yes | | /links/abs.md | /notes.md | /workspace/notes.md | Yes | | /links/dotdot.md | /src/../notes.md | /workspace/src/../notes.md | Yes | | /links/esc.md | /../notes.md | /workspace/../notes.md | ENOENT | /workspace/../notes.md resolves to /notes.md, which is outside the migration destination /workspace. The cause is in the script's resolveTarget(): // Shell resolves a relative target against the link's directory and never // goes above `/`. function resolveTarget(link: string, target: string): string { if (target.startsWith("/")) return target; // Absolute paths pass through const parts = link.split("/").slice(1, -1); for (const part of target.split("/")) { if (part === "..") parts.pop(); else if (part !== "" && part !== ".") parts.push(part); } return `/${parts.join("/")}`; } The @cloudflare/shell implementation (resolveSymlink) also sends absolute paths through normalizePath. normalizePath stops .. at the root, so /../notes.md becomes /notes.md in Shell. The migration script passes the path through unchanged. When it prefixes /workspace, the target escapes that directory. The conditions are narrow. Relative paths all migrate correctly. Absolute paths containing ., //, or .. that does not go above the root also work. The only failure is an absolute path containing .. that goes above the root. The script does not report an error. symlink() saves the target without validating it, and following it stops at the root rather than throwing. This is like a legal dangling link on POSIX. The copy completes successfully. A path/type/hash comparison will not catch this. The link exists, so it is not missing. Its type is still symlink, so the type matches. It has no file content, so it is not included in the hash comparison. My own comparison script reported missing: [], contentMismatch: []. To catch this, you have to follow and read the link: await to.fs.readFile(linkPath, "utf8"); // ENOENT if the target cannot be followed A second issue is that the migration is not safe to rerun: First migration → ok Second migration → EEXIST path exists: /workspace/links/abs.md mkdir({ recursive: true }) silently succeeds for an existing directory. writeFile overwrites unless exclusive is specified. symlink(target, path) has no equivalent of a force option; if the path already exists, it always throws EEXIST. That matches Node's fs.symlink behavior and is not a library bug. The guide's onStart example sets a flag after copying completes. If the copy fails partway through, the flag is never set and the next startup fails again on the same link. Remove the link before recreating it: const link = at(entry.path); if (await to.fs.readlink(link).then(() => true, () => false)) { await to.fs.rm(link); } await to.fs.symlink(at(target), link); I reported these two issues in cloudflare/agents#2645. Before filing, I checked for duplicates and found that both had been raised in earlier reviews. One did not survive a PR replacement; the other had been marked resolved based on the incorrect assumption that absolute paths were already rebased. Checking first meant I did not present either as a new discovery. If your Workspace has no symlinks, you will not hit this part. 11. Persistence survives hibernation The storage format changed, but the files still live in Durable Object SQLite. I checked whether they survive restarts. “Readable from another request” is not enough evidence. The same instance might still be in memory and return the file from there. I generated a crypto.randomUUID() in the constructor and included it in the response. If that value changes, the Durable Object is a new incarnation. bootId Read 1. Write 1cadfbdd-7595-4879-94c1-43abca4688c0 ok 2. Read immediately 1cadfbdd-7595-4879-94c1-43abca4688c0 ok (same) 3. After 15 seconds e4f5f2ab-3d7d-4389-8e2d-ee32fdd97b02 ok (changed) 4. After 150 seconds c602f7f1-c9f6-465e-9b36-0c3259706d64 ok (changed again) Reads 3 and 4 came from different incarnations. The file content included the old bootId from when it was written, showing it was the same data. I decided which fields to record before running the test: a case number for writing back the verdict, bootId to show whether a restart happened, env to distinguish local from production, sha256 and size to identify the file, the operation's elapsed time, and ok and error fields that hold results instead of throwing exceptions. This control proved useful. After redeploying, my first immediate read succeeded, but the bootId was unchanged. The DO was still in memory and running the old code; it had not restarted. Without the control, I might have concluded that the file persisted across a restart. I waited 15 seconds and tried again, then confirmed that the bootId changed and the file was still readable. How long until hibernation? I varied the wait time and checked bootId. The zero-second wait was the control: Wait (s) Restarted Read 0 No ok (control) 3 No ok 6 No ok 9 No ok 11 Yes ok 13 Yes ok 15 Yes ok The boundary is between 9 and 11 seconds, matching the documentation's “hibernate after 10 seconds of inactivity.” 12. Before you migrate - Count your symlinks. Run glob("/**") and count entries with type === "symlink". If there are none, the official script should work as-is. - If you have links, follow and read them after migration. Path/type/hash comparisons will not catch the issue. - Check for files larger than 6 MiB. If the old implementation stored them in R2, pass the same r2 bucket and name during migration. - Deploy assuming you cannot roll back. Once the new schema has been written, an older @cloudflare/computer cannot open that Durable Object. - Do not delete the old data immediately. The old tables remain, so wait to DROP TABLE until your comparison is done. The dependency arrangement changes too. In @cloudflare/think@0.20.2, @cloudflare/shell was a direct dependency; you did not install it yourself. In 0.21.0, @cloudflare/computer is a peer dependency. The mechanism behind “I upgraded and my Workspace is empty” is right there. 13. Conclusion The storage format changed, and the rest followed from it: - Different tables → files are invisible after switching without a migration, but the old tables remain and the old Workspace can still read them. - One row versus chunks → the old implementation hits a limit at about 6 MiB; the new one accepts files of 32 MB. - Base64 conversion on every operation → a 13.5× difference in the 1 MB read/write test. - Content-addressed blobs → the same content at two paths takes one blob row. - Fewer metadata columns → there is nowhere to store mime_type or created_at. - A versioned schema → it migrates forward automatically and cannot be opened by an older implementation after the version changes. The migration guide says to copy files manually because the tables differ. The difference is not just the table names; it is the structure. Understanding that structure tells you what to verify before you migrate. I also found two mismatches with the documentation. The Durable Object SQLite value limit I tested was 8 MiB, not 2 MB, and the user-facing docs do not mention that an older implementation cannot open a Durable Object after its schema has been upgraded. The most surprising result was that a 4 MB file worked. I had predicted the result from the official limit and got it wrong. Because I had trusted the documented number, I no longer trusted my other predictions once it failed. I ended up measuring both the size limit and performance myself. That took more time than the migration itself. References - Think agents now use a @cloudflare/computer workspace — The announcement, the lack of automatic migration, and deprecation of createExecuteTool. - Migrating from @cloudflare/shell to @cloudflare/computer — Both schemas and the copy script discussed in §10. - cloudflare/computer docs/03_filesystem_schema.md — All vfs_* table definitions, chunk size, and schema version behavior. - Durable Objects — Limits — The documented 2 MB row-size limit tested in §5. - Durable Objects — Lifecycle — Sources for the 10-second hibernation and 70–140-second eviction behavior. - cloudflare/computer#217 / #219 — Acknowledgment that writing to R2 and namespaces are not supported yet. - cloudflare/agents#2645 — Report about the symlink migration script in §10.
Cloudflare AgentsのWorkspaceを移行して測ってみる > 違うのは、テーブル名ではありませんでした この記事の結論 2026年10月20日、Cloudflare Agents の Workspace が @cloudflare/shell から @cloudflare/computer に切り替わりました。変わったのは API の名前ではなく、ファイルの持ち方です。旧はパス1本につき1行で、中身を同じ行に base64 で持っていました。新は inode とチャンクに分けて、512 KiB ごとの content-addressed な blob に置きます。 実際の Durable Object に新旧を同居させて、移行の前後を1件ずつ突き合わせました。 - テーブルが別なので、移行せずに切り替えると旧ファイルは見えない。 ただし消えてはいない - 1行に全部入れるかどうかで、上限も速度も変わる。 旧は約 6 MiB で頭打ち、1MB の読み書きは 13.5 倍遅い - スキーマにバージョンがあるので、前には自動で進むが後ろには戻れない | 観点 | 旧 @cloudflare/shell | 新 @cloudflare/computer | | --- | --- | --- | | テーブル | cf_workspace_<namespace> | vfs_* / _vfs_* | | 1ファイルの表現 | 1行（path TEXT PRIMARY KEY） | inode + 512 KiB のチャンク | | 中身の置き場 | 同じ行の content に base64 | sha256 をキーにした blob | | 実測の上限 | 約 6 MiB（R2 を渡さない場合） | チャンクに割れるので頭打ちなし | | 1MB の書き込み+読み込み | 87.25ms | 6.45ms | | 同じ内容を2箇所に置く | 2行ぶん | blob は1行を共有 | | 古い実装に戻す | できる | EIO で開けない | 検証コードはこちらです: github.com/tanahiro2010/slides/tree/main/slides/s… そして、この記事で一番伝えたいことを先に書いておきます。 新旧の差は、API ではなく保存形式です。 そこさえ押さえれば、移行しないと見えなくなる理由も、ファイルサイズの上限が変わる理由も、速くなる理由も、古い実装に戻せない理由も、すべて同じ1つの変更から導けます。移行ガイドは「テーブルが違うので手でコピーしてください」としか書いていませんが、違うのはテーブル名ではなく構造のほうです。 > この記事は「Cloudflare AgentsのWorkspaceを移行してみる」の登壇内容に、発表で話しきれなかった計測値を足したものです。対象は Cloudflare Agents を使っていて、これから @cloudflare/computer に移る人です。 --- 1. 発端 2026年10月20日、Changelog が出ました。 > Think and Agent Skills now use the workspace from @cloudflare/computer as well as the filesystem tools. > @cloudflare/shell is deprecated, and so is Think's createExecuteTool. These will no longer be developed nor supported from today onwards. 同じ日に @cloudflare/think@0.21.0、@cloudflare/computer@0.6.0、agents@0.29.0 が公開されています。@cloudflare/shell も同日に 0.5.0 が出ていて、これが非推奨を告知するリリースです。npm の deprecated フラグは過去のバージョンにも遡って付くので、0.4.3 を見ても同じ警告が出ます。 移行ガイド自体はもう少し前、10月14日の PR #2564 で入っていました。発表と同時にガイドが出たわけではありません。 そして Changelog にはこう書いてあります。 > This is a breaking change. @cloudflare/computer stores files in different tables from @cloudflare/shell, and there is no automatic data migration between workspace formats. 「テーブルが違う」。ここが出発点です。どう違うのかを見ていきます。 2. 旧 Workspace は、1ファイル1行だった Workspace はエージェントのファイル置き場です。モデルが read write edit ls で触り、実体は Durable Object の SQLite に載っています。 旧 @cloudflare/shell の定義は移行ガイドに載っています。 CREATE TABLE cf_workspace_default ( path TEXT PRIMARY KEY, parent_path TEXT NOT NULL, name TEXT NOT NULL, type TEXT NOT NULL CHECK(type IN ('file','directory','symlink')), mime_type TEXT NOT NULL DEFAULT 'text/plain', size INTEGER NOT NULL DEFAULT 0, storage_backend TEXT NOT NULL DEFAULT 'inline' CHECK(storage_backend IN ('inline','r2')), r2_key TEXT, target TEXT, content_encoding TEXT NOT NULL DEFAULT 'utf8', content TEXT, created_at INTEGER NOT NULL DEFAULT (unixepoch()), modified_at INTEGER NOT NULL DEFAULT (unixepoch()) ); 素直です。パスが主キーで、メタデータも中身も同じ行に乗っています。content にはファイルの中身が入り、バイナリなら base64 です。 大きいファイルだけ別扱いになります。既定の閾値は 1,500,000 バイトで、これを超えると R2 に逃がし、行には r2_key だけ残ります。R2 を渡していない場合は警告を出して、そのまま inline に入れます。 if (size >= this.threshold && !r2) console.warn(`[Workspace] File ${path} is ${size} bytes but no R2 bucket was provided. Storing inline.`); この「1行に全部入れる」という性質が、後で響いてきます。 3. 新 Workspace は、inode とチャンクに分かれている 新 @cloudflare/computer はテーブルを分けます。 | テーブル | 持つもの | | --- | --- | | vfs_dirents | 親 inode + 名前 → 子 inode | | vfs_nodes | inode のメタデータ（type / mode / mtime / size / link_target） | | vfs_chunks | inode + 何番目のチャンクか → blob の sha256 | | vfs_blobs | sha256 → サイズと最終参照時刻 | | vfs_blob_bytes | sha256 → 実バイト列 | | vfs_meta | schema_version とリビジョンカウンタ | パスの解決は vfs_dirents をルート（inode = 1）から辿る形です。ファイルの中身は 512 KiB ごとに切られ、それぞれが sha256 をキーにした blob として vfs_blob_bytes に入ります。 const CHUNK_SIZE = 524288; 名前が vfs_ と _vfs_ で始まるので、cf_workspace_* とは衝突しません。移行の最中は両方が並んで存在できます。 ここから先は、この構造の違いから何が導けるかを1つずつ測りました。 4. 帰結①：切り替えても、旧ファイルは見えない 同じ Durable Object の上に新旧を並べました。別の DO namespace に分けると「同じストレージを使った移行」になりません。1つのクラスの中で切り替えています。 旧で13個書いてから、新を構築して読みます。 対照: 旧から読む → {found: true, length: 23} 新 Workspace を構築 新から読む /workspace/notes.md → ENOENT no such file 新から読む /notes.md → ENOENT no such file 新側のツリー → [{path: "/workspace", type: "dir"}] 新からは見えません。 ここで止めると「データが消えた」という記事になります。早い。そして違います。 対照を2本置く 「新から見えない」だけでは、そもそも書き込みが失敗していた可能性と区別できません。同じ run の中で、旧 Workspace から読めることを切り替えの前後で確認しました。 切り替え前に旧から読む → {found: true, length: 23} 切り替え後に旧から読む → {found: true, length: 23} cf_workspace_default の行数 → 14（切り替え前と同じ） 切り替えた後も旧からは読めます。行数も減っていません。 消えてはいない。読みに行く先が変わっただけです。テーブル一覧を見ると、両方が同居しています。 cf_workspace_default computer_execution_runtime sqlite_sequence vfs_blob_bytes vfs_blobs vfs_changes vfs_chunks vfs_dirents vfs_manifests vfs_meta vfs_nodes _vfs_fetch_cursor _vfs_mounts _vfs_push_cursor _vfs_sync_operations _vfs_sync_skips _vfs_watermark ついでに1つ分かりました。vfs_* は new Workspace() を呼んだ時点で全部作られます。最初の fs 操作を待ちません。schema_version は 10 でした。 5. 帰結②：1行に入れるかどうかで、上限が変わる 旧はファイルの中身を base64 にして1つのセルに入れます。4MB のファイルなら base64 で 5,592,408 文字です。 一方、Durable Objects の Limits ページにはこう書いてあります。 | 項目 | 記載値 | | --- | --- | | Maximum string, BLOB or table row size | 2 MB | | Key size（KV） | Key and value combined cannot exceed 2 MB | 2 MB を超えるので、4MB のファイルは旧 Shell に保存できないはずでした。ベンチマークの設計でそう予測して、1KB・100KB・1MB・4MB を並べました。 通りました。 予測が外れました。 4MB → storage_backend=inline, content_encoding=base64, content_len=5,592,408 → 読み戻しの SHA-256 も一致 8MB → Error: string or blob too big: SQLITE_TOOBIG ローカルの miniflare でも、デプロイした本番の Durable Object でも同じです。 計測：本当の上限はどこか 段階的なプローブで止めると実装の定数が見えないので、ライブラリを通さず ctx.storage.sql と ctx.storage.kv を直接叩いて境界を詰めました。プローブごとに新しい Durable Object を使っています。 通る最大 8,388,627 バイト 落ちる最小 8,388,628 バイト 8 MiB は 8,388,608 です。TEXT も BLOB も KV の値も、同じところで落ちます。 ドキュメントの 2 MB とは4倍ちがいます。新しい Durable Object で境界の前後だけを叩き直して、同じ結果になることも確認しました。この件は cloudflare-docs#34502 に出しています。2 MB が保証値で 8 MiB が実装の緩さ、という可能性を潰せていないので、数値を断定する PR にはせず、参考ブランチを添えるだけにしました。 考察：なぜ旧だけ 6 MiB で止まるのか 旧 Shell 自身の境界は、素の SQL より低いところにありました。 shell.writeFileBytes が通る最大 6,291,408 バイト（base64 8,388,544 文字） 落ちる最小 6,291,409 バイト（base64 8,388,548 文字） base64 が 4/3 に膨らむので、ファイルとしては約 6 MiB が上限です。 ただし、なぜ素の SQL（8,388,627）より手前で落ちるのかは分かりませんでした。Shell の DDL、インデックス、INSERT 文、ON CONFLICT DO UPDATE 句、そして Shell が実際に作る base64 文字列まで揃えて、同じ Durable Object で流しても、素の SQL は通ります。 UPSERT が excluded で値を二重に持つのではないかという仮説も立てましたが、行が既にある状態の UPSERT も同じサイズで通りました。 スタックトレースは Shell の INSERT を指しています。 Error: string or blob too big: SQLITE_TOOBIG at Object.run (index.js:367:17) at Workspace.writeFileBytes (index.js:652:22) ここは諦めました。実用上は「旧 Shell に R2 を渡さない場合、ファイルは約 6 MiB が上限」と覚えておけば足ります。 新 Computer は 512 KiB のチャンクに割るので、この壁がありません。8MB も 16MB も 32MB も通りました。チャンク化は速度の工夫に見えますが、変わったのは上限のほうです。 6. 帰結③：毎回 base64 に変換するので、遅い ここで1つ引っかかりました。Worker の中では Date.now() が進みません。 本番では 4MB の書き込みすら 0ms と記録されます。ローカルの miniflare では進むので、最初は本番のログを見て目を疑いました。 なので外から測り直しました。同じ操作を60回繰り返すリクエストと、0回で素通しするリクエストを投げて、その差を60で割ります。7回の中央値です。 | サイズ | 旧 Shell | 新 Computer | | --- | ---: | ---: | | 1KB | 1.58ms | -0.75ms | | 100KB | 4.92ms | 0.80ms | | 1MB | 87.25ms | 6.45ms | 1KB と 100KB は結論を出せません。負の値が出ている通り、HTTP の往復のばらつきに埋もれています。 1MB では差が出ました。13.5倍です。旧 Shell は毎回 1MB を base64 に変換して1行に入れ、読むときに戻しているので、その分が乗ります。書きと読みは分離していません。どちらが遅いかまでは言えません。 7. 帰結④：content-addressed なので、重複排除が効く 新は blob の主キーが sha256 です。同じバイト列はツリーのどこにあっても1行を共有します。 512 KiB の同じ内容を2つのパスに書いて、vfs_blobs の行数を数えました。 blobs 初期 → 0 同じ内容を1パス目 → 1 同じ内容を2パス目 → 1 ← 増えない 対照: 違う内容 → 2 ← 増える 対照を置かないと「そもそも blob が増えない実装」と区別できないので、違うバイト列で2行になることも確認しています。 旧はパスごとに content を持つので、同じファイルを2箇所に置けば2回分の容量を使います。 8. 帰結⑤：メタデータの置き場が無くなった 旧の FileInfo は mimeType createdAt updatedAt を持っています。新の WorkspaceStatResult はこれだけです。 { name, inode, mode, mtime, size, isFile, isDirectory, isSymbolicLink } MIME を読み書きする API が、workspace.fs のどこにもありません。時刻も mtime の1本だけです。 移行ガイドも「保持されない」と書いています。 > Things the copy does not keep: > - created_at and modified_at. Computer stamps the time of the copy. > - mime_type. Computer does not store a MIME type per file. 実測でも、移行後の mtime は全件コピー実行時刻になっていました。「保持されない」というより、新スキーマに置く場所がありません。 9. 帰結⑥：前には進めるが、後ろには戻れない 新はスキーマにバージョンを持ちます。初期化のコードはこうです。 const onDiskVersion = db.one("SELECT v FROM vfs_meta WHERE k = ?", "schema_version")?.v ?? 0; if (onDiskVersion > 10) throw createWorkspaceError("EIO", `Unsupported workspace filesystem schema version ${onDiskVersion}`); if (onDiskVersion > 0 && onDiskVersion < 10) runMigrations(db, onDiskVersion, 10); 前方への移行は自動です。v1 から v10 まで、マイグレータが9本登録されています。 後方はありません。 実際に古い版をデプロイする代わりに、on-disk の schema_version を 11 に書き換えて「このバイナリより新しい DB」を作り、同じ構築経路を通しました。 schema_version（現在） → 10 対照: 同じ版で再構築 → {read: "hello"} schema_version を 11 に偽装 古いバイナリで開き直す → EIO Unsupported workspace filesystem schema version 11 schema_version を 10 に戻す 戻したら開けるか → {read: "hello"} 測ったのは「on-disk の schema_version がバイナリの対応版より新しいと EIO で開けない」ことです。これが「古い版にロールバックできない」を意味するのは、新しい版がスキーマを上げた場合に限ります。過去に9回上げているので、次も上がると見るのが自然です。 移行ガイドにも Changelog にも、この記述はありません。実装ドキュメントの 03_filesystem_schema.md に1行あるだけです。 > Open() refuses to run if the binary is older than the on-disk schema_version. 旧データは残るので、移行に失敗しても最悪は旧テーブルから読み直せます。戻れないほうは取り返しがつきません。 10. 移行ガイドのスクリプトを流す 構造の違いは分かりました。実際に移します。 移行ガイドに copyShellWorkspace() というコピー用のコードが載っています。旧を glob("/**") で歩いて、新の fs に書き直すだけのものです。移行先は /workspace 配下で、Think もそこを作業ディレクトリとして使います。 手を入れずにそのまま流しました。題材は、UTF-8 の日本語を含むテキスト、ネストしたディレクトリに置いた TypeScript、内容の完全一致を見るための JSON、決定的な疑似乱数で生成した 64KB のバイナリ、中身を持たない空ディレクトリ、そして相対・絶対・ルート超えを撃ち分けたシンボリックリンク4本です。 comparison → { total: 13, missing: [], typeChanged: [], contentMismatch: [], extra: [] } 13件すべて存在し、型も変わらず、64KB のバイナリも SHA-256 が一致しています。空ディレクトリも残りました。ローカルの wrangler dev でも、デプロイした本番でも同じ結果です。 ハッシュ比較が機能していることも確認しました。1ビットだけ変えたバイト列を用意して、ハッシュが別物になることを見ています。af2ba40f… と 73734ea1… です。比較が不一致を検出できないまま「一致した」と言っても、何も示したことになりません。 スクリプトが暗黙に頼っている前提も確かめました。コードのコメントに「glob returns rows ordered by path, so parents come before children」とあります。これが崩れると mkdir の前に writeFile が走ります。実測では辞書順でソートされていて、親は必ず子より先に来ていました。 ハマりポイント：シンボリックリンクだけ、別の扱いが要る リンクを個別に辿ってみると、1本だけ落ちました。 | リンク | Shell でのリンク先 | 移行後のリンク先 | 辿れるか | | --- | --- | --- | --- | | /links/rel.md | ../notes.md | /workspace/notes.md | 辿れる | | /links/abs.md | /notes.md | /workspace/notes.md | 辿れる | | /links/dotdot.md | /src/../notes.md | /workspace/src/../notes.md | 辿れる | | /links/esc.md | /../notes.md | /workspace/../notes.md | ENOENT | /workspace/../notes.md は /notes.md に解決されます。移行先の /workspace の外です。 原因はスクリプトの resolveTarget() にあります。 // Shell resolves a relative target against the link's directory and never // goes above `/`. function resolveTarget(link: string, target: string): string { if (target.startsWith("/")) return target; // 絶対パスは素通し const parts = link.split("/").slice(1, -1); for (const part of target.split("/")) { if (part === "..") parts.pop(); else if (part !== "" && part !== ".") parts.push(part); } return `/${parts.join("/")}`; } @cloudflare/shell の本体（resolveSymlink）は、絶対パスも normalizePath に通します。normalizePath は .. をルートで止めるので、Shell にとって /../notes.md は /notes.md です。スクリプトはそれを素通しするので、/workspace を前置したときに外へ出ます。 条件は狭いです。相対パスは全件正しく、. や // を含む絶対パスも、ルートを超えない .. を含む絶対パスも正しく移ります。崩れるのは「絶対パスで、かつルートより上に登る .. を含む」場合だけです。 そして、これはエラーになりません。symlink() はリンク先を検証せずに保存し、辿るときも例外を投げずルートで止まります。POSIX のダングリングリンクが合法なのと同じです。コピーは正常終了します。 パス・型・ハッシュの照合では捕まりません。 リンクは存在するので欠落にならず、型は symlink のままなので型違いにもならず、中身を持たないのでハッシュ比較の対象にすら入りません。実際、私の照合スクリプトも missing: [], contentMismatch: [] を返しました。確かめるなら、辿って読むしかありません。 await to.fs.readFile(linkPath, "utf8"); // 辿れなければ ENOENT もう1つ、再実行も止まります。 1回目の移行 → ok 2回目の移行 → EEXIST path exists: /workspace/links/abs.md mkdir({ recursive: true }) は既存ディレクトリなら黙って返ります。writeFile は exclusive を指定しない限り上書きします。symlink(target, path) には force に相当するオプションがなく、パスが既にあれば必ず EEXIST を投げます。Node の fs.symlink と同じ挙動で、ライブラリ側のバグではありません。 ガイドの onStart の例はコピー完了後にフラグを立てるので、途中で落ちるとフラグが立たず、起動のたびに同じリンクで失敗します。張る前に消せば済みます。 const link = at(entry.path); if (await to.fs.readlink(link).then(() => true, () => false)) { await to.fs.rm(link); } await to.fs.symlink(at(target), link); この2点は cloudflare/agents#2645 に出しました。出す前に重複を調べたら、どちらも過去のレビューで指摘されていました。片方は PR の差し替えで引き継がれず、もう片方は「絶対パスは既に rebase されている」という誤った前提のまま解決済みになっていました。新発見として書かずに済んだのは、調べたからです。 シンボリックリンクを含まない Workspace なら、ここは踏みません。 11. 永続化は保たれている 保存形式が変わっても、Durable Object の SQLite に載っている点は同じです。再起動をまたいで残るかを確かめました。 「別のリクエストから読めた」だけでは証拠になりません。同じインスタンスがメモリに残っていて、そこから返しただけかもしれないからです。コンストラクタで crypto.randomUUID() を1つ生成して、レスポンスに載せました。値が変わっていれば、新しい incarnation です。 bootId 読めたか ① 書く 1cadfbdd-7595-4879-94c1-43abca4688c0 ok ② 直後に読む 1cadfbdd-7595-4879-94c1-43abca4688c0 ok ← 同じ ③ 15秒後 e4f5f2ab-3d7d-4389-8e2d-ee32fdd97b02 ok ← 変わった ④ 150秒後 c602f7f1-c9f6-465e-9b36-0c3259706d64 ok ← また変わった ③と④は別の incarnation から読めています。④の中身には書いたときの古い bootId が入っていたので、同じデータだと示せます。 記録するフィールドは最初から決めておきました。判定を書き戻すための C 番号、再起動の有無を示す bootId、ローカルか本番かを示す env、ファイルの同一性を示す sha256 と size、操作そのものにかかった時間、そして例外を投げずに結果として持つ ok と error です。 この対照は実際に仕事をしました。再デプロイ後に読めるかを試したとき、1回目は待たずに読んで成功したのですが、bootId が同じでした。DO は旧コードのままメモリに居座っていて、再起動していません。対照が無ければ「再デプロイしても残る」と書いて終わっていました。15秒待ってから取り直して、bootId が変わったうえで読めることを確認しています。 計測：hibernate は何秒か 待ち時間を変えて bootId を見ました。対照は待ち0秒です。 待ち(s) 再起動 読めた 0 しない ok ← 対照 3 しない ok 6 しない ok 9 しない ok 11 する ok 13 する ok 15 する ok 境界は9秒と11秒の間にあります。ドキュメントの「無活動10秒で hibernate」と一致しました。 12. 移行する前にやること - シンボリックリンクがあるか数える。 glob("/**") して type === "symlink" を数えるだけです。0本なら公式スクリプトをそのまま使って構いません - リンクがあるなら、移行後に辿って読む。 パス・型・ハッシュの照合では捕まりません - 6 MiB を超えるファイルがないか確認する。 旧で R2 に逃がしていたなら、移行時も同じ r2 と name を渡します - 古い実装に戻せない前提でデプロイする。 新スキーマを一度書いたら、その Durable Object は古い @cloudflare/computer では開けません - 旧データはすぐ消さない。 旧テーブルは残るので、照合が終わるまで DROP TABLE を待ちます 依存の形も変わっています。旧 @cloudflare/think@0.20.2 では @cloudflare/shell が直接依存で、自分でインストールするものではありませんでした。0.21.0 では @cloudflare/computer が peer dependency になります。「上げたら Workspace が空になった」が起きる構造が、ここにそのまま出ています。 13. まとめ 変わったのは保存形式です。そこから全部が導けました。 - テーブルが別 → 移行せずに切り替えると見えない。ただし旧テーブルは残り、旧 Workspace からは読める - 1行に全部入れる / チャンクに割る → 旧は約 6 MiB で頭打ち。新は 32MB でも通る - 毎回 base64 に変換する → 1MB の読み書きで 13.5 倍の差 - blob が content-addressed → 同じ内容を2箇所に置いても1行で済む - メタデータの列が減った → mime_type と created_at は置く場所がない - スキーマにバージョンがある → 前には自動で進み、後ろには戻れない 移行ガイドは「テーブルが違うので手でコピーしてください」としか書いていません。違うのはテーブル名ではなく構造のほうで、そこを見ておくと、移行のときに何を確かめればいいかが先に分かります。 ドキュメントとずれていた点も2つ出ました。Durable Object SQLite の値の上限は 2 MB ではなく 8 MiB でしたし、新スキーマを書いた Durable Object が古い実装で開けないことは、ユーザー向けのどこにも書かれていません。 一番こたえたのは、4MB が通ったところです。公式の数字から予測を立てて、外しました。前提を公式に置いていたぶん、崩れたときに他の予測まで信用できなくなって、上限も速度も結局は自分で測り直しています。移行そのものより、そっちに時間を使いました。 参考 - Think agents now use a @cloudflare/computer workspace — 切り替えの告知。自動移行が無いことと createExecuteTool の非推奨 - Migrating from @cloudflare/shell to @cloudflare/computer — 新旧両方の DDL と、10章で流したコピースクリプト - cloudflare/computer docs/03_filesystem_schema.md — vfs_* の全テーブル定義。チャンクサイズとスキーマバージョンの扱い - Durable Objects — Limits — 行サイズ 2 MB の記載元。5章で突き合わせた相手 - Durable Objects — Lifecycle — hibernate 10秒、eviction 70〜140秒の出典 - cloudflare/computer#217 / #219 — R2 への書き出しと namespace が未対応であることの自己申告 - cloudflare/agents#2645 — 10章のシンボリックリンクの件を報告したもの
@jhleath @yourclouddude niiiiiice something like this, but a real file system would go crazy github.com/cloudflare/computer/blob/main/packages…
@jhleath Cloudflare released cloudflare/computer that uses their isolates concept to apply your workspaces idea