The Polytoken VFS

The Polytoken virtual filesystem (VFS) exposes the prompts, facets, subagents, themes, 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.

What the VFS contains

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

polytoken vfs ls

polytoken://

Pass the scheme URI to list 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, execute, and orchestrate 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 fragments Polytoken uses to build a system prompt.
themes/	The built-in theme files: default.yaml, boringcyberpunk.yaml, and rose-pine.yaml.

Browse built-in resources

With a URI, polytoken vfs ls lists that directory’s contents. 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 it:

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

Every VFS path uses a URI scheme, and the scheme tells Polytoken which virtual filesystem should handle the path. The polytoken:// scheme names the resources that ship with Polytoken. 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 shipped resource that already shapes the behavior you want to change. When you write a facet, inspect the built-in facet and the prompt fragment that the facet includes with transclude:

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

The facet file shows the frontmatter keys, model and tool choices, and prompt framing that Polytoken uses by default; the prompt fragment contains the base instructions.

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:

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

The paths above are the default locations. Polytoken stores user config under $XDG_CONFIG_HOME/polytoken (default: ~/.config/polytoken). If you set XDG_CONFIG_HOME, substitute that directory in the commands 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") }}

Inspect a built-in file with polytoken vfs cat before you transclude it. The printed file is exactly what transclude includes. For template rendering behavior, see Templating.

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. Polytoken stores the token in a credential file; see Daemon Authentication for how to find the file. In the examples below, replace PORT with the daemon’s port from that page’s session information and set POLYTOKEN_DAEMON_TOKEN to the token from the credential file.

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

The root response lists the five top-level directories:

{
  "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 accepts one leading slash and trims trailing slashes. For subdirectory listings, Polytoken includes the normalized directory path in the response’s path field.

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.