alibabacloud-agent-fs 0.4.0

Virtual filesystem for Alibaba Cloud cloud-native services (AgentLoop Memory, Nacos)

Alibaba Cloud Agent FS

Virtual filesystem for Alibaba Cloud cloud-native services — designed for AI Agent interaction.

Exposes AgentLoop Memory (CMS) and Nacos (Config Center + Service Registry + Skill Registry) as a standard POSIX filesystem. Interact with cloud services using nothing but ls, cat, echo, cp, mkdir, and rm.

Features

• Agent-Friendly Design: Explore and operate cloud services with standard shell commands
• Self-Describing: _help.txt files at every level guide usage
• Multi-Service: Memory, config management, service discovery, and skill management in one mount
• Extensible: Plugin-based provider architecture — add new Alibaba Cloud services easily
• POSIX Compatible: Works with any tool that uses standard file operations

Installation

Install from source

pip install .

Install from wheel

pip install build
python3 -m build
pip install dist/alibabacloud_agent_fs-*.whl

OS Dependencies (FUSE)

macOS

brew install macfuse

Linux (Ubuntu/Debian)

sudo apt-get install fuse libfuse-dev

Linux (CentOS/RHEL/Alibaba Cloud Linux)

sudo yum install fuse fuse-devel

Configuration

Set environment variables or use a .env file:

# AgentLoop Memory (CMS) - static AK/SK
export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"
export CMS_WORKSPACE="your-workspace-name"
export CMS_ENDPOINT="cms.cn-hangzhou.aliyuncs.com"  # optional

# AgentLoop Memory (CMS) - STS
export ALIBABA_CLOUD_ACCESS_KEY_ID="your-sts-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sts-access-key-secret"
export ALIBABA_CLOUD_SECURITY_TOKEN="your-sts-security-token"

# AgentLoop Memory (CMS) - OIDC / RRSA
export ALIBABA_CLOUD_ROLE_ARN="acs:ram::123456789012:role/example"
export ALIBABA_CLOUD_OIDC_PROVIDER_ARN="acs:ram::123456789012:oidc-provider/example"
export ALIBABA_CLOUD_OIDC_TOKEN_FILE="/var/run/secrets/tokens/oidc-token"
export ALIBABA_CLOUD_REGION_ID="cn-hangzhou"  # optional, default: cn-hangzhou

# Nacos Config & Service Discovery
export NACOS_SERVER_ADDR="localhost:8848"       # or MSE endpoint
export NACOS_NAMESPACE="public"                 # optional, default: public
export NACOS_USERNAME="nacos"                   # optional, for self-hosted Nacos
export NACOS_PASSWORD="nacos"                   # optional
export NACOS_ACCESS_KEY="your-ak"              # optional, for Alibaba Cloud MSE
export NACOS_SECRET_KEY="your-sk"              # optional

For AgentLoop Memory, you can use any one of these auth modes:

• AK/SK
• AK/SK + STS security token
• OIDC / RRSA

Either provider can be omitted — the filesystem only mounts providers whose credentials are present.

Usage

Mount the Filesystem

mkdir -p /tmp/alibabacloud
alibabacloud-agent-fs /tmp/alibabacloud

Or with explicit options:

alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --endpoint cms.cn-shanghai.aliyuncs.com \
  --nacos-server mse.cn-hangzhou.aliyuncs.com:8848

Or with explicit STS / OIDC options:

alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --access-key-id sts-ak \
  --access-key-secret sts-sk \
  --security-token sts-token

alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --role-arn acs:ram::123456789012:role/example \
  --oidc-provider-arn acs:ram::123456789012:oidc-provider/example \
  --oidc-token-file /var/run/secrets/tokens/oidc-token

AgentLoop Memory Operations

# View help
cat /tmp/alibabacloud/agentloop-memory/_help.txt

# List memory stores
ls /tmp/alibabacloud/agentloop-memory/stores/

# Create a new store
mkdir /tmp/alibabacloud/agentloop-memory/stores/my_memories

# Add a memory (WRITE-ONLY, async processing)
echo "User prefers dark mode" > /tmp/alibabacloud/agentloop-memory/stores/my_memories/_add.txt

# Wait ~30-60 seconds for processing, then search
cat /tmp/alibabacloud/agentloop-memory/stores/my_memories/search/preferences.txt

# View all memories for a user
cat /tmp/alibabacloud/agentloop-memory/stores/my_memories/users/default_user/_all.txt

# Delete a memory store
rmdir /tmp/alibabacloud/agentloop-memory/stores/my_memories

Nacos Config Operations

# List namespaces
ls /tmp/alibabacloud/nacos/config/

# List groups in a namespace
ls /tmp/alibabacloud/nacos/config/public/

# List configs in a group
ls /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/

# Read a config
cat /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/application.properties

# Create or update a config
echo "server.port=8080" > /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/application.properties

# Delete a config
rm /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/old-config.properties

Nacos Service Discovery Operations

# List namespaces
ls /tmp/alibabacloud/nacos/services/

# List service groups
ls /tmp/alibabacloud/nacos/services/public/

# List services in a group
ls /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/

# View service metadata
cat /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/_info.json

# List service instances
ls /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/

# View instance details
cat "/tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/10.0.0.1:8080.json"

# Register an instance (write JSON to _register.json)
echo '{"action":"register","ip":"10.0.0.2","port":8080,"weight":1.0}' \
  > /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/_register.json

# Deregister an instance
echo '{"action":"deregister","ip":"10.0.0.2","port":8080}' \
  > /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/_register.json

Nacos Skill Operations

Note: Skill 功能要求 Nacos Server >= 3.2.0。

# List namespaces
ls /tmp/alibabacloud/nacos/skills/

# List skills in a namespace
ls /tmp/alibabacloud/nacos/skills/public/

# View skill metadata
cat /tmp/alibabacloud/nacos/skills/public/my-skill/_info.json

# List files in a skill package
ls /tmp/alibabacloud/nacos/skills/public/my-skill/

# Read skill content
cat /tmp/alibabacloud/nacos/skills/public/my-skill/SKILL.md

# Upload a skill (cp ZIP file)
cp my-skill.zip /tmp/alibabacloud/nacos/skills/public/my-skill.zip

Unmount

# Linux
fusermount -u /tmp/alibabacloud

# macOS
umount /tmp/alibabacloud

Directory Structure

/
├── _help.txt
├── agentloop-memory/                    # AgentLoop Memory (CMS)
│   └── stores/
│       ├── _help.txt
│       └── {store_name}/
│           ├── _info.json               # Store configuration (READ-ONLY)
│           ├── _add.txt                 # Add memories (WRITE-ONLY, async)
│           ├── _help.txt
│           ├── memories/
│           │   └── {memory_id}.json     # Individual memory (READ / DELETE)
│           ├── users/
│           │   └── {user_id}/
│           │       ├── _all.txt         # All user memories (READ)
│           │       └── _add.txt         # Add for user (WRITE)
│           ├── agents/
│           │   └── {agent_id}/...
│           └── search/
│               └── {query}.txt          # Search results (READ)
└── nacos/                               # Nacos Config & Service Discovery
    ├── config/
    │   └── {namespace}/
    │       └── {group}/
    │           └── {dataId}             # Config content (READ / WRITE / DELETE)
    ├── services/
    │   └── {namespace}/
    │       └── {group}/
    │           └── {service}/
    │               ├── _info.json       # Service metadata (READ-ONLY)
    │               └── instances/
    │                   ├── {ip}:{port}.json    # Instance details (READ-ONLY)
    │                   └── _register.json      # Register/deregister (WRITE-ONLY)
    └── skills/
        └── {namespace}/
            ├── {skillName}.zip              # Upload skill (WRITE: cp ZIP)
            └── {skillName}/
                ├── _info.json               # Skill metadata (READ-ONLY)
                ├── SKILL.md                 # Skill content (READ-ONLY)
                └── {resource_file}          # Other files in skill package (READ-ONLY)

API Mapping

AgentLoop Memory

Shell Command	CMS API
mkdir agentloop-memory/stores/{name}	CreateMemoryStore
rmdir agentloop-memory/stores/{name}	DeleteMemoryStore
cat agentloop-memory/stores/{name}/_info.json	GetMemoryStore
echo "text" > agentloop-memory/stores/{name}/_add.txt	AddMemories
cat agentloop-memory/stores/{name}/search/{query}.txt	SearchMemories
cat agentloop-memory/stores/{name}/memories/{id}.json	GetMemory
rm agentloop-memory/stores/{name}/memories/{id}.json	DeleteMemory
ls agentloop-memory/stores/	ListMemoryStores

Nacos Config

Shell Command	Nacos API
ls nacos/config/	List Namespaces
ls nacos/config/{ns}/{group}/	List Configs (search=blur)
cat nacos/config/{ns}/{group}/{dataId}	GetConfig
echo "val" > nacos/config/{ns}/{group}/{dataId}	PublishConfig
rm nacos/config/{ns}/{group}/{dataId}	RemoveConfig

Nacos Services

Shell Command	Nacos API
ls nacos/services/{ns}/{group}/	ListServices
cat nacos/services/{ns}/{group}/{svc}/_info.json	GetService
ls nacos/services/{ns}/{group}/{svc}/instances/	ListInstances
echo '{"action":"register",...}' > .../instances/_register.json	RegisterInstance
echo '{"action":"deregister",...}' > .../instances/_register.json	DeregisterInstance

Nacos Skills

Shell Command	Nacos API
ls nacos/skills/{ns}/	ListSkills (v3)
cat nacos/skills/{ns}/{name}/_info.json	Skill metadata (from list cache)
ls nacos/skills/{ns}/{name}/	List skill files (download ZIP + extract)
cat nacos/skills/{ns}/{name}/SKILL.md	Read skill file (from ZIP cache)
cp skill.zip nacos/skills/{ns}/{name}.zip	UploadSkill (v3, multipart ZIP)

For AI Agents

This filesystem is designed to give AI agents access to Alibaba Cloud services using only standard shell commands — no SDKs, no special APIs.

Prompt templates are provided in the agent_integration/ directory:

1. INSTALL_PROMPT.md: Instructions for the agent to install dependencies, configure credentials, and mount the filesystem.
2. USAGE_PROMPT.md: System prompt snippet teaching the agent how to use memory, config, and service discovery.
3. SKILL.md: Cursor Agent skill for automatic memory integration.

CLI Reference

alibabacloud-agent-fs [-h] [-V] [-e FILE]
                       [--endpoint HOST] [-w NAME] [-p NAME]
                       [--access-key-id ID] [--access-key-secret SECRET]
                       [--security-token TOKEN] [--role-arn ARN]
                       [--oidc-provider-arn ARN] [--oidc-token-file FILE]
                       [--role-session-name NAME] [--region-id REGION]
                       [--nacos-server HOST:PORT] [--nacos-namespace NS]
                       [--nacos-username USER] [--nacos-password PASS]
                       [--nacos-access-key AK] [--nacos-secret-key SK]
                       [-d] [--allow-other]
                       mountpoint

Options:
  mountpoint                  Directory to mount the filesystem
  -V, --version               Show version
  -e, --env FILE              Path to .env file

AgentLoop Memory (CMS):
  --endpoint HOST             CMS endpoint (default: cms.cn-hangzhou.aliyuncs.com)
  -w, --workspace NAME        CMS workspace name
  -p, --project NAME          Alias for --workspace
  --access-key-id ID          Alibaba Cloud Access Key ID
  --access-key-secret SECRET  Alibaba Cloud Access Key Secret
  --security-token TOKEN      Alibaba Cloud STS security token
  --role-arn ARN              OIDC role ARN for AgentLoop Memory
  --oidc-provider-arn ARN     OIDC provider ARN for AgentLoop Memory
  --oidc-token-file FILE      OIDC token file path for AgentLoop Memory
  --role-session-name NAME    OIDC role session name
  --region-id REGION          Region used to derive the STS endpoint for OIDC auth

Nacos:
  --nacos-server HOST:PORT    Nacos server address
  --nacos-namespace NS        Default namespace (default: public)
  --nacos-username USER       Nacos username
  --nacos-password PASS       Nacos password
  --nacos-access-key AK       Alibaba Cloud AK for MSE Nacos
  --nacos-secret-key SK       Alibaba Cloud SK for MSE Nacos

FUSE:
  -d, --debug                 Enable debug logging
  --allow-other               Allow other users access

Testing

# Unit tests
python -m pytest tests/test_unit.py

# Integration tests (requires credentials)
python tests/test_memory_api.py

# E2E tests (requires mounted filesystem)
alibabacloud-agent-fs /tmp/alibabacloud_test &
bash tests/e2e_test.sh

License

MIT License