@morphixai/agent-workspace

Sandbox — the restricted operating environment an agent instance is constructed with — plus the storage ports it builds on.

An agent never touches host storage directly: every file/data operation goes through its injected Sandbox. Two instances with different sandboxes are mutually unreachable by construction (the isolation is structural, not policy-based).

Install

npm install @morphixai/agent-workspace

Sandbox hierarchy

import { Sandbox, VirtualSandbox, LogicalSandbox } from '@morphixai/agent-workspace';

// zero-dependency, in-memory — tests / demos / ephemeral agents
const sandbox = new VirtualSandbox();
await sandbox.files.write('report.md', '# Draft');

// production: subclass LogicalSandbox and bind real adapters at construction
class AppSandbox extends LogicalSandbox {
  constructor(deps: { cos: CosClient; appData: AppDataService }) {
    super({ files: cosFilePort(deps.cos), data: appDataPort(deps.appData) });
  }
}

• Sandbox (abstract) — implements the Workspace contract; declares its isolation level: virtual | logical | process | container.
• VirtualSandbox — in-memory, zero deps. The default for tests and demos.
• LogicalSandbox — construction-bound ports over your real storage (object storage, DB, …). Per-app/per-user boundaries live in the adapters.

Lifecycle note: disposing an agent instance does not drop its sandbox — sandboxes are host-owned and may outlive (or be shared across) instances the host constructs.

Storage ports

Backing stores usable standalone or inside a sandbox:

• InMemoryStore — in-memory backing store.
• JsonFileStore — file-backed store (handy for local persistence in tests).
• Types: Workspace, WorkspaceContent, WorkspaceEntry, WorkspaceKind, CommitTarget, WorkspaceError / WorkspaceErrorCode.

Pairs with @morphixai/agent-framework (instances are constructed with a sandbox) but is usable standalone.

Versioning

≥ 1.0.0 is the framework-v2 stable line, released in lockstep with agent-core / agent-bus / agent-framework. The pre-1.0 "runtime-private staging workspace" framing evolved into the Sandbox model above.

License

MIT © MorphixAI