mount_config in Python or mountConfig in TypeScript. The SDK sends the mount specs to LangSmith and composes the required auth proxy rules for provider credentials.
Sandbox mounts require
langsmith[sandbox]>=0.8.16 for Python or langsmith>=0.7.10 for TypeScript. Context Hub mounts require langsmith[sandbox]>=0.11.0 for Python or langsmith>=0.8.11 for TypeScript.Configure mount paths
Each mount has anid, a type, and a mount_path / mountPath. Bucket and Git mounts must use an absolute path under /mnt/mounts. Context Hub mount paths can be any absolute path outside the system directories, so an agent can read its context from the location it already expects.
Use stable paths that describe the mounted source:
Mount IDs can contain ASCII letters, digits, underscores, and hyphens. Do not reuse an ID or mount path within the same sandbox.
Mount an S3 bucket
S3 mounts require AWS authentication. Use static access keys or an IAM role when your deployment and SDK support role authentication. The LangSmith UI also supports role setup. Both methods keep real AWS credentials outside the sandbox.Authenticate with static access keys
The SDK creates an AWS auth proxy rule fromaws_auth / awsAuth, so the sandbox can access the bucket without seeing the real access keys.
Authenticate with an IAM role
IAM role authentication lets the AWS auth proxy assume a role in your AWS account. S3 mounts use the same authentication as other supported AWS requests from the sandbox. LangSmith obtains and renews temporary AWS credentials, so you do not need to store or rotate access keys in workspace secrets.This option requires your LangSmith deployment to enable AWS proxy role authentication. Enabling IAM roles for ECR registries does not enable them for the auth proxy. If AWS IAM role is absent from the AWS authentication options, use static access keys or contact your LangSmith administrator. The role-based SDK examples require a release with
aws_auth(role_arn=...) and mount_config(proxy_config=...) in Python, or awsAuth({ roleArn }) and mountConfig({ proxyConfig }) in TypeScript. The mount versions listed at the top of this page do not establish support for these newer options.- Open Sandboxes > Create sandbox, add an S3 bucket in the Mounts section, and configure its bucket, region, prefix, mount path, and read-only setting.
- Go to the Network section, enable AWS authentication, and select AWS IAM role. To use the role without mounts, skip the mount configuration in step 1.
- Use the two values displayed below AWS role ARN in your IAM role’s trust policy:
- Principal: The exact AWS role ARN that this LangSmith deployment uses to assume customer roles. Use the displayed principal, not an ARN copied from another environment or from an ECR registry.
- External ID: Your current LangSmith workspace UUID. LangSmith supplies this value when assuming the role; you do not choose a separate external ID.
- Expand AWS role setup, select Copy trust policy, and apply that policy to the customer role in AWS IAM. It permits
sts:AssumeRoleonly for the displayed principal with the matchingsts:ExternalId. - Attach a least-privilege permissions policy for the AWS services and resources the sandbox needs. For configured S3 mounts, Copy S3 permissions supplies a starting policy. Review it before attaching it; LangSmith does not apply it automatically.
- Enter the customer role’s ARN in AWS role ARN. This is the role you configured in your account, not the LangSmith principal shown in the setup instructions.
- Select Create Sandbox, then verify that sandbox code can read the mounted path and, for writable mounts, write to it.
* or remove the external ID condition. Entering the customer role ARN in LangSmith does not create the role or update its AWS policies.
Limit S3 access
The optional S3 permissions example grants access based on the mount settings:- All S3 mounts: Bucket-location access, prefix-scoped listing, and object reads.
- Writable mounts: Additional object-write, delete, and multipart-upload permissions.
- Empty prefix: Object access throughout the bucket. Use a prefix to restrict access to a subtree.
Use a shared role in the SDK
A shared AWS proxy role authenticates both S3 mounts and supported application requests, just like the UI setup above. Configure the trust and permissions policies first, then replace the example role ARN and bucket with your own values. Pass the same proxy configuration to the mount helper and sandbox creation. The mount helper does not copy it into mount-specific authentication:Restrict a role to S3 mount scopes
Mount-specific role authentication adds a session policy that restricts AWS access to the configured S3 buckets, prefixes, and read-only settings. Use this API alternative when sandbox AWS access must stay within those mount scopes. The customer role still needs the trust and permissions policies described above. Pass the role inauth to serialize it as mount_config.auth.aws.role_arn. Do not also pass an AWS proxy rule:
mount_config.auth.aws API accepts either role_arn or the static access_key_id and secret_access_key pair, not both. It cannot be combined with an AWS proxy rule. Static-key examples earlier on this page continue to work unchanged.
Renew credentials
LangSmith renews temporary credentials as AWS requests need them, including after a sandbox stops and resumes. You do not supply a saved STS token or renew it manually. Keep the role’s trust and access permissions in place for continued access. If renewal is temporarily unavailable, the mount can use cached credentials only until they expire. An authorization denial or expired credentials causes authenticated S3 requests to fail; the mount does not fall back to static keys.Mount a GCS bucket
GCS mounts require GCP auth. The OAuth scope is supplied by the backend, derived from the mounts themselves: read-only mounts getdevstorage.read_only and writable mounts get devstorage.read_write.
Because a single mount_config resolves to one scope, all of its GCS mounts must agree: mixing read-only and writable GCS mounts in one config is rejected. Use writable mounts throughout, or create separate sandboxes.
Mount a public Git repository
Public Git mounts do not require AWS or GCP auth. Use an HTTPS remote URL and optionally pin a branch or tag.proxy_config / proxyConfig rules when the remote requires proxy-managed auth. There is not yet a high-level private Git auth helper.
Mount a Context Hub repo
A Context Hub mount mirrors the latest commit of an agent or skill repo into the sandbox filesystem. Use it to give sandbox code the same instructions, skills, and tools your production agents pull, without packaging them into the sandbox image or copying them in at startup. Identify the repo asowner/repo. Use - as the owner for a repo in the current workspace, such as -/my-agent. The caller’s API key must have read access to the repo. LangSmith rejects sandbox creation for a repo private to another workspace, and does not distinguish a missing repo from an inaccessible one. Context Hub mounts do not require AWS or GCP auth.
Read a repo as it changes
Context Hub mounts are read-only, and the sync is one-way. Files written under the mount path inside the sandbox are never pushed back to the repo, and the next refresh overwrites them. Write sandbox output to a path outside the mount, and push it with the Context Hub SDK when it belongs in the repo. LangSmith keeps the mount in sync for the sandbox’s lifetime. New commits reach a running sandbox within roughly 30 seconds. Treat that cadence as best effort rather than a freshness guarantee. A refresh replaces the whole tree at once, so a reader sees either the previous commit or the new one, never a mix. A mount always tracks the latest commit. To read a fixed version, pull the commit or environment tag you want with the Context Hub SDK instead of mounting the repo. Passinitial_pull_only / initialPullOnly to sync once at startup and then stop polling:
Handle startup and failures
The mount directory exists as soon as the sandbox is ready, but reads under it block until the first commit tree arrives. Code that reads the mount immediately at startup waits for the initial sync rather than seeing an empty directory. LangSmith retries a failed refresh and keeps serving the last commit it published, so a transient error does not empty a working mount. Two conditions do surface to sandbox code:- A rejected request: Reads fail with
EIO. Revoking the caller’s access to the repo after the sandbox starts rejects later pulls, because LangSmith re-checks access on every pull. - A repo that exceeds the sync limits: The mount serves no tree. A synced commit can hold at most 2,500 files and 25 MiB of file content, counting everything the repo links.
Combine mounts
A sandbox can mount multiple sources, including a Context Hub repo alongside bucket and Git mounts. Build onemount_config / mountConfig with all mount specs, and include provider auth for every bucket provider used by those specs.
Cache bucket mounts
S3 and GCS mounts support optional cache settings. Cache settings tune the local VFS cache used by the bucket mount; the bucket remains the source of truth. Use cache settings to control local disk usage and writeback timing, not as a separate persistence layer. Cache settings do not apply to Git mounts.
For read-only dataset mounts, configure
max_size_bytes only when you need a
specific local cache cap. For writable mounts, keep writeback_seconds low when
another process needs to read the objects from S3 or GCS soon after the sandbox
writes them.
Limits
- Mounts are attached when the sandbox is created. Create a new sandbox to change mounts.
- Configure each cloud provider’s credentials in one auth surface per sandbox. If mount auth supplies AWS or GCP credentials, do not also add an auth proxy rule for the same provider.
- Git refs can be omitted or set to a branch or tag. Commit refs are not supported.
- Git mounts do not support
read_only/readOnlyor cache settings. - Context Hub mounts are always read-only and do not support cache settings.
- Context Hub mounts accept agent and skill repos. LangSmith rejects other repo types and repos with no commits.
- A Context Hub mount path cannot be the filesystem root or sit at or under a system directory such as
/etc,/usr, or/var. - Restoring a sandbox reconnects each Context Hub mount at its configured path. A restored process that holds an open file or working directory inside the mount must reopen it.
Connect these docs to your agent of choice via MCP for real-time answers.

