Mount Slots Reference

This page documents every workspace mount slot, its configuration options, and usage patterns.

Mount Slots Overview

A mount slot is a directory or resource that gets materialized into the agent's /workspace/. Manifest authors declare which slots to mount and in what mode (read-only or read-write).

yaml

1spec:
2  mounts:
3    deliverables:      # slot name
4      mode: read-write  # access mode

All Mount Slots

`inputs`

Path: /workspace/inputs/
Mode: Always read-only
Description: Structured input data supplied by the caller (workflow inputs, session context).

Configuration:

yaml

1spec:
2  mounts:
3    inputs: true    # always read-only, no additional config

File structure:

text

1/workspace/inputs/
2├── inputs.json      # caller-supplied inputs as JSON
3└── (optional) / individual input files

Use case: Agent reads structured inputs from the workflow dispatch or session launch.

`repos`

Path: /workspace/repos/
Mode: read-only or read-write
Description: Git repositories the agent operates on or references.

Configuration:

yaml

1spec:
2  mounts:
3    repos:
4      mode: read-write    # agent can commit, push, create branches
5      work:               # repository role/group
6        - url: ${input.repo_url}
7          role: primary   # which repo is the "main" one
8        - url: https://github.com/example/dependency
9          role: reference

File structure:

text

1/workspace/repos/
2├── <repoName1>/     # cloned from primary repo
3├── <repoName2>/     # cloned from reference repo
4└── ...

Field	Type	Description
`mode`	string	`read-only` or `read-write`
`work`	array	Repos to mount (role not used currently, reserved)
`work[].url`	string	SCM repository URL
`work[].role`	string	`primary` or `reference` (informational)

Use case: Agent working on codebase, running tests, committing changes.

`references`

Path: /workspace/references/
Mode: Always read-only
Description: Knowledge-base spaces and external reference repositories (no write).

Configuration:

yaml

1spec:
2  mounts:
3    references:
4      mode: read-only                          # always read-only
5      kb:                                      # knowledge-base spaces
6        spaces: ${input.kbSpaceIds}       # e.g. ["best-practices", "api-docs"]
7      externalProjects:                        # external reference repos
8        repos: ${input.referenceRepo}     # e.g. "owner/reference-repo"

File structure:

text

1/workspace/references/
2├── kb/
3│   ├── best-practices/          # KB space content
4│   ├── api-docs/
5│   └── ...
6└── external-projects/
7    ├── <externalRepoName1>/
8    ├── <externalRepoName2>/
9    └── ...

Field	Type	Description
`mode`	string	Always `read-only` (no additional options)
`kb.spaces`	string[]	KB space slugs to mount (resolved at runtime)
`externalProjects.repos`	string	SCM repo URL or slug (resolved at runtime)

Use case: Agent researching architecture patterns, reading documentation, referencing external examples.

`deliverable-specs`

Path: /workspace/deliverable-specs/
Mode: Always read-only
Description: Output contracts and deliverable templates (what the agent is expected to produce).

Configuration:

yaml

1spec:
2  mounts:
3    deliverable-specs: true   # no additional config needed

File structure:

text

1/workspace/deliverable-specs/
2├── <specSlug1>.json
3├── <specSlug2>.json
4└── ...

Spec format: Each spec is a JSON file defining:

Output format (e.g., markdown, JSON, code)
Validation schema (Zod or JSON-Schema)
Required sections/fields

Use case: Agent reads the output contract before starting work; platform validates agent output against these specs.

`deliverables`

Path: /workspace/deliverables/
Mode: read-only or read-write
Description: Agent outputs and intermediate artifacts (harvested at session end).

Configuration:

yaml

1spec:
2  mounts:
3    deliverables: true       # read-write (always writable)

File structure:

text

1/workspace/deliverables/
2├── manifest.json             # required; created by platform or agent
3├── my-output.md              # custom deliverable files
4├── code/
5│   ├── module.py
6│   └── ...
7└── ...

Special file:

manifest.json — declares what was produced and how to classify each file:

json

1{
2  "deliverables": [
3    { "path": "my-output.md", "kind": "code-review" },
4    { "path": "code/module.py", "kind": "implementation" }
5  ]
6}

Use case: Agent writes analysis, code, documentation, or any output. Platform automatically harvests on session end.

`uploads`

Path: /workspace/uploads/
Mode: Always read-only
Description: Files uploaded by the user to the interactive session (documents, code snippets, images).

Configuration:

yaml

1spec:
2  mounts:
3    uploads: true        # no additional config

File structure:

text

1/workspace/uploads/
2├── document.pdf
3├── code-snippet.py
4├── screenshot.png
5└── ...

Use case: User attaches supporting files during a session; agent reads and analyzes them.

Agent-runtime config dir

Path: /workspace/<agent-runtime-config>/ (internal — exact location is managed by the platform)
Mode: read-only (internal agent runtime config)
Description: Xema Agent Runtime configuration (agents, skills, instructions). Managed automatically by the platform.

File structure (not user-configurable):

text

1/workspace/<agent-runtime-config>/
2├── runtime.jsonc               # runtime config (managed by pool-api)
3├── agents/                      # agent definitions
4│   ├── engineer.md
5│   └── ...
6├── skills/                      # skill definitions
7│   ├── code-review/
8│   │   └── SKILL.md
9│   └── ...
10└── instructions/                # custom instructions
11    ├── custom-rule.md
12    └── ...

Note: You do NOT declare this mount in your manifest. It is always present and managed by the platform.

Mount Configuration Patterns

Minimal (No Custom Config)

Use true as a shorthand to enable with platform defaults:

yaml

1spec:
2  mounts:
3    inputs: true
4    references: true
5    deliverable-specs: true
6    deliverables: true
7    uploads: true

Explicit Mode

Specify the access mode explicitly:

yaml

1spec:
2  mounts:
3    repos:
4      mode: read-write
5    references:
6      mode: read-only

Dynamic Configuration

Use expressions to bind mount config at runtime:

yaml

1spec:
2  inputs:
3    kbSpaces:
4      type: array
5      default: ["best-practices"]
6    primaryRepo:
7      type: string
8      required: true
9
10  mounts:
11    references:
12      kb:
13        spaces: ${input.kbSpaces}     # resolved at dispatch
14    repos:
15      work:
16        - url: ${input.primaryRepo}  # resolved at dispatch

Omitting Mounts

If you don't declare a mount, it is not mounted:

yaml

1spec:
2  mounts:
3    repos: true          # ✓ /workspace/repos/ exists
4    # deliverables not listed → /workspace/deliverables/ not mounted
5
6  # So the agent cannot write deliverables!
7  # (Unless deliverables is needed, always include it)

Mount Access Modes

read-only

Agent can read but cannot modify:

bash

1cat /workspace/references/kb/best-practices.md  # ✓ works
2echo "test" > /workspace/references/new.md     # ✗ read-only filesystem

Slots that are always read-only:

inputs
references
deliverable-specs
uploads
Agent-runtime config dir

read-write

Agent can create, modify, delete files:

bash

1cat /workspace/repos/myrepo/code.py            # ✓ read
2echo "changes" >> /workspace/repos/myrepo/code.py   # ✓ write
3git -C /workspace/repos/myrepo add .            # ✓ commit

Slots that can be read-write:

repos
deliverables

Common Manifest Patterns

Brainstorming Session

yaml

1spec:
2  mounts:
3    inputs: true           # user inputs for brainstorm
4    deliverables: true     # brainstorm notes
5    # no repos, no references — this is creative, offline work

Engineering Review

yaml

1spec:
2  mounts:
3    repos:                 # read code
4      mode: read-only
5      work:
6        - url: ${input.repo_url}
7    references: true       # reference patterns/guidelines
8    deliverables: true     # write review comments

Code Implementation

yaml

1spec:
2  mounts:
3    repos:                 # work on codebase
4      mode: read-write
5      work:
6        - url: ${input.repo_url}
7    deliverable-specs: true    # understand output contract
8    deliverables: true         # write implementation

Research + Documentation

yaml

1spec:
2  mounts:
3    references:            # research materials
4      kb:
5        spaces: ${input.kbSpaces}
6    deliverables: true     # write findings
7    # no repos — this is documentation work, not coding

Troubleshooting

Q: Agent says "permission denied" on /workspace/xxx
A: The mount is read-only and the agent is trying to write. Check spec.mounts.<slot>.mode and update to read-write if needed.

Q: I don't see /workspace/repos/ in the agent
A: repos is not mounted in your manifest. Add spec.mounts.repos: true or spec.mounts.repos: { mode: read-write }.

Q: How do I mount a specific KB space?
A: Use spec.mounts.references.kb.spaces: ["space-slug"]. At dispatch, provide the space IDs in inputs.

Q: Can the agent create new files in /workspace/deliverables?
A: Yes, if spec.mounts.deliverables: true (or read-write). The agent can create any files. Use manifest.json to declare which ones are actual deliverables.

Related: Authoring Guide · DSL Reference

Previous: ← DSL Reference Next: Environment Blocks →