#Workspace Backends

Workspace backends decide where built-in workspace tools read and write files. The default is the local filesystem rooted at the session workspace. The SDKs also expose typed backends for local files, S3-compatible object storage, and an optional HTTP/JSON remote git provider.

Use this surface when the host owns workspace placement: local development, browser or container workspaces, object-storage workspaces, or managed sessions.

#Capability Matrix

Object storage cannot service local processes. Do not promise shell execution on an S3 workspace unless the host provides a separate sandbox through MCP or A3S Box.

#Local Backend

The explicit local backend is useful when host code wants one option surface for both local and remote sessions.

import { Agent, LocalWorkspaceBackend } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = agent.session('/repo', {
  workspaceBackend: new LocalWorkspaceBackend('/repo'),
});

from a3s_code import Agent, LocalWorkspaceBackend, SessionOptions

agent = Agent.create("agent.acl")
opts = SessionOptions()
opts.workspace_backend = LocalWorkspaceBackend("/repo")
session = agent.session("/repo", opts)

#S3 Backend

S3WorkspaceBackend points the built-in file tools at any S3-compatible service, including AWS S3, MinIO, RustFS, Cloudflare R2, and Backblaze B2.

import { Agent, S3WorkspaceBackend } from '@a3s-lab/code';

const backend = new S3WorkspaceBackend({
  endpoint: process.env.WORKSPACE_S3_ENDPOINT,
  region: process.env.WORKSPACE_S3_REGION ?? 'us-east-1',
  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  bucket: process.env.WORKSPACE_S3_BUCKET!,
  prefix: 'sessions/example',
  forcePathStyle: true,
  searchEnabled: false,
});

const agent = await Agent.create('agent.acl');
const session = agent.session('s3://workspace-bucket/sessions/example', {
  workspaceBackend: backend,
});

import os

from a3s_code import Agent, S3WorkspaceBackend, SessionOptions

agent = Agent.create("agent.acl")
opts = SessionOptions()
opts.workspace_backend = S3WorkspaceBackend(
    bucket=os.environ["WORKSPACE_S3_BUCKET"],
    prefix="sessions/example",
    access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    endpoint=os.environ.get("WORKSPACE_S3_ENDPOINT"),
    region=os.environ.get("WORKSPACE_S3_REGION", "us-east-1"),
    force_path_style=True,
    search_enabled=False,
)
session = agent.session("s3://workspace-bucket/sessions/example", opts)

S3 search is intentionally opt-in. When enabled, grep / glob degrade to object listing and bounded downloads. Configure maxObjectsScanned, maxGrepBytesPerObject, and searchConcurrency when the bucket can be large or the endpoint rate-limits.

#S3 Options

#Remote Git

remoteGit attaches an HTTP/JSON git provider on top of workspaceBackend. It is designed for non-local workspaces where the built-in git tool cannot use a local .git directory.

remoteGit requires workspaceBackend; passing it alone is rejected.

import { Agent, S3WorkspaceBackend } from '@a3s-lab/code';

const backend = new S3WorkspaceBackend({
  endpoint: process.env.WORKSPACE_S3_ENDPOINT,
  region: process.env.WORKSPACE_S3_REGION ?? 'us-east-1',
  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  bucket: process.env.WORKSPACE_S3_BUCKET!,
  prefix: 'sessions/example',
  forcePathStyle: true,
});

const agent = await Agent.create('agent.acl');
const session = agent.session('s3://workspace-bucket/sessions/example', {
  workspaceBackend: backend,
  remoteGit: {
    baseUrl: process.env.REMOTE_GIT_BASE_URL!,
    repoId: 'sessions/example',
    bearerToken: process.env.REMOTE_GIT_TOKEN,
  },
});

import os

from a3s_code import (
    Agent,
    RemoteGitBackendConfig,
    S3WorkspaceBackend,
    SessionOptions,
)

agent = Agent.create("agent.acl")
opts = SessionOptions()
opts.workspace_backend = S3WorkspaceBackend(
    bucket=os.environ["WORKSPACE_S3_BUCKET"],
    prefix="sessions/example",
    access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    endpoint=os.environ.get("WORKSPACE_S3_ENDPOINT"),
    region=os.environ.get("WORKSPACE_S3_REGION", "us-east-1"),
    force_path_style=True,
)
opts.remote_git = RemoteGitBackendConfig(
    base_url=os.environ["REMOTE_GIT_BASE_URL"],
    repo_id="sessions/example",
    bearer_token=os.environ["REMOTE_GIT_TOKEN"],
)
session = agent.session("s3://workspace-bucket/sessions/example", opts)

Keep remote git credentials out of agent.acl and agent directories. Inject them from the host environment or secret manager.

#Remote Git Options

#Choosing A Backend

• Use the default local workspace for normal developer machines and CI checkouts.
• Use LocalWorkspaceBackend when your host always passes a typed backend object.
• Use S3WorkspaceBackend when workspace state must live in object storage.
• Add remoteGit when a non-local workspace still needs the built-in git tool.
• Use MCP or A3S Box for shell-like execution that cannot run inside the selected workspace backend.