Workspace
The workspace library gives an agent access to files and shell commands. Its implementation can use a virtual filesystem or a real computer.
Methods
| Method | Inputs | Description |
|---|---|---|
bash | command | Execute a shell command. |
read | path, offset?, limit? | Read file content or a range of lines. |
write | path, content | Create or overwrite a file. |
edit | path, oldText, newText | Replace one exact occurrence of text. |
Agent usage
agent.ts
import { Effect } from "effect"
import { Agent } from "tardie/agent"
import { Actor } from "tardie/core"
import { workspace } from "tardie/libraries"
const program = Effect.gen(function* () {
const tools = yield* Agent.tools([workspace])
const context = yield* Agent.compact(Agent.messages)
return yield* Agent.make({
system: "Use the workspace to read files and run commands.",
tools,
context,
})
})
export const assistant = Actor.make("assistant", program)
Local
Real filesystem
Use Bun with the local filesystem and shell:
workspace.ts
import { localWorkspace } from "tardie/platform/bun"
export const workspace = localWorkspace({
directory: "./workspace",
policy: {
commandTimeoutMs: 30_000,
maxOutputChars: 32_768,
maxReadChars: 32_768,
},
})
Virtual filesystem
Use Bun to persist a virtual filesystem in SQLite:
workspace.ts
import { virtualWorkspace } from "tardie/platform/bun"
export const workspace = virtualWorkspace({
filename: ".tardigrade/workspace.sqlite",
name: "agent-workspace",
directory: "/workspace",
network: { mode: "none" },
policy: { maxFileBytes: 8 * 1024 * 1024 },
})
Remote
Virtual filesystem
Use the current Cloudflare Durable Object's SQLite storage for a virtual workspace:
workspace.ts
import { Effect, Layer } from "effect"
import { DurableStorage, virtualWorkspace } from "tardie/platform/cloudflare"
export const workspace = Layer.unwrap(Effect.map(DurableStorage, storage =>
virtualWorkspace(storage, {
name: "agent-workspace",
directory: "/workspace",
network: { mode: "none" },
policy: { maxFileBytes: 8 * 1024 * 1024 },
}),
))
Real filesystem
Use a Cloudflare container, with a sandbox named for the current thread:
sandbox.ts
import { createWorkspaceObject } from "tardie/platform/cloudflare"
export const Sandbox = createWorkspaceObject({
directory: "/workspace",
network: { mode: "none" },
start: (_env, container) => ({ image: container.images.current! }),
})
workspace.ts
import { Effect, Layer } from "effect"
import { Bindings, HostThread, remoteWorkspace, workspaceObjectName } from "tardie/platform/cloudflare"
import type { Sandbox } from "./sandbox"
interface Env {
readonly SANDBOX: DurableObjectNamespace<InstanceType<typeof Sandbox>>
}
export const workspace = Layer.unwrap(Effect.gen(function* () {
const env = yield* Bindings<Env>()
const thread = yield* HostThread
return remoteWorkspace(env.SANDBOX.getByName(workspaceObjectName(thread)))
}))
See container workspace setup for the image and Wrangler bindings.
Host wiring
Supply the chosen workspace layer alongside your model layer:
worker.ts
import { Layer } from "effect"
import { host } from "tardie/platform/cloudflare"
import { assistant } from "./agent"
import { model } from "./model"
import { workspace } from "./workspace"
const worker = host(assistant, {
layer: Layer.mergeAll(model, workspace),
})
export const ActorDO = worker.ActorObject
export const ThreadDO = worker.ThreadObject
export default worker
For the container backend, also export the sandbox from the Worker entrypoint:
worker.ts
export { Sandbox } from "./sandbox"
For Bun host wiring, see Run locally. To define your own service and library, see the concept walkthrough.