DocsGuides
Artifacts
A Computer's artifacts are the files it keeps beyond its sessions. They are stored outside the Computer, so they stay through Stop and Start, and you can list, upload and download them with the project key while the Computer is stopped. Session files are temporary (Persistence): keep in artifacts what a later session or your application will need.
- The agent saves its outputs there and reads the inputs you put there. Every session of the Computer sees the same files.
- A Computer holds up to 100 GiB of artifacts. A single file is limited only by the disk of whatever saves or reads it (Limits).
- Artifacts stay until they are deleted. Deleting the Computer deletes its artifacts too: they can't be reached once the storage tokens issued before the delete lapse, within 30 minutes, and Pine deletes them 25 hours later.
Files are named by paths such as reports/q3.pdf. Folders are part of the
path, so there is nothing to create first. A path is up to 900 bytes, without
control characters, and no part of it between slashes may be empty, . or
..; spaces and other characters are fine. Saving to a path that already holds
a file replaces it. Pine keeps one version of each file: to keep earlier
versions, save each under its own name, such as reports/q3-v2.pdf.
A turn returns its deliverables in turn.result.artifacts. Each entry's root
tells you how to download it:
workdir: readrelative_paththrough the session file API. These files last until the Computer stops; their size, hash and other metadata describe the file when the turn returned it.artifact_store: usecomputer_idandrelative_pathwith the artifact SDK. Downloads go directly from storage, including large files and files read after the Computer stops. These references may have no file metadata.
Downloads return the current contents at the path: replacing a file changes what you download, and a missing or deleted file returns a not-found error. Only files returned as deliverables appear in the result; other saved files remain available through the artifact SDK. The same references appear in result events.
To download a returned saved file:
ref = turn.result.artifacts.find { |file| file.fetch("root") == "artifact_store" }
client.artifacts(ref.fetch("computer_id")).download(ref.fetch("relative_path"), "report.pdf")
for _, ref := range turn.Result.Artifacts {
if ref.Root == "artifact_store" {
if _, err := client.Artifacts(ref.ComputerID).Download(ctx, ref.RelativePath, "report.pdf"); err != nil {
return err
}
}
}
const ref = turn.result!.artifacts.find(file => file.root === "artifact_store")!;
await client.artifacts(ref.computerId!).download(ref.relativePath, "report.pdf");
ref = next(file for file in turn.result.artifacts if file.root == "artifact_store")
client.artifacts(ref.computer_id).download(ref.relative_path, "report.pdf")
The artifact client's open method streams bytes instead of saving to disk.
Workdir files continue to use the existing session file methods.
Playground shows all returned files together. Downloading a saved file there requires a running Computer with public artifact links available. SDK downloads work while the Computer is stopped and do not need public links.
In a session
A session's agent reaches the artifacts only if you allow it when you create
the session. Its artifact_access is fixed for the session's life:
artifact_access |
The session's agent can |
|---|---|
none (default) |
Cannot read, save or return Computer artifacts. |
read_only |
List, find and read files. |
read_write |
Also save and remove files, and make public links. |
Your own access with the project key doesn't depend on it.
The default none preserves worktree-only results. Before opting into artifact
access, update your SDK and handle artifact_store entries in the result.
Older integrations that assume every result file is in the workdir must be
updated before enabling artifact access. Downloading a saved reference
requires your project key, not a session token or a public link.
session = computer.create_session(name: "researcher", artifact_access: "read_write")
session.artifact_access # => "read_write"
session, err := computer.CreateSession(ctx, pine.CreateSessionOptions{
Name: "researcher", ArtifactAccess: pine.ArtifactAccessReadWrite,
})
if err != nil {
return err
}
fmt.Println(session.Info().ArtifactAccess) // read_write
const session = await computer.createSession({ name: "researcher", artifactAccess: "read_write" });
session.artifactAccess; // "read_write"
session = computer.create_session(name="researcher", artifact_access="read_write")
session.artifact_access # "read_write"
On the Computer, the agent uses its pine-artifact command. Commands you run
in the session's shell don't have it: your application reaches the artifacts
through the SDK, as below.
| Command | What it does |
|---|---|
pine-artifact save <file|folder> [<path>] |
Saves a file as <path> (by default, its name), or a folder's files under <path>/. --note TEXT adds a description shown in listings. --move deletes the local file once it is saved. |
pine-artifact get <path> [<dest>] |
Copies a file into the session, or a whole folder when the path ends in /. The copies are read-only. |
pine-artifact ls [<folder>] [-R] |
Lists a folder, or everything below it with -R. |
pine-artifact find <text> |
Finds files whose path or note contains the text. |
pine-artifact cat <path> |
Writes a file to standard output, to stream it into another program. |
pine-artifact rm <path>... |
Removes files, for every session and for you. There is no undo. |
pine-artifact link <path> [--expires 24h] |
Prints a public link to the file. |
With artifacts on, the agent learns that pine-artifact keeps files beyond
the session. It saves what your task asks it to keep, or what a later session
will need, and leaves scratch files out. Say in your task what to keep, for
example: "Save the final report as an artifact at reports/q3.pdf, with a
one-line note."
From your application
client.artifacts(computer_id) returns the artifacts of one of the project's
Computers, running or stopped. The handle gets a short-lived storage token
from Pine, then sends every request, file bytes included, directly to the
storage service the token names, Google Cloud Storage
(storage.googleapis.com). Your application needs to reach that host. Reuse one handle for a run of calls; it renews its token before the
token lapses.
list returns one folder level: its files, with path, size,
updated_at, content_type and note, and its folders. Set recursive to
list every file below the prefix instead. A long listing comes in pages:
pass the page's next token back until it is empty, as below. upload and
download resume a dropped connection where it stopped; download writes to
a temporary file beside the destination and renames it when complete. open
streams a file without keeping a local copy.
require "pathname"
artifacts = client.artifacts(computer.id)
# A String is the file's bytes; a Pathname or an IO is read from the local disk.
artifacts.upload("inputs/brief.pdf", Pathname("brief.pdf"), note: "Client brief")
page_token = nil
loop do
page = artifacts.list(prefix: "reports/", page_token: page_token) # recursive: true lists every file below
page.files.each { |file| puts "#{file.path} #{file.size} #{file.note}" }
page_token = page.next_page_token
break if page_token.nil? || page_token.empty?
end
artifacts.download("reports/q3.pdf", "q3.pdf")
# A large file, streamed in chunks:
artifacts.open("data/events.csv") { |chunk| process(chunk) }
artifacts := client.Artifacts(computer.ID())
if _, err := artifacts.Upload(ctx, "inputs/brief.pdf", pine.ArtifactFromFile("brief.pdf"),
pine.ArtifactUploadOptions{Note: "Client brief"}); err != nil {
return err
}
pageToken := ""
for {
page, err := artifacts.List(ctx, pine.ArtifactListOptions{Prefix: "reports/", PageToken: pageToken}) // set Recursive to list every file below
if err != nil {
return err
}
for _, file := range page.Files {
fmt.Println(file.Path, file.Size, file.Note)
}
pageToken = page.NextPageToken
if pageToken == "" {
break
}
}
if _, err := artifacts.Download(ctx, "reports/q3.pdf", "q3.pdf"); err != nil {
return err
}
// A large file, streamed. Close the reader when you're done.
body, err := artifacts.Open(ctx, "data/events.csv")
if err != nil {
return err
}
defer body.Close()
if err := process(body); err != nil {
return err
}
import { openAsBlob } from "node:fs";
const artifacts = client.artifacts(computer.id);
// A local file is a Blob: openAsBlob(path) on Node, Bun.file(path) on Bun.
await artifacts.upload("inputs/brief.pdf", await openAsBlob("brief.pdf"), { note: "Client brief" });
let pageToken = "";
do {
const page = await artifacts.list({ prefix: "reports/", pageToken }); // recursive: true lists every file below
for (const file of page.files) console.log(file.path, file.size, file.note);
pageToken = page.nextPageToken;
} while (pageToken);
await artifacts.download("reports/q3.pdf", "q3.pdf");
// A large file, streamed as a ReadableStream<Uint8Array>:
const body = await artifacts.open("data/events.csv");
await process(body);
from pathlib import Path
artifacts = client.artifacts(computer.id)
# A Path or an open binary file is read from the local disk; bytes are the file's content.
artifacts.upload("inputs/brief.pdf", Path("brief.pdf"), note="Client brief")
page_token = None
while True:
page = artifacts.list(prefix="reports/", page_token=page_token) # recursive=True lists every file below
for file in page.files:
print(file.path, file.size, file.note)
page_token = page.next_page_token
if not page_token:
break
artifacts.download("reports/q3.pdf", "q3.pdf")
# A large file, streamed. The with block closes the stream.
with artifacts.open("data/events.csv") as body:
for chunk in body:
process(chunk)
Copy and delete
copy copies a file from another of the project's Computers, or from
elsewhere in this one, inside storage. Nothing passes through your
application, whatever the file's size. It returns the new file. delete
removes one file.
# Start a new Computer with the files a previous one kept.
artifacts.copy(previous.id, "reports/q3.pdf", "inputs/q3.pdf")
artifacts.delete("reports/q3-draft.pdf")
// Start a new Computer with the files a previous one kept.
if _, err := artifacts.Copy(ctx, previous.ID(), "reports/q3.pdf", "inputs/q3.pdf"); err != nil {
return err
}
if err := artifacts.Delete(ctx, "reports/q3-draft.pdf"); err != nil {
return err
}
// Start a new Computer with the files a previous one kept.
await artifacts.copy(previous.id, "reports/q3.pdf", "inputs/q3.pdf");
await artifacts.delete("reports/q3-draft.pdf");
# Start a new Computer with the files a previous one kept.
artifacts.copy(previous.id, "reports/q3.pdf", "inputs/q3.pdf")
artifacts.delete("reports/q3-draft.pdf")
Public links
A running Computer can make a link to one of its artifacts that anyone can open to download the file, without a Pine credential. The link always serves the file's current version. It stops working when the Computer stops or its services restart, or at the expiry you set, up to 30 days; without an expiry, it works until the Computer stops. Make a new link after a Start.
The agent makes one with pine-artifact link. Your application uses the
running Computer:
link = computer.artifact_link("reports/q3.pdf", expires_in_seconds: 86_400)
link["url"] # share this
link, err := computer.ArtifactLink(ctx, "reports/q3.pdf", 24*time.Hour)
if err != nil {
return err
}
fmt.Println(link.URL) // share this
const link = await computer.artifactLink("reports/q3.pdf", { expiresInSeconds: 86_400 });
link.url; // share this
link = computer.artifact_link("reports/q3.pdf", expires_in_seconds=86_400)
link.url # share this
Anyone who has the link can download the file until it stops working, so share it only with the people the file is for.
Errors
| Error | When | What to do |
|---|---|---|
ArtifactNotFoundError |
No file at the path, for open, download, delete, or the source of copy. Its path names it. |
Check the path with list. |
ArtifactStorageFullError |
The Computer's artifacts have reached their limit. upload and copy save nothing. It reports used_bytes and limit_bytes. |
Delete files the Computer no longer needs, then save again. |
A 404 from Pine, COMPUTER_NOT_FOUND |
The Computer, or the source Computer of a copy, is unknown, deleted, or in another project. |
Check the Computer ID. A deleted Computer's artifacts can't be reached. |
| A retryable error from Pine | Pine couldn't issue a storage token. | Try again. |