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. All four SDKs expose configuration for local files, S3-compatible object storage, and an optional HTTP/JSON remote git provider. Go uses value configurations where Node.js and Python use backend objects.

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 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.

Rust

Node.js

Python

Rust

use a3s_code_core::{Agent, SessionOptions, WorkspaceServices};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let backend = WorkspaceServices::local("/repo");
    let session = agent
        .session_builder("/repo")
        .options(SessionOptions::new().with_workspace_backend(backend))
        .build()
        .await?;

    println!("{}", session.read_file("Cargo.toml").await?);

    session.close().await;
    agent.close().await;
    Ok(())
}

The workspace path already selects the default local backend. Use WorkspaceBackendConfig when one option shape must cover local and remote sessions:

package main

import (
	"context"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(ctx)

	session, err := agent.Session(ctx, "/repo", &code.SessionOptions{
		WorkspaceBackend: &code.WorkspaceBackendConfig{
			Kind: "local",
			Root: "/repo",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(ctx)

	content, err := session.ReadFile(ctx, "go.mod", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(content)
}

S3 Backend

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

Rust

Node.js

Python

The Rust crate must be built with its s3 feature.

Rust

use std::env;

use a3s_code_core::{Agent, S3BackendConfig, SessionOptions, WorkspaceServices};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let bucket = env::var("WORKSPACE_S3_BUCKET")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let access_key = env::var("S3_ACCESS_KEY_ID")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let secret_key = env::var("S3_SECRET_ACCESS_KEY")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;

    let mut config =
        S3BackendConfig::new(bucket, "sessions/example", access_key, secret_key)
            .region(env::var("WORKSPACE_S3_REGION").unwrap_or_else(|_| "us-east-1".into()))
            .force_path_style(true)
            .enable_search(false);
    if let Ok(endpoint) = env::var("WORKSPACE_S3_ENDPOINT") {
        config = config.endpoint(endpoint);
    }

    let agent = Agent::new("agent.acl").await?;
    let session = agent
        .session_builder("s3://workspace-bucket/sessions/example")
        .options(
            SessionOptions::new().with_workspace_backend(WorkspaceServices::s3(config)),
        )
        .build()
        .await?;

    println!("{}", session.read_file("README.md").await?);

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

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,
});

Python

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)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(ctx)

	forcePathStyle := true
	searchEnabled := false
	session, err := agent.Session(
		ctx,
		"s3://workspace-bucket/sessions/example",
		&code.SessionOptions{
			WorkspaceBackend: &code.WorkspaceBackendConfig{
				Kind: "s3",
				S3: &code.S3BackendConfig{
					Endpoint:        os.Getenv("WORKSPACE_S3_ENDPOINT"),
					Region:          os.Getenv("WORKSPACE_S3_REGION"),
					AccessKeyID:     os.Getenv("S3_ACCESS_KEY_ID"),
					SecretAccessKey: os.Getenv("S3_SECRET_ACCESS_KEY"),
					Bucket:          os.Getenv("WORKSPACE_S3_BUCKET"),
					Prefix:          "sessions/example",
					ForcePathStyle:  &forcePathStyle,
					SearchEnabled:   &searchEnabled,
				},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(ctx)

	content, err := session.ReadFile(ctx, "README.md", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(content)
}

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.

Go exposes the same fields on S3BackendConfig: Bucket, Prefix, AccessKeyID, SecretAccessKey, Endpoint, Region, SessionToken, ForcePathStyle, MaxReadBytes, SearchEnabled, MaxObjectsScanned, MaxGrepBytesPerObject, and SearchConcurrency.

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.

Rust

Node.js

Python

Rust

use std::env;

use a3s_code_core::{
    Agent, RemoteGitBackendConfig, S3BackendConfig, SessionOptions, WorkspaceServices,
};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let bucket = env::var("WORKSPACE_S3_BUCKET")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let access_key = env::var("S3_ACCESS_KEY_ID")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let secret_key = env::var("S3_SECRET_ACCESS_KEY")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let base_url = env::var("REMOTE_GIT_BASE_URL")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;
    let token = env::var("REMOTE_GIT_TOKEN")
        .map_err(|error| a3s_code_core::CodeError::Config(error.to_string()))?;

    let storage = WorkspaceServices::s3(S3BackendConfig::new(
        bucket,
        "sessions/example",
        access_key,
        secret_key,
    ));
    let backend = storage.with_remote_git(
        RemoteGitBackendConfig::new(base_url, "sessions/example").bearer_token(token),
    )?;

    let agent = Agent::new("agent.acl").await?;
    let session = agent
        .session_builder("s3://workspace-bucket/sessions/example")
        .options(SessionOptions::new().with_workspace_backend(backend))
        .build()
        .await?;

    let status = session
        .tool("git", serde_json::json!({ "command": "status" }))
        .await?;
    println!("{}", status.output);

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

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,
  },
});

Python

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)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	code "github.com/A3S-Lab/Code/sdk/go/v6"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(ctx)

	forcePathStyle := true
	session, err := agent.Session(
		ctx,
		"s3://workspace-bucket/sessions/example",
		&code.SessionOptions{
			WorkspaceBackend: &code.WorkspaceBackendConfig{
				Kind: "s3",
				S3: &code.S3BackendConfig{
					Endpoint:        os.Getenv("WORKSPACE_S3_ENDPOINT"),
					Region:          os.Getenv("WORKSPACE_S3_REGION"),
					AccessKeyID:     os.Getenv("S3_ACCESS_KEY_ID"),
					SecretAccessKey: os.Getenv("S3_SECRET_ACCESS_KEY"),
					Bucket:          os.Getenv("WORKSPACE_S3_BUCKET"),
					Prefix:          "sessions/example",
					ForcePathStyle:  &forcePathStyle,
				},
			},
			RemoteGit: &code.RemoteGitBackendConfig{
				BaseURL:     os.Getenv("REMOTE_GIT_BASE_URL"),
				RepoID:      "sessions/example",
				BearerToken: os.Getenv("REMOTE_GIT_TOKEN"),
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(ctx)

	status, err := session.Git(ctx, code.GitOptions{Command: "status"})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(status.Output)
}

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.

Go exposes the same fields on RemoteGitBackendConfig: BaseURL, RepoID, BearerToken, ClientCertPEM, ClientKeyPEM, RequestTimeoutMS, MaxDiffBytes, and MaxLogEntries.

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.

#Workspace Backends

#Capability Matrix

#Local Backend

#S3 Backend

#S3 Options

#Remote Git

#Remote Git Options

#Choosing A Backend

Workspace Backends

Capability Matrix

Local Backend

S3 Backend

S3 Options

Remote Git

Remote Git Options

Choosing A Backend