Files and one off tasks for agents

This reference extends https://app.tokay.io/llms.txt with deployed file and one off task operations for AI agents. Use these operations only when the user explicitly asks or a named readiness action requires them.

Last updated

AI agent? Start with llms.txt.

The file model

  • Every Service has two file scopes. SAVED is durable application storage that survives deploys and restarts and is available to the running Service and one off tasks. CURRENT is the filesystem of the running Service instance. It is read only evidence and disappears when that instance is replaced.
  • service.fileRoots is the map. Each root is an absolute runtime path such as /tokay/data or /app/uploads. Every path you pass on this page must be inside one of these roots. /tokay/data always exists, and so does /tokay/shared, the Project's shared directory (isSharedWithProject: true), which lists the same files from every Service in the Project.
  • SAVED roots come from declared storage paths. Tokay detects the places the code writes, such as ./uploads, during analysis and declares them for you (author TOKAY). One the code ships nothing at, or a SQLite database, becomes ATTACHED on its first deploy. One the code ships files at waits for a choice (awaitingConfirmation). You can declare more.
  • Listings validate paths immediately. Ticket minting validates nothing. A wrong path in a download or upload ticket fails at redemption, not at mint, so verify paths against a listing first.
  • SAVED files live on the workspace disk, so a SAVED listing and SAVED download and upload tickets wake a sleeping workspace. While it starts, a ticket returns a null URL and retryAfterSeconds, and a listing fails with reason WORKSPACE_WAKING and extensions.retryAfterSeconds. Wait that long and repeat the call. fileRoots never wakes it.
  • A one off task is the only exec path. There is no SSH. runServiceTask runs the command against the Service's deployed version with its full runtime environment and SAVED storage, then records the output.

What to call

To Use
See which directories are durable service.fileRoots
List files in a scope service.files(scope:, path:)
Download files createServiceFileDownloadTicket, then GET the URL
Upload into durable storage createServiceFileUploadTicket, then PUT the bytes
Save a live file before it disappears copyCurrentFileToSaved
Run a bounded command runServiceTask, then poll releaseExecution
Inspect declared durable directories service.storagePaths
Make another directory durable createServiceStoragePath

Find the roots, then list inside them

query Files($id: ID!) {
  service(id: $id) {
    fileRoots { path scope durability isVisibleToTasks isWritable survivesDeploy isSharedWithProject }
    files(scope: SAVED, path: "/app/uploads", first: 200) {
      nodes { name path type sizeBytes updatedAt }
      currentInstanceRef
    }
  }
}

Query fileRoots first and list inside a root. Listing path: "/" fails with "Path is not inside Saved service files" unless / is itself a root, which is true only for CURRENT. Entry type is FILE, DIRECTORY, or SYMLINK. A CURRENT listing needs a running Service instance and returns currentInstanceRef. Save that ref when you plan to rescue.

Download files

mutation DownloadTicket($service: ID!, $paths: [String!]!) {
  createServiceFileDownloadTicket(input: {
    service: $service,
    scope: SAVED,
    paths: $paths,
    format: RAW
  }) {
    serviceFileDownloadTicket { downloadUrl expiresAt retryAfterSeconds }
  }
}

Then GET {downloadUrl} with no Authorization header. The URL is the authorization and works for an hour. One SAVED file has no size limit and resumes on the same URL with Range. HEAD gives its size and ETag. Keep the ETag of the first response (curl -D HEADERS -o FILE "$URL") and send that same one as If-Range on every resume (curl -C - -H "If-Range: $ETAG" -o FILE "$URL"), never one read later, which would let a file that changed in between splice. If it changed, curl exits 33 instead: delete FILE and download it from the start. Once curl exits 0, HEAD the URL: an ETag other than the one you kept means the file changed, so download it again from the start. A TAR_GZ archive or a CURRENT file streams whole, so a broken one starts over. Use RAW for one file and TAR_GZ for several paths or a directory. Minting succeeds even for paths outside SAVED. The GET then returns HTTP 400 with reason: SERVICE_FILE_PATH_NOT_SAVED. For a CURRENT download pass scope: CURRENT plus expectedCurrentInstanceRef from a listing.

Upload into durable storage

mutation UploadTicket($service: ID!) {
  createServiceFileUploadTicket(input: {
    service: $service,
    destinationPath: "/app/uploads/report.csv",
    overwrite: true,
    expectedSizeBytes: "1024"
  }) {
    serviceFileUploadTicket { uploadUrl maxBytes expiresAt retryAfterSeconds }
  }
}

Then PUT {uploadUrl} with the raw bytes as the body. Success returns HTTP 201 with {"sha256": "...", "sizeBytes": N}. expectedSizeBytes is a BigInt scalar, so send it as a string in JSON variables. destinationPath must be absolute inside a SAVED root. A wrong destination fails at PUT with reason SERVICE_FILE_DESTINATION_NOT_SAVED. The running app sees the file immediately, with no restart. Respect the returned maxBytes.

Rescue a live file

If the app wrote something important outside durable storage, copy it into SAVED before the instance changes.

mutation Rescue($service: ID!, $ref: String!) {
  copyCurrentFileToSaved(input: {
    service: $service,
    sourcePath: "/app/report.json",
    destinationPath: "/app/uploads/report.json",
    expectedCurrentInstanceRef: $ref,
    overwrite: true
  }) {
    currentFileCopy {
      id
      state
      failure { action code message supportRef }
    }
  }
}

The copy is asynchronous. Poll currentFileCopy(id:) until state reaches SUCCEEDED or FAILED (PENDING and RUNNING come first). expectedCurrentInstanceRef must come from a CURRENT listing. If the Service instance was replaced between your read and the copy, the guard fails the copy instead of copying a different instance's file. List the files again and retry. After a rescue, declare the source directory durable so future writes survive on their own.

Run a one off task

mutation Task($service: ID!, $commandArgv: [String!]!) {
  runServiceTask(input: { service: $service, commandArgv: $commandArgv }) {
    releaseExecution { id }
  }
}

commandArgv is an argument vector, not a shell string. Wrap pipes and chains in ["sh", "-c", "..."]. The working directory defaults to the service root, so relative paths like uploads resolve against /app. Pass workingDirectory to change it. Poll the returned row:

query TaskResult($id: ID!) {
  releaseExecution(id: $id) { state exitCode logTail }
}

state reaches SUCCEEDED or FAILED. Simple commands finish in a few seconds. The task runs against the Service's deployed version with its full runtime environment, including Project Config, Secrets, database URLs, and SAVED storage. It also sets TOKAY_PROCESS=task, so code that starts work when it loads can skip it rather than run a second copy of the live Service's loop. The run is attributed to your identity and credential. The command must exit. Tokay stops and fails a task still running after three hours. A server or a watch loop belongs in a Service. A task also runs while the Service is stopped, from its deployed version, so stop the Service first when a repair must not race the running app, such as fixing a SQLite file or migrating data. The Service stays stopped, and a sleeping workspace starts for the task.

To read app state, query the managed database (queryProjectResource, MCP query_database) or download SAVED files rather than running a task. Tasks are the right tool for data fixes. The managed database query endpoint is read only, but a task's framework client holds real credentials from the environment. Schema changes should still ship as migrations with a deploy, which rehearses the change, takes a snapshot, and applies Project release safety before production changes.

Durable directories

query StoragePaths($id: ID!) {
  service(id: $id) {
    storagePaths(first: 20, orderBy: [AWAITING_CONFIRMATION_DESC, PATH_ASC]) {
      nodes { id path state author awaitingConfirmation }
    }
  }
}

path is relative to the service root, so uploads mounts at /app/uploads. States are PENDING (recorded, mounts after clean build evidence or user confirmation), ATTACHED (mounted and durable), and DETACHED (intentionally unmounted, row kept as a tombstone, data preserved). awaitingConfirmation is true on a Tokay-suggested path where the deployed code ships files too, and deployReadiness then carries CONFIRM_STORAGE_PATH. Keep a path the app writes with reattachServiceStoragePath(input: { serviceStoragePath: $id, hideImageFiles: true }): a PENDING one starts persisting, and an ATTACHED one keeps its stored data over the code's copy. Reject a path the app only reads with detachServiceStoragePath, so every deploy serves the code's copy. Ask the user first when an ATTACHED path may hold data they want. Check the existing list before declaring anything. Tokay usually detected the app's write directories already, so add one only when the user asks or the app demonstrably writes somewhere undeclared, with createServiceStoragePath(input: { service: $service, path: "data" }). Apart from answering CONFIRM_STORAGE_PATH, detach or clear data only when the user asks. detachServiceStoragePath stops mounting but keeps the stored data, reattachServiceStoragePath reverses it, and destroying data is the separate clearServiceStoragePathData. A storage path change (add, keep, detach or reattach) redeploys the running version and takes effect at that deploy's cutover: until then the running version keeps its mounts, so a Saved Files upload to a just-added path fails until its deploy is live, and clearServiceStoragePathData refuses with STORAGE_PATH_STILL_MOUNTED while a running or deploying version or an unfinished service task still mounts the path. New code should skip all of this and write under TOKAY_DATA_DIR. These files belong to one Service and its copies. Files other Services in the Project read go under TOKAY_SHARED_DIR (/tokay/shared), which every Service, scheduled run, and service task mounts and release commands do not. A file there keeps its writer's owner and mode, and an upload belongs to the runtime user of the Service it went through, so a Service whose own Dockerfile runs as another non-root user can read it but not replace it. A directory sends no notice when a file changes, so messages between Services belong in Redis or HTTP, and state that the app queries usually fits a managed database better. See Managed databases for agents.

Error shapes

You see It means Do this
GraphQL error "Path is not inside Saved service files" Listing or mutation path is outside the declared roots Query fileRoots, use an absolute path inside a root
Ticket with a null URL and retryAfterSeconds, or GraphQL error reason: WORKSPACE_WAKING The ticket or listing woke a sleeping workspace, which is still starting Wait retryAfterSeconds, then repeat the same call
HTTP 409 reason: WORKSPACE_NOT_RUNNING on ticket GET or PUT, or on a CURRENT listing The workspace stopped after the ticket was minted, or was stopped while its Service runs For SAVED, mint a new ticket, which wakes it. For CURRENT, the workspace must be started first
HTTP 400 reason: SERVICE_FILE_PATH_NOT_SAVED on ticket GET The download ticket was minted with a bad path List the files again, then mint a new ticket with the listed path
HTTP 400 reason: SERVICE_FILE_DESTINATION_NOT_SAVED on PUT Upload destination is outside SAVED Target an absolute path inside a SAVED root
state: FAILED with failure.action: CHANGE_INPUT The request is stale or invalid Read failure.message. If the current instance changed, list CURRENT again and retry with the fresh currentInstanceRef
state: FAILED with another action The copy needs retry, a running Service, or support Follow failure.action and surface failure.code plus failure.supportRef
FORBIDDEN with a reason such as PROJECT_WRITE_FILES_REQUIRED Your credential or membership lacks that action on targetId Report the missing grant (requiredAction) to the user instead of retrying