Developer

Appearance

Resource Mounting

Resource Mounting ​

Resource mounting is an additional developer capability provided by the Sufy sandbox, suitable for securely using external resources in scenarios such as AI agents, code review, automated builds, and code migration.

When creating a sandbox, you can declare external resources to mount using the resources parameter:

ParameterCapabilityDescription
resourcesResource mountingThe platform prepares external resources before the sandbox starts and mounts them to a specified path inside the sandbox

Currently, resources supports GitHub repository resources. Credentials required to access external resources should be held by the platform as much as possible and not directly exposed to processes inside the sandbox.

Supported Resource Types ​

GitHub Repository Resource ​

The GitHub repository resource is used to pre-fetch a repository snapshot before the sandbox starts and mount it to a specified path inside the sandbox. It is suitable for scenarios such as code review, automated builds, and AI agent code modification.

FieldRequiredDescription
typeYesResource type; for GitHub repository resources, use github_repository
urlYesGitHub repository URL. Supports HTTPS URLs or GitHub SSH-style URLs like git@github.com:owner/repo.git. The platform will uniformly convert them to HTTPS for processing.
mount_pathYesMount path inside the sandbox. Must be an absolute path and must not be duplicated within the same sandbox.
authorization_tokenYesGitHub token for accessing the repository. Multiple GitHub repository resources within the same sandbox must currently use the same token.

If a github_repository resource is passed when creating a sandbox, the platform will use the authorization_token in the resource to pre-fetch the repository and automatically derive a runtime GitHub injection. Processes inside the sandbox do not need and cannot directly read the real token.

How It Works ​

text
Before sandbox starts:
External resource ── Platform prepares resource using credentials ── Mounts to mount_path inside sandbox

Core behaviors:

  • Resources are prepared before the sandbox starts; after startup, mount_path is directly accessible.
  • Credentials are held by the platform and do not enter the sandbox as environment variables, files, or command parameters.
  • For GitHub repository resources, a runtime GitHub injection is automatically derived, allowing subsequent git pull, git push, and other operations to continue authenticating.

When resources contains github_repository, do not explicitly pass injections with type: github. The server will automatically derive a GitHub injection based on the authorization_token. If you explicitly pass one, a 400 github_repository resources do not support explicit github injections error will be returned.

REST API Example ​

Create a sandbox and mount a GitHub repository resource:

bash
curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/owner/private-repo.git",
        "mount_path": "/workspace/repo",
        "authorization_token": "'"$GITHUB_TOKEN"'"
      }
    ]
  }'

Common Workflows ​

Start with Code ​

Suitable for code review, build testing, and repository content analysis:

  1. Pass a github_repository resource when creating a sandbox.
  2. The platform pre-fetches the repository and mounts it to mount_path.
  3. The agent runs tests, analyzes, or modifies code directly in the mounted directory.

Modify and Push Back to Repository ​

Suitable for automated fixes, batch migration, and documentation updates:

  1. Pass a github_repository resource when creating a sandbox.
  2. The agent modifies code in the mounted directory.
  3. The agent configures Git author information and commits.
  4. The agent directly executes git push.

Example:

bash
cd /workspace/repo
git checkout -b feature/auto-fix
git config user.name "AI Bot"
git config user.email "bot@example.com"
git add .
git commit -m "fix: update generated files"
git push -u origin feature/auto-fix

Limitations and Notes ​

  • resources supports a maximum of 20 items.
  • All mount_path values must be absolute paths, must not be duplicated, and must not contain path traversal.
  • github_repository.authorization_token is currently required, even if the target repository is public.
  • Multiple GitHub repository resources within the same sandbox must use the same authorization_token.
  • When using github_repository resources, do not explicitly pass additional GitHub injections.
  • GitHub repository resources use cached snapshots; the latest HEAD is not guaranteed to be fetched each time a sandbox is created. If the task depends on the latest code, execute git pull in the mounted directory.
  • For minimal permissions, GitHub recommends using Fine-grained PATs and granting only the necessary read/write permissions to the target repository.