Run A3S Code sessions against local files, S3-compatible object storage, and remote git services.

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

Backend	File tools	Search tools	Shell and local git
Default local workspace	`read`, `write`, `edit`, `patch`, `ls`	`grep`, `glob`	`bash`, `git`
`LocalWorkspaceBackend`	Same as default local workspace	Same as default local workspace	Same as default local workspace
`S3WorkspaceBackend`	`read`, `write`, `edit`, `patch`, `ls`	Optional degraded `grep` / `glob` when `searchEnabled` is set	Not registered
`S3WorkspaceBackend` + `remoteGit`	S3 file tools	Optional degraded S3 search	`git` through remote git, no `bash`

Object storage cannot service local processes. Do not promise shell execution on an S3 workspace unless the host provides a separate sandbox through AHP, 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

Node.js option	Python option	Required	Purpose
`bucket`	`bucket`	yes	S3 bucket that stores the workspace objects.
`prefix`	`prefix`	yes	Logical workspace root inside the bucket; use `""` for the bucket root.
`accessKeyId`	`access_key_id`	yes	Access key id, normally read from the host environment.
`secretAccessKey`	`secret_access_key`	yes	Secret access key, normally read from the host environment or a secret manager.
`endpoint`	`endpoint`	no	Custom S3-compatible endpoint; omit for AWS S3 defaults.
`region`	`region`	no	Region, defaulting to `us-east-1` when omitted.
`sessionToken`	`session_token`	no	STS session token when temporary credentials are used.
`forcePathStyle`	`force_path_style`	no	Set `true` for MinIO, RustFS, and most non-AWS endpoints.
`maxReadBytes`	`max_read_bytes`	no	Per-read size ceiling; defaults to 10 MiB.
`searchEnabled`	`search_enabled`	no	Enables degraded S3 `grep` / `glob`; defaults to false.
`maxObjectsScanned`	`max_objects_scanned`	no	Per-search object scan cap; used only when search is enabled.
`maxGrepBytesPerObject`	`max_grep_bytes_per_object`	no	Per-object download cap for `grep`; used only when search is enabled.
`searchConcurrency`	`search_concurrency`	no	Concurrent object downloads during `grep`; used only when search is enabled.

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

Node.js option	Python option	Required	Purpose
`baseUrl`	`base_url`	yes	Remote git service base URL, without a trailing slash.
`repoId`	`repo_id`	yes	Opaque repository id negotiated with the remote git service.
`bearerToken`	`bearer_token`	production	Bearer credential for the remote git service; omit only in trusted development setups.
`clientCertPem`	`client_cert_pem`	no	mTLS client certificate path; must be paired with the client key.
`clientKeyPem`	`client_key_pem`	no	mTLS client key path; must be paired with the certificate.
`requestTimeoutMs`	`request_timeout_ms`	no	Per-call HTTP timeout in milliseconds; defaults to 30000.
`maxDiffBytes`	`max_diff_bytes`	no	Client-side cap on `diff` response bytes; defaults to 1 MiB.
`maxLogEntries`	`max_log_entries`	no	Client-side cap on `log` entries; defaults to 200.

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 AHP, MCP, or A3S Box for shell-like execution that cannot run inside the selected workspace backend.

Workspace Backends

On this page