Mount your own OSS buckets (Beta)

• An Environment can declare at most 8 buckets.
• Only Alibaba Cloud OSS is supported (provider: "aliyun-oss").
• Both read-only and read-write are supported.
• Reads download from OSS through a presigned URL; writes upload directly to OSS with multipart upload (writes smaller than 1 MiB are relayed by Qoder).
• Your RAM role or AccessKey never enters the sandbox.

​

Configuration fields

{
  "type": "cloud",
  "storage": {
    "buckets": []
  }
}

​

Example

curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: oss-bucket-2026-09-23" \
  -d '{
    "name": "with-oss-buckets",
    "config": {
      "type": "cloud",
      "storage": {
        "buckets": [
          {
            "name": "datasets",
            "provider": "aliyun-oss",
            "region": "cn-hangzhou",
            "bucket": "my-bucket",
            "prefix": "team/data/",
            "access": "read_only",
            "credential": {
              "type": "ram_role",
              "role_arn": "acs:ram::1234567890123456:role/qoder-oss-mount"
            }
          },
          {
            "name": "outputs",
            "provider": "aliyun-oss",
            "region": "cn-hangzhou",
            "bucket": "my-bucket",
            "prefix": "team/outputs/",
            "access": "read_write",
            "credential": {
              "type": "access_key",
              "access_key_id": "LTAI5tExampleAccessKey",
              "access_key_secret": "ExampleSecret"
            }
          }
        ]
      }
    }
  }'

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "with-oss-buckets",
  "description": "",
  "config": {
    "type": "cloud",
    "storage": {
      "buckets": [
        {
          "name": "datasets",
          "provider": "aliyun-oss",
          "region": "cn-hangzhou",
          "bucket": "my-bucket",
          "prefix": "team/data/",
          "access": "read_only",
          "credential": {
            "type": "ram_role"
          }
        },
        {
          "name": "outputs",
          "provider": "aliyun-oss",
          "region": "cn-hangzhou",
          "bucket": "my-bucket",
          "prefix": "team/outputs/",
          "access": "read_write",
          "credential": {
            "type": "access_key",
            "access_key_id": "LTAI****sKey"
          }
        }
      ]
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-10-21T08:00:00.000000Z",
  "updated_at": "2026-10-21T08:00:00.000000Z"
}

​

Credentials

​

RAM role (recommended)

1. Create a RAM role in your Alibaba Cloud account for Qoder to assume. Its trust policy must allow the Qoder service role to assume it; contact support for the Qoder service role.
2. Restrict who can assume it with sts:ExternalId:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "RAM": ["<Qoder service role ARN>"]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": ["<your user ID or organization ID@workspace ID>"]
        }
      }
    }
  ]
}

3. Put the role ARN in credential.role_arn.

​

AccessKey

• The AccessKey is stored with the Environment configuration and snapshotted into Sessions created afterwards.
• Reading an Environment returns only a masked access_key_id (for example LTAI****sKey); access_key_secret is never returned.
• Rotating the AccessKey only affects Sessions created afterwards.
• There is no STS session policy: Qoder enforces the prefix and read-only limits, while the storage-side limit is the AccessKey's own RAM policy.

​

Keeping credentials on update

• Omitting a bucket's credential, or echoing the masked credential you read back, keeps the stored credential.
• Renaming a bucket creates a new bucket and requires a full credential.
• Changing credential.type or sending "credential": null requires a full new credential.
• Removing a bucket from the array, or sending "buckets": [], removes it from Sessions created afterwards; existing Sessions keep their snapshot.

​

Authorizing a bucket

​

Tags

• A tag value is limited to 128 characters; use tags only for a small number of IDs.
• Individual sessions match only qoder-mount-users; enterprise sessions match only qoder-mount-organizations. They are different namespaces, so an identical spelling does not grant access across them.
• When qoder-mount-workspaces is set, the Session's workspace must match.
• When any restricting tag is present, every dimension that is set must match.
• Tags are cached for about 1 minute; on read failures the previous value is used for up to 10 minutes; an explicit denial (403) takes effect immediately.

​

Access list (optional)

• Name: <prefix without the trailing slash>.qoder-acl.json. For example, a prefix of team/data/ uses team/data.qoder-acl.json.
• A whole-bucket mount (no prefix) has no access list and relies on tags only.
• Only the file at the mounted directory's own level is read; parent directories are not consulted.

{
  "version": 1,
  "grants": [
    {"users": ["<user ID>"]},
    {"organizations": ["<organization ID>"], "workspaces": ["<workspace ID>"], "agents": ["<agent ID>"], "sessions": ["<session ID>"]}
  ]
}

• The supported dimensions are users, organizations, workspaces, agents, and sessions.
• Within one grant, every dimension that is set must match; unset dimensions are unrestricted; an empty list matches nobody.
• Any matching grant allows the mount; if none matches, the mount is refused with 403.
• When both tags and an access list are present, both must match.
• A file larger than 64 KB, invalid version 1 JSON, unknown keys, a null grant, or a dimension that is not an array of non-empty strings is rejected.
• agents and sessions are checked at mount time, not when the Environment is saved.
• The list is cached for about 1 minute; after it expires, read failures reuse the previous value for up to 10 minutes; 403 is never reused.
• A missing file is not an error, but in that case the tags must name who may mount.

​

Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["oss:ListObjects", "oss:GetBucketTagging"],
      "Resource": ["acs:oss:*:*:my-bucket"]
    },
    {
      "Effect": "Allow",
      "Action": ["oss:GetObject", "oss:HeadObject"],
      "Resource": ["acs:oss:*:*:my-bucket/team/data/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["oss:GetObject"],
      "Resource": ["acs:oss:*:*:my-bucket/team/data.qoder-acl.json"]
    }
  ]
}

​

Validation when saving

1. Obtain credentials (assume the role or use the AccessKey).
2. Read the bucket tags.
3. Read the access list, if present.
4. List the prefix once (max-keys=1).

• A configuration or permission refusal returns 400 invalid_request_error with a message such as Bucket '<name>' cannot be mounted: <reason>.
• An OSS / STS outage returns 503 api_error and can be retried.
• The agents / sessions dimensions of the access list are not checked when saving; they are checked at mount time.

​

Behavior in the sandbox

• Directories: object storage has no real directories. A directory is the prefix of object keys; an empty directory is kept alive by a zero-byte <path>/ placeholder object, the same convention as the OSS console and ossutil.
• Reads: Qoder returns a 302 to a presigned URL and the sandbox downloads directly from OSS.
• Writes: files smaller than 1 MiB use a regular upload relayed by Qoder; files of 1 MiB or more use multipart upload (the sandbox PUTs each part to a presigned URL and then commits).
• Rename: a single-file rename is copy + delete and is not atomic. Concurrent Sessions modifying the same path can lose writes; Qoder does not arbitrate across Sessions.
• Directory rename: not natively supported; the client falls back to moving files one by one.
• Deleting directories: a non-empty directory returns 409; delete its files first.
• Listing limit: a single directory with more than 100,000 entries returns 507 rather than a truncated listing.
• File size limit: a direct upload is at most 10,000 parts × 64 MiB, i.e. 625 GiB; the bucket's own quotas and limits still apply.
• Interrupted uploads: an interrupted write leaves unfinished parts in the bucket. Configure a lifecycle rule on the bucket to clean them up.
• Regions: when the bucket is in the sandbox's region, the OSS internal endpoint is used; otherwise traffic goes over the public endpoint with higher latency. The OSS accelerator works only in the same region.
• Networking: the sandbox accesses OSS directly for reads and for writes of 1 MiB or more. If the Environment uses restricted networking, allow the corresponding OSS domain.

​

Errors

​

Limitations

• Only Alibaba Cloud OSS is supported; S3, COS, MinIO, and custom endpoints are not.
• Qoder does not manage object versions, lifecycle rules, bucket ACLs, or other OSS settings.
• One prefix of one bucket can appear only once per Environment; to mount several directories of the same bucket, use different name and prefix values.
• Mounts use the Environment snapshot; changing an Environment does not alter existing Sessions.