Artifacts are files that belong to a Pioneer workspace. They can come from you, from an agent, from a tool call, or from a task. The gateway stores the files and links them to the thread, turn, and message where they were used or created.
This matters most when you connect to a remote gateway. A file path shown in a tool call may belong to the remote machine, but an artifact can be downloaded to your desktop and opened locally.
Where Artifacts Appear
In a thread, open the artifacts panel from the bottom bar. The panel is only shown on the thread screen and is hidden by default.
The panel lets you:
- list all artifacts for the current thread;
- filter by uploaded files, generated files, task outputs, images, and documents;
- select an artifact and read its metadata;
- preview images when a thumbnail is available;
- download the file to your computer;
- open a downloaded copy;
- reveal a downloaded copy in the file manager;
- attach an existing artifact back into the composer.
Clicking an attachment chip in the timeline selects that artifact. If the artifacts panel is closed, Pioneer opens it first and then shows the selected file.
For parent threads that use subagents, the panel includes artifacts registered in the parent thread and in delegated child threads under that parent. A file created by a subagent should therefore be visible from the parent workflow as long as it was registered as an artifact.
Upload Files
Attach files in the composer when they are part of the prompt: screenshots, logs, small datasets, text files, or documents. Pioneer uploads those bytes to the gateway before the turn starts.
On a local gateway, this usually feels like a normal local file attachment. On a remote gateway, the same operation copies the file from your computer to the remote gateway. The model provider receives the gateway-owned artifact, not an inaccessible path from your desktop.
Do not rely on desktop-only paths in a remote gateway thread. Upload the file as an artifact if the agent or model needs to read it.
Agent-Created Files
When an agent creates a file as a result for you, it must register that file with the artifact store before the final response. Registered files are linked back to the turn and appear in the artifacts panel.
The agent is instructed to use a managed output directory and the artifact_prepare / artifact_register tools for user-visible files. The managed path is temporary staging on the gateway. The durable artifact is the registered file in the gateway artifact store.
Pioneer does not scan arbitrary gateway folders to guess which files should become artifacts. If an agent mentions that it created a file but the file does not appear in the artifacts panel, ask it to register the file as an artifact. If you explicitly asked the agent to write to a specific path, that path may still be a normal gateway file; it is only shown in the artifact panel after registration.
The same applies to hidden subagent threads. A subagent-created file is shown in the parent thread only after the subagent registers it. The artifact stays bound to child-thread and task lineage, but the desktop includes that child-thread subtree when listing artifacts for the parent workflow.
Artifacts show the display name, type, size, source, creation time, and SHA-256 digest. Images can have thumbnails. If a thumbnail is still pending, the file itself may already be ready; the preview is a derived projection and can finish later.
The desktop app caches preview images locally under its runtime directory. The preview cache is pruned automatically when it exceeds 512 MB. Clearing that cache does not delete gateway artifacts.
Download, Open, Reveal
Download copies the artifact from the gateway to a folder you choose on your computer.
Open downloads a verified copy into the desktop cache if needed, then asks the operating system to open that local copy.
Reveal opens the folder for a local downloaded copy. It is disabled until Pioneer has a local path to reveal.
For remote gateways, these actions move bytes over the gateway connection. They do not require direct filesystem access to the remote host.
Reuse Artifacts
Use the attach action in the artifact detail panel when you want to send an existing thread artifact again. Pioneer adds the artifact to the composer without asking you to find the original local file.
This is useful when:
- the original file was uploaded from another computer;
- the artifact was created by an agent on a remote gateway;
- you want to ask a follow-up question about a generated file;
- you want a task or subagent to receive a file from the parent thread.
Follow-Up Questions About Old Files
Pioneer does not blindly attach every old file to every new model request. That would make long threads expensive and confusing, especially if you uploaded many screenshots, photos, logs, or documents.
Instead, Pioneer keeps lightweight artifact references next to the conversation messages where those artifacts appeared. When recent history is included in a new turn, the model can see that a past user message or assistant message had artifacts attached. The reference includes enough metadata to identify the file, such as artifact id, version id, name, kind, MIME type, size, and role. It does not include the file bytes.
If the model needs the actual content, it must reveal the artifact tool domain and call artifact_read for one or more specific artifact refs. That is the right behavior for questions like:
- “why did you think the car in the photo was BMW?”;
- “look again at the second screenshot”;
- “use the CSV I uploaded earlier”;
- “compare this answer with the PDF from yesterday.”
This gives Pioneer continuity without flooding the prompt. If a follow-up does not need the file, the model can answer from normal conversation history. If it does need the file, it can request only that file instead of receiving every artifact from the thread.
Thread context recall follows the same idea. If Pioneer recalls an older conversation snippet that had artifacts attached, the snippet can include a clearly scoped artifact-reference block for that specific snippet. The reference is still metadata only. File content is loaded only through artifact_read.
Troubleshooting
If the artifacts panel says the thread was not found, the thread may still be a draft. Pioneer only loads artifacts for materialized threads.
If a preview is missing but the file is ready, open or download the artifact. The preview path is separate from the original file.
If a file cannot be opened, download it first and check that the destination exists on your desktop. In a remote gateway setup, revealing a gateway path directly is not possible; Pioneer can only reveal local cached or downloaded files.
If Pioneer seems to “forget” a photo or document in a follow-up turn, check two things: whether that message is still in the retained recent history or whether thread context recall brought back the relevant older snippet. If neither happened, the model may not see the artifact reference and therefore cannot know which artifact to read.
Go Deeper
