The Polytoken VFS

The Polytoken virtual filesystem (VFS) exposes the prompts, facets, subagents, and supporting resources that ship with Polytoken. Inspect those resources before you write a custom facet, replace a prompt section, or reference a built-in resource from your own configuration.

Use the VFS to compare your customization with Polytoken’s baseline behavior before you customize a facet, subagent, prompt, or resource outside the core engine.

What the VFS contains

Run polytoken vfs ls to see the VFS schemes Polytoken can inspect:

polytoken vfs ls

polytoken://

Run polytoken vfs ls polytoken:// to see the top-level directories in the built-in VFS:

polytoken vfs ls polytoken://

facets/
resources/
subagents/
system_prompts/
themes/

Directory	Contents
facets/	The built-in plan and execute facets. Read these files before you replace a facet or write a related facet.
resources/	Supporting text that built-in prompts or facets reference.
subagents/	Built-in subagent definitions. These files show how Polytoken frames delegated work.
system_prompts/	Base prompt templates and prompt fragments Polytoken uses when Polytoken builds a system prompt.
themes/	Theme files that ship with Polytoken. The built-in default theme lives at themes/default.yaml.

Browse built-in resources

Run polytoken vfs ls with a URI to list a directory. Directory names end with /, and file names do not.

polytoken vfs ls polytoken://system_prompts

polytoken vfs cat prints a file exactly as Polytoken stores the file:

polytoken vfs cat polytoken://facets/plan.md

Every VFS path uses a URI scheme. Polytoken accepts polytoken:// paths for the built-in VFS. Polytoken also accepts file-style polytoken:/// paths, so polytoken:///facets/plan.md and polytoken://facets/plan.md reference the same built-in resource. You can add trailing slashes to a VFS path, and Polytoken ignores them. A bare path such as facets/plan.md is not a VFS path, and Polytoken rejects schemes such as example://facets/plan.md.

Inspect before you extend

Start with the resource closest to the behavior you want to change. When you write a facet, inspect the built-in facet and the prompt that the built-in facet includes with transclude:

polytoken vfs cat polytoken://facets/plan.md
polytoken vfs cat polytoken://system_prompts/facet.md

The built-in facet shows the frontmatter keys, model and tool choices, and prompt framing that Polytoken uses by default. The prompt fragment shows the base instructions the facet includes with transclude("polytoken://system_prompts/facet.md").

You can copy a built-in file as a starting point:

mkdir -p .polytoken/facets
polytoken vfs cat polytoken://facets/plan.md > .polytoken/facets/my-plan.md

Copying is optional. When you write a facet from scratch, use the VFS to compare your design with the prompts, tool choices, and instructions that shape Polytoken’s default model behavior.

Inspect the built-in theme

The built-in default theme lives at polytoken://themes/default.yaml. Copy the file as a starting point for a custom theme:

polytoken vfs cat polytoken://themes/default.yaml > ~/.config/polytoken/themes/my-theme.yaml

The path above is the default location. Polytoken stores user config under $XDG_CONFIG_HOME/polytoken (default: ~/.config/polytoken). If you set XDG_CONFIG_HOME, substitute that directory in the command above.

For the full theme authoring guide, see Themes.

Use VFS paths in templates

Facet and subagent bodies can include built-in resources with transclude:

{{ transclude("polytoken://system_prompts/facet.md") }}

Use the VFS to inspect a resource before you transclude the resource. The VFS shows which resource the URI references. For template rendering behavior, see Templating.

Path format

The built-in VFS uses polytoken:// and polytoken:/// URIs. polytoken vfs ls lists VFS schemes when you omit the URI, and lists resources when you provide a URI. polytoken vfs cat prints a resource from the command line.

Always include the URI scheme. The scheme tells Polytoken which virtual filesystem should handle the path, and polytoken:// names the resources that ship with Polytoken.

Inspect the VFS over HTTP

The daemon exposes the shipped-resource VFS through authenticated read-only HTTP routes. Send the bearer token that Polytoken created for the daemon with every request.

curl --fail \\
  -H "Authorization: Bearer $POLYTOKEN_DAEMON_TOKEN" \\
  http://127.0.0.1:PORT/vfs

A root index returns JSON with five directory entries:

{
  "entries": [
    {"name": "facets", "is_dir": true},
    {"name": "resources", "is_dir": true},
    {"name": "subagents", "is_dir": true},
    {"name": "system_prompts", "is_dir": true},
    {"name": "themes", "is_dir": true}
  ]
}

Pass a relative directory in path to inspect a subdirectory. Polytoken trims trailing slashes and accepts one leading slash.

curl --fail \\
  -H "Authorization: Bearer $POLYTOKEN_DAEMON_TOKEN" \\
  'http://127.0.0.1:PORT/vfs?path=system_prompts/'

Read a shipped file with /vfs/content:

curl --fail \\
  -H "Authorization: Bearer $POLYTOKEN_DAEMON_TOKEN" \\
  'http://127.0.0.1:PORT/vfs/content?path=facets/plan.md'

The content response includes the normalized path and the exact file body:

{
  "path": "facets/plan.md",
  "content": "---\nname: plan\n..."
}

HTTP errors use an ErrorBody with a stable code string and a human-readable message. Clients should treat codes they do not recognize as opaque strings.

Code	Meaning
missing_path	/vfs/content did not receive a non-empty path.
invalid_vfs_path	The path contains an unsupported component, such as . or .., a backslash, or a double slash. On /vfs/content, a path consisting only of slashes, such as ?path=/, also returns invalid_vfs_path because the VFS root is a directory, not a readable file.
vfs_not_found	The shipped-resource path does not exist.
vfs_is_a_directory	/vfs/content received a directory path.
vfs_not_a_directory	/vfs received a file path.
vfs_io_error	Polytoken could not read the shipped-resource tree.