Work with sandbox files

Use write_file(path, content) to write bytes into the sandbox. It creates parent directories and returns after the write completes. read_file() reads the active VM without taking a snapshot. The next command reuses that VM, including its running processes. A cold session reads its saved image; pending staged files start a VM so reads include those inputs.

Use session.list_dir(path) for directory entries and session.grep(pattern, ...) to search file contents. These methods use the same current filesystem as read_file(). Both synchronous and asynchronous sessions provide all four methods.

This example writes /input.txt, runs a command to copy it to /output.txt, and reads the result back as bytes. Configure a connection as described in Connection sources.

"""Write and read files in one sandbox session."""

from contree_sdk import create_sandbox_session


def main() -> None:
    with create_sandbox_session(image="tag:alpine:latest") as session:
        session.write_file("/input.txt", b"Hello from a file!\n")
        session.run(shell="cat /input.txt > /output.txt")
        content = session.read_file("/output.txt")
        print(content.decode())


main()

import asyncio

from contree_sdk import create_sandbox_session


async def main() -> None:
    async with create_sandbox_session(image="tag:alpine:latest") as session:
        await session.write_file("/input.txt", b"Hello from a file!\n")
        await session.run(shell="cat /input.txt > /output.txt")
        content = await session.read_file("/output.txt")
        print(content.decode())


asyncio.run(main())

Both programs print Hello from a file!. read_file() sees both writes without stopping the VM. Normal context exit saves them. With ContreeSession, each command saves by default; disposable=True leaves the previous image selected.

Note

Async snippets with top-level await run inside an async function or a notebook that supports it. For a standalone script, use the asyncio.run(main()) structure from Your first sandbox.

Use run(files={"/input.txt": Path("local.txt")}, command="cat", args=["/input.txt"]) to make a local file available before the command starts. A LazySession applies the file to its running VM, including on the first call; a ContreeSession attaches it at operation startup. Directory sources expand into individual files on both paths, so empty directories are omitted. Live placement uses mode 0644 and the VM runtime user; explicit non-default UploadFileSpec ownership or mode is rejected for LazySession.

List directories and search files

Use list_dir() and grep() directly on the session. Both return structured results that you can print directly. Directory listings default to a detailed format like ls -l. Paths start at the filesystem root, independently of the command working directory.

from contree_sdk import create_sandbox_session


with create_sandbox_session(image="tag:alpine:latest") as sandbox_session:
    sandbox_session.write_file("/work/message.txt", b"Hello from ConTree!\n")

    directory = sandbox_session.list_dir("/work")
    print(directory)

    matches = sandbox_session.grep("Hello", path="/work/message.txt", max_total=20)
    print(matches)

from contree_sdk import create_sandbox_session


async with create_sandbox_session(image="tag:alpine:latest") as sandbox_session:
    await sandbox_session.write_file("/work/message.txt", b"Hello from ConTree!\n")

    directory = await sandbox_session.list_dir("/work")
    print(directory)

    matches = await sandbox_session.grep("Hello", path="/work/message.txt", max_total=20)
    print(matches)

matches.matches contains the structured matches. Check matches.truncated when a search must be complete. Use glob, case, before, and after to select files and include context lines.

Advanced: choose a file source

Input

Meaning

files={"/input.txt": b"content"}

Upload bytes directly.

files={"/input.txt": "local.txt"}

Read a local file; the string is a path, not file content.

files={"/input.txt": Path("local.txt")}

Read a local file using a path object.

files=["local.txt"]

Upload the file to /local.txt.

files={"/tool.sh": UploadFileSpec(...)}

Set ownership and mode for startup attachments.

Destination paths refer to the remote filesystem. Source paths refer to your local machine. A duplicate destination in a list raises ValueError before execution. The standard transfer component uses the client’s ensure_file() to reuse uploads by content. A saved upload does not by itself change a session image.

See Customize the SDK to replace file transfer.

Advanced: upload an executable script

Use UploadFileSpec to set a mode. This example runs the uploaded script directly. Its output is script output. It is disposable because the script is not needed by a later command.

from contree_sdk import ContreeSession, create_sandbox_session
from contree_sdk.files import UploadFileSpec


with create_sandbox_session(session_type=ContreeSession, image="tag:alpine:latest") as session:
    script = UploadFileSpec(source=b"#!/bin/sh\necho 'script output'\n", mode=0o755)
    result = session.run("/tool.sh", files={"/tool.sh": script}, disposable=True)
    print(result.stdout)

from contree_sdk import ContreeAsyncSession, create_sandbox_session
from contree_sdk.files import UploadFileSpec


async with create_sandbox_session(session_type=ContreeAsyncSession, image="tag:alpine:latest") as session:
    script = UploadFileSpec(source=b"#!/bin/sh\necho 'script output'\n", mode=0o755)
    result = await session.run("/tool.sh", files={"/tool.sh": script}, disposable=True)
    print(result.stdout)

Advanced: stage files for a later command

stage_files() uploads content and appends a stage history entry. It does not start a VM or change the image. pending_files() returns the uploaded UUID, destination path, and permissions for each pending attachment.

Use a SQLite store to keep staging between processes. The next run() or spawn() attaches pending files from its source history entry. Local sources are no longer needed after staging succeeds.

This example stages a configuration file, closes the store, and resumes the session. A committed run consumes the attachment. Rolling back that run restores the pending attachment with its original permissions.

from contree_client import profiles
from contree_client.sync import ContreeClient

from contree_sdk import ContreeSession
from contree_sdk.files import UploadFileSpec
from contree_sdk.store import SyncSQLiteStore


with ContreeClient.from_profile(profiles.from_env() or profiles.resolve_profile()) as client:
    with SyncSQLiteStore("staging.db") as store:
        session = ContreeSession(client, image="tag:alpine:latest", session_id="edit-demo", store=store)
        config_file = UploadFileSpec(source=b"mode=test\n", uid=1000, gid=1000, mode=0o640)
        staged = session.stage_files({"/work/config.ini": config_file})
        pending = session.pending_files()
        assert pending[0].mode == 0o640

    with SyncSQLiteStore("staging.db") as store:
        session = ContreeSession(client, session_id="edit-demo", store=store)
        assert session.pending_files() == pending
        session.run(shell="cat /work/config.ini")
        assert session.pending_files() == ()
        session.rollback()
        assert session.tip_id == staged.id
        assert session.pending_files() == pending

from contree_client import profiles
from contree_client.asyncio import ContreeAsyncClient

from contree_sdk import ContreeAsyncSession
from contree_sdk.files import UploadFileSpec
from contree_sdk.store import AsyncSQLiteStore


async with ContreeAsyncClient.from_profile(profiles.from_env() or profiles.resolve_profile()) as client:
    async with AsyncSQLiteStore("staging-async.db") as store:
        session = ContreeAsyncSession(client, image="tag:alpine:latest", session_id="edit-demo", store=store)
        config_file = UploadFileSpec(source=b"mode=test\n", uid=1000, gid=1000, mode=0o640)
        staged = await session.stage_files({"/work/config.ini": config_file})
        pending = await session.pending_files()
        assert pending[0].mode == 0o640

    async with AsyncSQLiteStore("staging-async.db") as store:
        session = ContreeAsyncSession(client, session_id="edit-demo", store=store)
        assert await session.pending_files() == pending
        await session.run(shell="cat /work/config.ini")
        assert await session.pending_files() == ()
        await session.rollback()
        assert session.tip_id == staged.id
        assert await session.pending_files() == pending

Staging follows history ancestry. A new branch inherits the pending files at its starting entry. Staging another version of the same path changes only that branch. Rolling back a staging entry restores the previous version, if one exists.

Explicit run(files=...) attachments take precedence over pending files with the same destination. A committed result records all attached paths as applied, including those explicit replacements. A disposable run, failed operation, cancelled operation, or failed commit leaves the source staging available. Nonzero command exit codes follow the session’s normal commit behavior.

Concurrent operations retain their original parent. Their results become siblings; a late result does not replace a newer local selection. Use commit_result(operation, branch="result") to select its result explicitly.

read_file() reads the current image; staged attachments appear there only after a committed run. For LazySession, pending attachments enter the VM at startup and are consumed when its snapshot commits. Stage inputs before starting that VM.

Staging and pending-file resolution belong to Session. Store persists their nodes without interpreting file attachments. Rollback changes only the local selection; pass node_id=staged.id to resume that position in another process. Stored file references do not guarantee that the uploaded UUID still exists on the server.

Advanced: prepare directory trees and stream large files

Directory sources expand into regular-file attachments. For example, files={"/app": Path("project")} uploads the contents of project under /app. Use prepare_file_tree() for exclusions and ownership. It returns ordinary UploadFileSpec objects that can be passed to a session or a transfer component.

Patterns match relative POSIX paths. Patterns without / also match basenames at any depth; matching directories are excluded with their contents. Permission bits are preserved unless mode= is supplied. Ownership defaults to uid=gid=0. Symlinks and special files raise ValueError; empty directories are omitted because spawn attachments represent files. Normalized destination conflicts are rejected before uploads start, including a file that would be another file’s parent.

Client-backed transfers send local files as binary streams. Keep source files unchanged until the upload completes, or use Reuse uploads and retain their sources for a stable temporary snapshot. Bytes inputs are already in memory. read_file() still returns the whole file; use iter_file() or download_file() for large results.

The examples upload a directory with an exclusion, then stream a result into a local file. Configure a connection as described in Connection sources.

from pathlib import Path

from contree_client import profiles
from contree_client.sync import ContreeClient

from contree_sdk import ContreeSession
from contree_sdk.files import ClientFileTransfer, prepare_file_tree


Path("project").mkdir()
Path("project/input.txt").write_text("hello\n")
Path("project/ignored.tmp").write_text("excluded")
files = prepare_file_tree("project", "/app", exclude=("*.tmp",), mode=0o640)
progress = []
with ContreeClient.from_profile(profiles.from_env() or profiles.resolve_profile()) as client:
    transfer = ClientFileTransfer(client, max_concurrency=2, on_progress=progress.append)
    session = ContreeSession(client, image="tag:alpine:latest", file_transfer=transfer)
    session.run(shell="cat /app/input.txt > /result.txt", files=files)
    count = transfer.download_file(session.image_uuid, "/result.txt", "result.txt")
assert count == 6
assert Path("result.txt").read_bytes() == b"hello\n"
assert progress[-1].direction == "download"
assert progress[-1].bytes_transferred == 6

import asyncio
from functools import partial
from pathlib import Path

from contree_client import profiles
from contree_client.asyncio import ContreeAsyncClient

from contree_sdk import ContreeAsyncSession
from contree_sdk.files import AsyncClientFileTransfer, prepare_file_tree


await asyncio.to_thread(Path("project").mkdir)
await asyncio.to_thread(Path("project/input.txt").write_text, "hello\n")
await asyncio.to_thread(Path("project/ignored.tmp").write_text, "excluded")
files = await asyncio.to_thread(partial(prepare_file_tree, "project", "/app", exclude=("*.tmp",), mode=0o640))
progress = []
async with ContreeAsyncClient.from_profile(profiles.from_env() or profiles.resolve_profile()) as client:
    transfer = AsyncClientFileTransfer(client, max_concurrency=2, on_progress=progress.append)
    session = ContreeAsyncSession(client, image="tag:alpine:latest", file_transfer=transfer)
    await session.run(shell="cat /app/input.txt > /result.txt", files=files)
    count = await transfer.download_file(session.image_uuid, "/result.txt", "result.txt")
assert count == 6
assert await asyncio.to_thread(Path("result.txt").read_bytes) == b"hello\n"
assert progress[-1].bytes_transferred == 6

max_concurrency limits uploads within each prepare_files() call. Sync defaults to one worker; async defaults to four. Sync callbacks run in upload worker threads when concurrency exceeds one, so callbacks and custom clients must support that usage. Async callbacks run on the event loop and must not block it. Upload events report a completed file’s size, including server deduplication. Download events report cumulative bytes received for one file. Callbacks are synchronous and their exceptions propagate.

An upload failure cancels queued work and joins active workers. Async cancellation also joins local file I/O before closing files. Uploads already accepted by the server are not undone. Concurrent calls have separate worker limits.

download_file() writes a temporary sibling, flushes it, and replaces the destination only after the stream completes. Failure, cancellation, or a progress callback error preserves the previous destination and removes the temporary file. The parent directory must exist. The replacement uses private temporary-file permissions; it does not retain the destination’s previous mode. If you iterate iter_file() directly, close it on early exit with contextlib.closing() or aclosing().

write_download() and write_download_async() provide the same atomic local writer for other byte iterables. These helpers do not own their input streams; the caller must close them. Custom transfer backends can override iter_file(); its default implementation buffers through read_file().

Inspect the active VM without stopping it

LazySession.inspect() returns a view of the current session. Each file request selects the active VM or, when the session is cold, its saved image. Retaining the view does not keep a VM running. Pending staged files start a VM before reading.

The view provides list, grep, file_exists, archive_exists, read_file, iter_file, download_file, and archive. Paths use the filesystem root rather than the command’s working directory. File contents bypass the operation event log. download_file replaces the local destination only after the complete transfer.

from contextlib import closing

from contree_sdk import create_sandbox_session


with create_sandbox_session(image="tag:alpine:latest") as session:
    session.write_file("/result.txt", b"result\n")
    view = session.inspect()
    with closing(view.iter_file("/result.txt")) as chunks:
        content = b"".join(chunks)
    assert content == b"result\n"
    assert session.phase == "running"
    saved = session.inspect_snapshot()
    assert session.phase == "cold"
    image_uuid = saved.image_uuid

from contextlib import aclosing

from contree_sdk import create_sandbox_session


async with create_sandbox_session(image="tag:alpine:latest") as session:
    await session.write_file("/result.txt", b"result\n")
    view = await session.inspect()
    async with aclosing(view.iter_file("/result.txt")) as chunks:
        content = b"".join([chunk async for chunk in chunks])
    assert content == b"result\n"
    assert session.phase == "running"
    saved = await session.inspect_snapshot()
    assert session.phase == "cold"
    image_uuid = saved.image_uuid

Close streams when iteration stops early. Snapshot and normal session close wait for accepted live requests, including their streams. File requests count as idle activity; they do not increase CommandCountSnapshotPolicy’s command count. Requests arriving during a snapshot wait for it to finish. inspect(timeout=...) limits that admission and startup wait; client settings control HTTP timeouts. Live errors propagate without reading an older image as a fallback.

Live reads can observe concurrent writes. They are not filesystem snapshots. Live grep also differs from image grep in regex support, encoding, ignore rules, and highlight spans. Unsupported patterns raise an error; check truncated on successful results. The live API limits transfers to 300 seconds and directory listings to 10,000 entries. Use inspect_snapshot() for a stable image view; its image_uuid remains fixed across later commands. Image metadata through view.info() requires this same snapshot and stops the VM.