Connect clients and Agents

SDK or filesystem mount

For a custom Python Agent, start with the Python SDK: no FUSE required, with snapshot-versioned discovery. For an existing Agent that only accepts directories, use the Linux mount below. Cache, offline and context-update semantics differ; see integration choices. Mode and offline-policy descriptions below apply to mount clients. The SDK defaults to dynamic views with online validation; retries reuse an explicit checkpoint by default.

Create a Profile and client identity

Choose a Profile's channel, Skills, dynamic or pinned mode, and offline policy. Ensure the channel has a snapshot. Register a mount client and save its one-time token. If lost, rotate it; the platform does not reveal the original again.

Use separate credentials per endpoint. The server Profile determines the mode; a client cannot change channels or expand its own access.

Mount on Linux

You need Linux FUSE, an accessible /dev/fuse, and mount permissions. Place the matching architecture's skills-mount executable on PATH. Native macOS / Windows mounting is not implemented.

For a dynamic Profile, replace the server and PROFILE_ID below and save the token to client.token:

chmod 600 client.token
skills-mount login \
  --server https://skills.example.internal \
  --token-file client.token

skills-mount mount \
  --profile PROFILE_ID \
  --mode dynamic \
  --path "$HOME/agent-skills"

Mount runs in the foreground. Use another terminal for status, refresh, or unmount. Concurrent mounts need separate --cache directories; pass the corresponding cache to control commands too.

Connect the Agent project

From the Skiva repository, link a verified mount into a target project:

python3 scripts/agent-link.py \
  --source-mount-path /srv/agent-skills \
  --project /workspace/my-project \
  --agent codex

The script refuses to overwrite existing paths and does not change global Agent configuration. If a sandbox rejects symlinks, mount directly in an allowed search directory or use an administrator-managed read-only bind mount.

Control commands

skills-mount status
skills-mount refresh
# Rebind pinned content only between tasks
skills-mount refresh --repin
skills-mount unmount --path "$HOME/agent-skills"

If the Profile specifies pinnedSnapshotId, update that server binding before repin can select another authorized target.

Offline access and revocation

• deny_on_disconnect rejects reads after the authorization lease expires; use for sensitive content.
• allow_cached permits verified cached content while offline. Uncached files remain unavailable.
• Online detection of revocation stops authorized reads. Immediate detection during a network outage is impossible.

The cache does not prefetch every file. If offline use is required, actually read necessary files beforehand and test disconnection behavior.

Filesystem updates are not context updates

Dynamic mode preserves old handles while new opens use the refreshed index; pinned mode fixes a task snapshot. Agents may keep their own Skill indexes or prompt caches and require a reload or new session.

Host discovery was tested for Codex, Claude Code, and OpenCode. A real Pydantic AI + MiniMax model also completed the release workflow through Docker Linux FUSE. Other sandboxes and context-cache policies need separate qualification.

Run the local Pydantic AI example

examples/pydantic-agent/run.sh starts an isolated backend on 8083 and its own database. Prepare Docker Desktop, uv, and model environment variables, then run:

./examples/pydantic-agent/run.sh

The example evaluates a simulated 150-unit reimbursement. Version 1 caps reimbursement at 100 and rejects it. After publishing version 2 with a cap of 200, dynamic approves while pinned still rejects. Rollback restores the rejection; revoked credentials prevent both mounts from reading. Each model turn rereads SKILL.md through the mount.

See the complete setup. Results and local OpenTelemetry traces live in .data/agent-pilot/; hosted tracing is not required.