#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. Rust hosts can also supply their own backend by implementing the workspace traits; see Host-provided Backend.

#Feature Flags

The local backend and remote git are always compiled in. The S3 backend is behind the Cargo feature s3, which the server and full features include (core/Cargo.toml); the Core default feature set is local-code only.

#Capability Matrix

download is registered only for a writable local root. code_symbols, code_navigation, and code_diagnostics are registered only when the backend carries a code-intelligence provider; the default local backend has none.

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.

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(())
}

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)

package main

import (
	"context"
	"fmt"
	"log"

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

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

#Local download sink

A writable local backend also registers download. The tool accepts a public HTTP(S) url and writes only to a workspace-relative file_path; omitting the path produces a sanitized inferred filename. It is absent from S3 and other non-local backends because atomic adjacent temporary files, cancellation cleanup, symlink checks, and final promotion require local filesystem semantics.

overwrite defaults to false. Transfers default to a 512 MiB max_bytes limit and a 300-second timeout, with hard limits of 8 GiB and 3600 seconds. Range concurrency is adaptive or explicitly bounded to 1–4 connections, and expected_sha256 can require a 64-character hexadecimal digest before the destination is promoted. See Tools for transport and metadata details.

#S3 Backend

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

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(())
}

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)

package main

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

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

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

Go exposes the same fields on S3BackendConfig: Bucket, Prefix, AccessKeyID, SecretAccessKey, Endpoint, Region, SessionToken, ForcePathStyle, MaxReadBytes, SearchEnabled, MaxObjectsScanned, MaxGrepBytesPerObject, and SearchConcurrency. Go additionally accepts RequestTimeoutMS, a per-request S3 timeout that the Node.js and Python backends do not expose.

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

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(())
}

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)

package main

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

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

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

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

#Host-provided Backend

A Rust host can back a session with its own storage by implementing WorkspaceFileSystem (read_text, write_text, list_dir) and, optionally, WorkspaceCommandRunner, WorkspaceSearch, and WorkspaceGit. The traits are Send + Sync and exported from the crate root. WorkspaceServices::builder starts with read and write capabilities; each attached service enables the matching capability and tools.

use std::sync::Arc;

use a3s_code_core::{SessionOptions, WorkspaceFileSystem, WorkspaceRef, WorkspaceServices};

fn host_backend(files: Arc<dyn WorkspaceFileSystem>) -> SessionOptions {
    let services = WorkspaceServices::builder(
        WorkspaceRef::new("tenant-42/workspace", "/workspace"),
        files,
    )
    .build();
    SessionOptions::new().with_workspace_backend(services)
}

Attach .command_runner(...) for bash, .search(...) for search, .git(...) for git, and .code_intelligence(...) for the code-intelligence tools. A non-local backend keeps its own command runner: the native Bash sandbox applies only to local workspaces, so the host is responsible for confining commands it runs. Effect isolation never reuses a host-provided backend. The Node.js, Python, and Go SDKs do not expose custom backends.

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