Shell workspaces

Files and state

Despite its name, this package's execution model is JavaScript with structured filesystem operations. It does not provide a Bash interpreter. Its package guide describes StateBackend, filesystem implementations, and the stateTools integration with Code Mode.

Choose an in-memory filesystem for disposable work, or a Workspace backed by the Durable Object's SQLite storage for files that must survive another request. The example below stores Markdown drafts in the latter.

Drafts Folder

Workspace from @cloudflare/shell is a file system stored in the Durable Object's SQLite database. On a PUT, the object saves the request body as a Markdown file at the request path, and every response lists the .md files with their sizes.

open Fable.Core

module Workers = FSharp.CloudEdge.Runtime.Workers
module Runtime = FSharp.CloudEdge.Runtime.Workers.Cloudflare.Workers
module Shell = FSharp.CloudEdge.Runtime.Shell

type DraftsFolder(ctx: Workers.DurableObjectState<obj>, env: obj) =
    inherit Runtime.DurableObject<obj, obj>(ctx, env)

    let workspace = Shell.Exports.Workspace(Shell.WorkspaceOptions.Create(sql = ctx.storage.sql))

    interface Runtime.DurableObject.IFetchHandler with
        member _.fetch request =
            async {
                let path = Workers.Exports.URL(U2.Case1 request.url).pathname
                if request.``method`` = "PUT" then
                    let! text = request.text () |> Async.AwaitPromise
                    do! workspace.writeFile (path, text, "text/markdown") |> Async.AwaitPromise
                let! drafts = workspace.glob "/**/*.md" |> Async.AwaitPromise
                let listing = drafts |> Array.map (fun draft -> {| path = draft.path; size = draft.size |})
                return Workers.Exports.Response.json listing
            }
            |> Async.StartAsPromise
            |> U2.Case1

Expose files to an agent

stateTools(workspace) provides file operations to Code Mode. The host owns the workspace and supplies the provider; generated code operates through the exposed state API. Use Git tools when those files also need commits, branches, and remote synchronization.

Workspace persistence and version history serve different purposes. Saving a draft makes the current file durable. Committing it records a revision. Pushing that revision to Artifacts makes it available independently of this workspace.

Choosing between Shell and Computer

Shell supplies state backends and Code Mode providers. Computer provides a workspace filesystem with a configurable execution backend. Choose the API around how the agent will interact with its files; both deserve an explicit storage and ownership decision.

Related Pages

• Code Mode
• Git tools
• Computer workspaces

Testing and feedback

Useful test cases include persistence across Durable Object restarts, file metadata, filesystem adapters, and state-tool arguments and results.

Verify bindings explains how to run checks and report an issue. Include a small reproduction and the package versions used; working examples are welcome too.

NuGet packages

Runtime.Shell 0.1.0, Runtime.ShellGit 0.1.0, Runtime.Workers 0.1.0.

See installation and release availability.