Files and Git
Read, write and watch files in a sandbox, and read and change a git repository in it, over the HTTP API or the TypeScript SDK.
The files API lets a client work with the file system of a sandbox without a
shell. Use it to build an editor, a file tree or a change view next to an agent.
By default, every operation runs in the sandbox as the image user, the same
user as tektona ssh and processes. A file that you write has the
same owner as a file that the agent writes. To work on files that the image
user cannot change, see Edit files as root.
All endpoints are under /v1/sandboxes/{sandboxId} at the access endpoint of
the sandbox, not at the API host. A path is absolute, or relative to the
sandbox working directory. ~ and ~/… name the home directory of the user
that the operation runs as, for example path=~/.bashrc. The API refuses
~name with 422. A ~ later in a path, as in a/~/b, is a plain name.
Responses always contain absolute paths. The
TypeScript SDK wraps every endpoint and finds the
access endpoint for you.
Access endpoint
Read the access endpoint of a sandbox from access_endpoint in
GET /v1/sandboxes/{sandboxId}, for example
https://fr-par-1.access.sandbox.tektona.app. One access endpoint serves every
sandbox of a region. The API host answers the files endpoints with
421 use_access_endpoint. In the API reference and in the OpenAPI document,
every files and git operation names the access endpoint as its server, with the
variable access_endpoint.
ACCESS_ENDPOINT=$(curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
"$TEKTONA_API_URL/v1/sandboxes/$SANDBOX" | jq -r .access_endpoint)Send the same API key to the access endpoint. access_credentials in
GET /v1/sandboxes/{sandboxId} lists the credentials that the access endpoint
takes. A client that holds none of them, such as a browser with a session
cookie, gets a scoped access token from the API host:
POST /v1/sandboxes/{sandboxId}/access-tokens {"actions": ["sandbox.files.list", "sandbox.files.get"]}{ "token": "tsat_…", "access_endpoint": "https://fr-par-1.access.sandbox.tektona.app", "actions": ["sandbox.files.get", "sandbox.files.list"], "expires_at": "2026-10-06T08:15:00Z" }The token works on this sandbox only, for the listed actions (all files and git actions when you omit them), for 15 minutes. It still needs your permissions on the sandbox, and a change to your roles or API keys ends it. The access endpoint reads no cookie.
Access
| Operation | Who can do it |
|---|---|
| List, read, watch | Everyone who can observe the sandbox |
| Write, delete, move, create a directory, set a mode or an owner, upload an archive | Everyone who can operate the sandbox |
| Create a signed URL | Download: everyone who can observe the sandbox. Upload: everyone who can operate it |
Any file operation with user | Everyone who can operate the sandbox |
| All git operations | Everyone who can operate the sandbox |
Git needs permission to operate the sandbox because git runs the configuration and the filters of the repository. See Sharing sandboxes for who can observe and who can operate a sandbox.
A paused sandbox returns 409. Add resume=true to the query to wake it.
A sandbox that started before the files API existed returns
409 sandbox_update_required. Restart the sandbox to use the files API.
A sandbox runs at most 8 file and git operations at once, plus 2 git
operations with a remote (clone, fetch, pull, push). A call that waits more
than 10 s for its turn returns 409 busy; retry it.
A refused call returns an application/problem+json body. Its type holds
the error code, for example not_found, precondition_failed or
too_many_transfers, and detail holds a message. The
API reference lists the codes of each status.
Read files
List a directory. depth sets how many levels to return (default 1, at most
32). depth=0 returns only the entry at the path:
GET /v1/sandboxes/{sandboxId}/files?path=src&depth=2{
"entry": { "path": "/workspace/src", "name": "src", "type": "directory", "size": 4096, "mode": 493, "uid": 1000, "gid": 1000, "owner": "dev", "group": "dev", "modified_at": "2026-10-01T09:00:00Z" },
"entries": [ { "path": "/workspace/src/main.go", "name": "main.go", "type": "file", "size": 812, "mode": 420, "uid": 1000, "gid": 1000, "owner": "dev", "group": "dev", "modified_at": "2026-10-01T09:00:00Z" } ],
"truncated": false
}A listing never follows a symlink below path. A symlink is listed with its
symlink_target, also when the target is missing. When path itself is a
symlink to a directory, the listing shows the entries of that directory, as
ls link/ does.
To skip folders in one call, repeat exclude (64 at most). A name without
/ matches at any depth, and a name with / matches a path below path:
GET /v1/sandboxes/{sandboxId}/files?path=.&depth=5&exclude=node_modules&exclude=web/distgitignore=true skips what git ignores in the repository, and the .git
folder. It needs write access to the sandbox, because git runs the
repository's configuration. Outside a repository it returns 422 not_a_git_repository. A skipped entry does not count against limit.
A listing returns 5000 entries by default (limit, at most 20000). It lists
level by level, in name order inside each folder. It stops at limit or at
about 6 MiB of reply, and sets truncated: true. per_dir_limit keeps the
first entries of each folder in name order, so that one large folder such as
node_modules does not use up limit:
GET /v1/sandboxes/{sandboxId}/files?path=.&depth=3&per_dir_limit=200A cut listing names, in truncated_paths, each folder that it did not fully
list. The order is the order of the listing. A folder in entries above
depth that is not in truncated_paths is complete, unless you cannot read
it. To get the rest of a folder from truncated_paths, list it again without
per_dir_limit, with the depth that remains below it. That listing can be cut
too. truncated_paths can name path itself: a folder with more entries than limit (at most 20000) cannot be
listed in full, so skip a part of it with exclude. A folder of more than
100,000 entries returns 413 (see Transfer limits). A
folder that the listing did not read can turn out to be empty:
{
"entry": { "path": "/workspace", "type": "directory" /* … */ },
"entries": [ /* … */ ],
"truncated": true,
"truncated_paths": ["/workspace/node_modules", "/workspace/web"]
}mode holds the permission bits as a decimal integer: 493 is 0o755.
owner and group are the names of uid and gid in the sandbox's
/etc/passwd and /etc/group. They are absent when those files have no name
for the id.
Read a file of any size. The response body contains the raw bytes:
GET /v1/sandboxes/{sandboxId}/files/content?path=src/main.goAn unconditioned read of a file up to 1 MiB has a strong SHA-256 ETag.
Larger reads stream without an ETag. Use HEAD to get the size and an
ETag for a file up to 1 GiB. Send If-None-Match on GET to get 304 when
a file up to 1 GiB has not changed. Files above 1 GiB do not support
conditional reads or saves. A Range read has no ETag.
With Range and If-None-Match, a matching ETag returns 304 before the range runs.
HEAD ignores Range. A range outside the file returns 416 with Content-Range: bytes */<size>.
To resume a download, send Range: bytes=<offset>- with If-Range: <ETag>.
When the file still has that strong ETag, the reply is 206 with the rest
and the ETag. When the file changed, the reply is 200 with the whole file.
If-Range with a date or a weak ETag, or for a file above 1 GiB, always
gets the whole file.
Write files
Send the raw bytes as the request body, with no file size limit. Missing parent directories are created:
PUT /v1/sandboxes/{sandboxId}/files/content?path=src/main.go
If-Match: "9f86d08…"If-Matchwrites only when the file still has thisETag. Otherwise the API returns412with the codeprecondition_failed.If-Matchaccepts a current file up to 1 GiB. Above that size, the API returns422 invalid_argumentbefore the upload starts.If-None-Match: *writes only a new file.modesets the permission bits as a decimal integer from 0 to 4095, for examplemode=493for0o755. The file gets the mode before it replaces the target, so a script never appears without its execute bit.
When a write returns, the bytes of the file are on disk: the API syncs the
temporary file before it replaces the target, and then tries to sync the
folder. If the file sync fails, the write fails with 500 internal and the old
file stays. A crash of the sandbox in the first seconds after a write can bring
back the old file, complete, but never a half-written one.
The API uploads to a temporary file before it replaces the target. A cut upload leaves the old file. The new file has a new inode, so reload it in an editor. Hard links keep the old bytes. The API follows a symlink and keeps the old mode without setuid and setgid. An upload as root keeps the old owner. Guest processes do not share the API path locks.
Delete and move:
DELETE /v1/sandboxes/{sandboxId}/files?path=build&recursive=true
PUT /v1/sandboxes/{sandboxId}/files/move {"from": "a.txt", "to": "b.txt", "overwrite": false}A directory that is not empty needs recursive=true. A recursive delete removes
a directory symlink, but not the directory that it points to. A move to an
existing path needs "overwrite": true.
Create a directory, set a mode, and set an owner:
PUT /v1/sandboxes/{sandboxId}/files/directory {"path": "build/out", "mode": 448}
PUT /v1/sandboxes/{sandboxId}/files/mode {"path": "run.sh", "mode": 493}
PUT /v1/sandboxes/{sandboxId}/files/owner {"path": "run.sh", "owner": "dev", "group": "dev", "user": "root"}files/directory creates the missing parents too, like mkdir -p. mode
applies only to the last directory, and only when the call creates it. The
reply has "created": false when the directory was there already. Another
entry at the path returns 409 already_exists. files/mode follows a
symlink and is not recursive. Only the owner of a file, or root, can change
its mode.
files/owner works like chown. owner and group take a name from the
sandbox's /etc/passwd and /etc/group, or a number. Omit one to keep it. It
follows a symlink and is not recursive. Only root can change the owner, and the
owner of a file can change its group only to one of its own groups. Anything
else returns 403 permission_denied.
Download a folder
Download a file or a folder as one tar or tar.gz archive. Repeat exclude to
skip build output: a name without / matches at any depth, and a name with
/ matches a path relative to path.
curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
"$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/app&format=tar.gz&exclude=node_modules&exclude=.git" \
-o app.tar.gzNames in the archive are relative to path. To download several files or
folders in one archive, repeat path, up to 64 times. Each one then goes in
under its base name, in the order given, and two paths with the same base name
return 422. An exclude with / then matches a name in the archive, such
as app/build:
curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
"$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/app/README.md&path=/workspace/app/src&path=/var/log/app.log" \
-o files.tarSymlinks stay links, and the archive keeps modes, owners and modification times. Fifos, sockets and devices are skipped. A download that fails partway breaks the response, so a short archive never looks complete: check the exit code of your client. An archive takes one transfer slot.
Upload a folder
Upload a tar or tar.gz archive to extract it into a directory. The directory and its parents are created:
tar -C ./site -czf - . | curl -sf -X PUT --data-binary @- \
-H "Authorization: Bearer $TEKTONA_API_KEY" \
"$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/site&format=tar.gz"{ "root": "/workspace/site", "files": 42, "directories": 7, "symlinks": 1, "bytes": 183920 }Each file is written to a temporary file and renamed over the old one, with the
mode and modification time from the archive. An entry with the PAX record
TEKTONA.keep_mode=1 keeps the mode of the file that it replaces, without
setuid and setgid; a new file gets the mode of the entry. A cut upload never leaves a
half-written file. The archive as a whole is not atomic: a failure keeps the
entries before it, and the error detail names the failed entry and how many
entries were written. For all or nothing, upload into a new directory, then
move it with files/move.
An absolute name, a .. component, a name below a symlink from the same
archive, a file over such a symlink, a device or a fifo fails with 422 invalid_argument. A hard link
must point to an earlier file of the archive.
Share a file with a signed URL
A signed URL lets a client without Tektona credentials, such as a CI job or a browser, download or upload one file, or download a folder. Create it on the API host with your own credentials. The URL points at the access endpoint:
POST /v1/sandboxes/{sandboxId}/files/signed-url {"path": "dist/app.zip", "method": "GET", "expires_in": 300}{ "url": "https://fr-par-1.access.sandbox.tektona.app/v1/files/signed?token=…", "method": "GET", "expires_at": "2026-10-06T08:05:00Z", "single_use": false }Then use the URL with no other header:
curl -sf "$URL" -o app.zip
curl -sf -X PUT --data-binary @report.pdf "$UPLOAD_URL"- Add
"format": "tar"or"format": "tar.gz"to aGETURL to download the folder atpathas one archive, asfiles/archivedoes. An archive URL takesGETonly. - A URL expires after
expires_inseconds, 300 by default and 900 at most. - A
GETURL also takesHEAD,RangeandIf-None-Match. APUTURL uploads once. An upload that starts uses the URL up, also when it fails. A refusal before the upload starts (409for a paused sandbox,429,503when the sandbox cannot be reached) keeps the URL, so you can retry with it. A signed URL does not resume a paused sandbox: resume it with the API first. APUTURL takesIf-Match,If-None-Match: *andmode. On a signed URL,modetakes the permission bits only (0 to 511); setuid, setgid and sticky return422. - Creating a
GETURL needs permission to observe the sandbox. APUTURL or auserneeds permission to operate it. A change to the permissions of its creator, or to the sharing of the sandbox, ends the URL with403. - The URL is the credential: share it only with the client that needs it. A
refused URL returns
401 signed_url_invalid,410 signed_url_expiredor410 signed_url_used. - Any web origin can use a signed URL; the browser sends no cookies with it.
Transfer limits
The access endpoint allows 32 transfers per sandbox. Additional requests
return 429 too_many_transfers. A transfer
stops when it moves less than 256 KiB in a minute. A failed download can end
before its declared Content-Length. Check the byte count before you use the
file.
A download is application/octet-stream, or application/x-tar or
application/gzip for an archive, with Content-Disposition: attachment and
the last part of the path as the file name. A browser saves it and never shows
it as a page.
A recursive delete, a folder download or a list fails with 413 too_large
for a folder of more than 100,000 entries or a tree of more than 256 levels.
A list instead skips the entries of such a subfolder, sets truncated and
names the subfolder in truncated_paths. A list of that subfolder itself
returns 413 too_large; skip it with exclude. A folder download stops after one hour.
Edit files as root
Every file operation takes an optional user, a user name or a uid. The
operation then runs as that user, the same as tektona ssh --user and
tektona sandbox cp --user. Set user on list, read, write and delete as a
query parameter, and on move and watch in the JSON body:
GET /v1/sandboxes/{sandboxId}/files/content?path=/etc/hosts&user=root
PUT /v1/sandboxes/{sandboxId}/files/content?path=/etc/hosts&user=rootAny operation with user needs permission to operate the sandbox, also a read.
A relative path resolves against the working directory of that user, as it does
for tektona sandbox cp --user. ~ names the home directory of that user, so
path=~/notes.txt&user=root names /root/notes.txt. Git operations always run
as the image user.
Git
| Endpoint | Returns |
|---|---|
GET git/status?path= | Branch, upstream, ahead and behind counts, and the changed, untracked and conflicted files |
GET git/diff?path=&base= | Per-file changes against base (default HEAD), staged and unstaged, plus untracked files |
GET git/diff/summary?path=&base= | Counts of changed, added, deleted, and unknown-line files, plus changed lines |
GET git/patch?path=&base=&file=&context= | One unified patch of the staged, unstaged and untracked changes against base, as text/x-diff |
GET git/blob?path=&oid= | The raw bytes of a blob, 4 MiB at most |
GET git/files?path= | The tracked and untracked, not ignored paths, for a file picker |
GET git/ignored?path= | The paths that git ignores; a folder that git ignores as a whole is one path that ends in / |
path is a directory in the repository. To show a diff of one file, read the
current file with files/content and the base side with git/blob and the
old_oid from git/diff.
Each diff file has a lines object with additions and deletions.
The counts describe changed lines, not the total length of a file.
The lines value is null for binary files and files without a known line count.
The summary counts those files in files.binary and excludes them from lines.
git/patch returns a patch that git apply -p1 takes in the work tree root.
It includes binary files and untracked files that git does not ignore. Repeat
file to limit it to some paths, relative to the root. The
Tektona-Git-Root header holds the root, and Tektona-Git-Base holds the
commit that the patch compares with. A patch above 6 MiB stops after its last
complete file and has Tektona-Git-Truncated: true.
curl -s -H "Authorization: Bearer $TEKTONA_API_KEY" \
"$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/git/patch?path=/workspace/app" -o changes.diff
git apply -p1 changes.diffA very large work tree, for example a build folder that git does not ignore,
does not fail git/status, git/diff or git/diff/summary. The reply then has
truncated: true. git/status lists only the first files, but the branch fields
stay correct. git/diff misses the files after the cut, or has lines: null for
them. The summary counts are lower bounds.
To keep a change view current, read git/status again 300 ms after the last
changes frame of a watch, once more a second later, and
every 30 seconds while the view is visible. Calls for the same repository
within one second share one result, so many viewers cost the sandbox one
git status. That is why a read right after a change can still show the
state before it.
Change a repository
| Endpoint | Does |
|---|---|
POST git/clone | Clone url into path; returns the root of the new work tree |
GET git/log?path=&ref=&limit=&skip= | Commits of ref (default HEAD), newest first; limit is 50 by default and 500 at most |
GET git/branches?path= | The local branches with upstream and ahead and behind counts, and the current branch |
POST git/branches | Create the branch name at start_point; checkout switches to it |
DELETE git/branches?path=&name=&force= | Delete a branch; an unmerged branch needs force=true |
PUT git/checkout | Switch to the local branch ref, or detach HEAD at any other revision |
PUT git/stage | Stage files, or the whole work tree when files is empty |
PUT git/unstage | Unstage files, or the whole work tree when files is empty |
PUT git/discard | Restore the tracked files to their staged content; the changes are lost |
POST git/commits | Commit the staged changes; returns the oid |
PUT git/fetch, git/pull, git/push | Fetch from, pull from or push to remote and branch |
POST git/init | Create a repository at path, with initial_branch as the first branch; returns the root |
PUT git/reset | Move the branch to ref (default HEAD). mode is soft, mixed (default) or hard. files reset index entries only and need mixed |
PUT git/restore | Restore files in the work tree (default), the index (staged), or both, from source; the work tree changes are lost |
GET git/remotes?path= | The remotes with their fetch and push URLs. The URLs never hold credentials |
POST git/remotes, DELETE git/remotes?name= | Add the remote name with an HTTPS url that has no credentials, or remove it |
GET git/config?key=, PUT git/config | Read or write key in the repository config. Allowed keys: user.name, user.email, core.autocrlf, pull.rebase, init.defaultBranch |
POST /v1/sandboxes/{sandboxId}/git/commits
Content-Type: application/json
{ "path": "/workspace/app", "message": "Fix the login form", "all": true }files are paths relative to the repository root. Git reads them literally, so
* is a file name, not a pattern.
A commit takes the author from author_name and author_email. Without them,
the git configuration in the sandbox must set user.name and user.email,
else the API returns 422 git_identity_missing. A commit with nothing to
commit returns 409 nothing_to_commit, unless you set allow_empty. all
commits the changes to tracked files, as git commit --all does. It does not
add new files: stage them first. A commit runs the hooks of the repository as
the image user.
Clone, fetch, pull and push connect to the remote. An HTTPS remote signs in with
the git credentials of the project, which the egress
gateway adds. The sandbox never holds the credentials. Clone takes an https://
URL only: plain http:// and SSH remotes are not supported, and a URL with
credentials returns 422 invalid_argument. remote and branch of fetch,
pull and push are names: a refspec with : or a leading + returns
422 invalid_argument. Use force_with_lease to force a push.
Changes to one repository run one at a time. Fetch and push do not wait, and
neither do writes through the files endpoints. A command that git refuses
returns 422 git_failed with the message of git. A command with a remote stops
after 4 minutes, any other command after 2 minutes. When a request times out,
the command can still have run: read git/status or git/log to see the
result. A 502 unknown_outcome response means the connection ended after a git
write request was sent. The command can have completed. Check the repository
before you retry.
The image must contain git. Otherwise the API returns 422 with the code
git_not_installed.
Watch for changes
A watch streams changes under a directory over a WebSocket at the access endpoint:
GET /v1/sandboxes/{sandboxId}/files/watch?path=src&recursive=true&exclude=node_modules&exclude=.gitSend the credential in Authorization. A browser cannot set that header on a
WebSocket, so it offers the protocols tektona.files.v1 and
Bearer-<credential>, for example with a scoped access token. The server
selects tektona.files.v1.
An exclude entry without /
matches a directory name at any depth. An entry with / matches a path
relative to the watched directory. A watch sends no change for an excluded
directory or for anything in it.
Many clients can watch the same directory. Watches with the same path,
recursive, exclude, include_entry and user share one watch in the sandbox. A sandbox has
at most 16 different watches and 512 open watches. A watch past either limit
ends with too_many_watches. A client that falls 256 frames or 8 MiB behind
the others ends with slow_consumer and does not slow the others down.
A watch expires after 15 minutes. The server closes it without end.
A watch ends within 15 seconds when the caller loses access to the sandbox or
the user is deactivated, with end reason forbidden and close code 1008.
A revoked API key does not end an open watch; the watch still expires.
The server sends JSON text frames:
{ "type": "ready", "seq": 1, "path": "/workspace/src" }
{ "type": "changes", "seq": 2, "changes": [ { "path": "/workspace/src/a.go", "op": "modified", "type": "file" } ] }
{ "type": "resync", "seq": 3, "reason": "overflow" }
{ "type": "end", "reason": "sandbox_paused" }op is created, modified, removed, renamed or chmod:
renamedmovesold_pathtopath. A renamed directory is followed bycreatedfor each entry under it. A move into or out of the watched directory is acreatedor aremoved.chmodmeans that the mode, the owner or a time of the entry changed.
A write through the files API shows as one created or modified of the
file. The temporary file of the write does not show.
Set include_entry=true to get the entry, in the shape that the list returns,
in entry on each change except removed.
end is the last frame. Its
reason tells why the watch stopped, for example sandbox_paused,
not_found, too_many_watches, or forbidden when you lost access to the
sandbox. A watch does not follow a symlink at path: it ends with
not_a_directory. Watch the target directory instead.
To keep a correct view of the directory, follow these rules:
- Open the WebSocket and wait for
ready. - List or read what you need. Keep the frames that arrive meanwhile.
- Apply the kept frames, then each new frame.
- On
resync, drop the kept frames and list again. - If
seqskips a number, a frame is not valid, or the socket closes withoutend, you lost changes. Open a new watch and start again at step 1.
The TypeScript SDK checks rule 5 for you and throws FilesWatchLostError.
Processes
Run one-off commands, background servers, and interactive shells inside a sandbox — and manage them long after the client disconnects.
Secrets
Store a credential once as a project secret, shared with everyone on the project. Scope it to just yourself when you need to, and Tektona keeps it encrypted and out of your sandboxes.