feat(sdk): add gzip option to template copy layer (#1482)

Adds a `gzip` option to the template `.copy()` / `copyItems` layer that
controls whether copied files are gzipped before upload, threaded from
the copy call through the build-time tar stream in both the JS SDK and
the sync/async Python SDKs. It is enabled by default to preserve
existing behavior, so passing `gzip: false` (`gzip=False`) uploads an
uncompressed tar — useful for already-compressed payloads where gzip
adds CPU cost without shrinking the upload. The option name matches
node-tar's own `gzip` option and the existing sandbox filesystem `gzip`
kwarg. Gzip is deliberately excluded from the file cache hash, so
toggling it does not bust the build cache. Tests in both SDKs were
updated for the new argument and extended with `gzip: false` cases
asserting the archive is not gzipped yet still extracts, and a changeset
(`minor` for both packages) is included.

> [!NOTE]
> The server that extracts these uploaded archives lives in another repo
and must auto-detect compression (peek the gzip `0x1f 0x8b` magic)
rather than assuming gzip; confirm it handles plain tars before release.

## Usage

```ts
// JS/TS
template.copy('model.bin', '/app/', { gzip: false })
template.copyItems([{ src: 'a.bin', dest: '/app/', gzip: false }])
```

```python
# Python (sync & async)
template.copy('model.bin', '/app/', gzip=False)
template.copy_items([{ 'src': 'a.bin', 'dest': '/app/', 'gzip': False }])
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mishushakov

.changeset/copy-compression-option.md

@@ -0,0 +1,22 @@
+---
+"e2b": minor
+"@e2b/python-sdk": minor
+---
+
+Add a `gzip` option to the template `copy` layer to control whether copied
+files are gzipped before upload.
+
+Gzip is enabled by default (matching the previous behavior). Pass
+`gzip: false` (`gzip=False` in Python) to upload an uncompressed tar archive
+instead — useful when copying already-compressed files where gzipping adds
+CPU cost without shrinking the payload.
+
+```ts
+// JS/TS
+template.copy('model.bin', '/app/', { gzip: false })
+```
+
+```python
+# Python
+template.copy('model.bin', '/app/', gzip=False)
+```

packages/js-sdk/src/template/buildApi.ts

@@ -111,6 +111,7 @@ export async function uploadFile(
     url: string
     ignorePatterns: string[]
     resolveSymlinks: boolean
+    gzip: boolean
   },
   stackTrace: string | undefined,
   // Uploads (PUT to S3 presigned URL) can take a long time for large
@@ -120,8 +121,14 @@ export async function uploadFile(
   // via `signal`) to override.
   abortOpts?: { signal?: AbortSignal; requestTimeoutMs?: number }
 ) {
-  const { fileName, url, fileContextPath, ignorePatterns, resolveSymlinks } =
-    options
+  const {
+    fileName,
+    url,
+    fileContextPath,
+    ignorePatterns,
+    resolveSymlinks,
+    gzip,
+  } = options
   // Spool the archive to a temporary file and stream it from disk instead of
   // buffering in memory. S3 presigned PUT URLs reject Transfer-Encoding:
   // chunked with 501 NotImplemented (see e2b-dev/e2b#1243), so the upload
@@ -139,7 +146,8 @@ export async function uploadFile(
       fileName,
       fileContextPath,
       ignorePatterns,
-      resolveSymlinks
+      resolveSymlinks,
+      gzip
     )
     uploadStream = tar.stream
 

packages/js-sdk/src/template/consts.ts

@@ -33,6 +33,13 @@ export const STACK_TRACE_DEPTH = 3
  */
 export const RESOLVE_SYMLINKS = false
 
+/**
+ * Default setting for whether to gzip files when copying them into the
+ * template. When true, the upload archive is gzipped before being uploaded.
+ * @internal
+ */
+export const GZIP = true
+
 /**
  * Default per-request timeout (in milliseconds) for the file-upload phase
  * (PUT to S3 presigned URL) when the caller hasn't supplied

packages/js-sdk/src/template/index.ts

@@ -16,7 +16,7 @@ import {
   uploadFile,
   waitForBuildFinish,
 } from './buildApi'
-import { RESOLVE_SYMLINKS, STACK_TRACE_DEPTH } from './consts'
+import { GZIP, RESOLVE_SYMLINKS, STACK_TRACE_DEPTH } from './consts'
 import { parseDockerfile } from './dockerfileParser'
 import { LogEntry, LogEntryEnd, LogEntryStart } from './logger'
 import { ReadyCmd, waitForFile } from './readycmd'
@@ -570,6 +570,7 @@ export class TemplateBase
       user?: string
       mode?: number
       resolveSymlinks?: boolean
+      gzip?: boolean
     }
   ): TemplateBuilder {
     if (runtime === 'browser') {
@@ -598,6 +599,7 @@ export class TemplateBase
         force: options?.forceUpload || this.forceNextLayer,
         forceUpload: options?.forceUpload,
         resolveSymlinks: options?.resolveSymlinks,
+        gzip: options?.gzip,
       })
 
       // Collect one stack trace per pushed instruction so build steps stay
@@ -626,6 +628,7 @@ export class TemplateBase
             user: item.user,
             mode: item.mode,
             resolveSymlinks: item.resolveSymlinks,
+            gzip: item.gzip,
           })
         } catch (error) {
           const copyError = error as Error
@@ -1193,6 +1196,7 @@ export class TemplateBase
                 ...readDockerignore(this.fileContextPath.toString()),
               ],
               resolveSymlinks: instruction.resolveSymlinks ?? RESOLVE_SYMLINKS,
+              gzip: instruction.gzip ?? GZIP,
             },
             stackTrace,
             // Forward `requestTimeoutMs` only when the caller set it — we

packages/js-sdk/src/template/types.ts

@@ -197,6 +197,7 @@ export type Instruction = {
   forceUpload?: true
   filesHash?: string
   resolveSymlinks?: boolean
+  gzip?: boolean
 }
 
 /**
@@ -209,6 +210,7 @@ export type CopyItem = {
   user?: string
   mode?: number
   resolveSymlinks?: boolean
+  gzip?: boolean
 }
 
 /**
@@ -412,6 +414,7 @@ export interface TemplateBuilder {
       user?: string
       mode?: number
       resolveSymlinks?: boolean
+      gzip?: boolean
     }
   ): TemplateBuilder
 

packages/js-sdk/src/template/utils.ts

@@ -371,13 +371,15 @@ export function padOctal(mode: number): string {
  * @param fileContextPath Base directory for resolving file paths
  * @param ignorePatterns Ignore patterns to exclude from the archive
  * @param resolveSymlinks Whether to follow symbolic links
+ * @param gzip Whether to gzip the archive
  * @returns The readable stream and the archive size in bytes
  */
 export async function tarFileStream(
   fileName: string,
   fileContextPath: string,
   ignorePatterns: string[],
-  resolveSymlinks: boolean
+  resolveSymlinks: boolean,
+  gzip: boolean
 ): Promise<{ stream: Readable; size: number }> {
   const { create } = await dynamicImport<typeof import('tar')>('tar')
   // Dynamically import so the browser bundle doesn't pull in node:fs.
@@ -405,7 +407,7 @@ export async function tarFileStream(
   try {
     await create(
       {
-        gzip: true,
+        gzip,
         cwd: fileContextPath,
         follow: resolveSymlinks,
         noDirRecurse: true,

packages/js-sdk/tests/template/uploadFile.test.ts

@@ -52,6 +52,7 @@ describe('uploadFile transfer encoding', () => {
         url: baseUrl,
         ignorePatterns: [],
         resolveSymlinks: false,
+        gzip: true,
       },
       undefined
     )

packages/js-sdk/tests/template/utils/tarFileStream.test.ts

@@ -126,7 +126,13 @@ describe('tarFileStream', () => {
     await writeFile(join(testDir, 'file1.txt'), 'content1')
     await writeFile(join(testDir, 'file2.txt'), 'content2')
 
-    const { stream, size } = await tarFileStream('*.txt', testDir, [], false)
+    const { stream, size } = await tarFileStream(
+      '*.txt',
+      testDir,
+      [],
+      false,
+      true
+    )
     expect(size).toBeGreaterThan(0)
 
     const contents = await extractTarContents(stream)
@@ -136,6 +142,39 @@ describe('tarFileStream', () => {
     expect(contents.get('file2.txt')?.toString()).toBe('content2')
   })
 
+  test('should create an uncompressed tar when gzip is disabled', async () => {
+    await writeFile(join(testDir, 'file1.txt'), 'content1')
+    await writeFile(join(testDir, 'file2.txt'), 'content2')
+
+    const { stream } = await tarFileStream('*.txt', testDir, [], false, false)
+
+    // Buffer the archive so we can both assert it is not gzipped and extract it
+    const chunks: Buffer[] = []
+    for await (const chunk of stream as unknown as AsyncIterable<Buffer>) {
+      chunks.push(Buffer.from(chunk))
+    }
+    const archive = Buffer.concat(chunks)
+
+    // gzip streams start with the magic bytes 0x1f 0x8b — an uncompressed tar must not
+    expect(archive[0]).not.toBe(0x1f)
+    expect(archive.subarray(0, 2).equals(Buffer.from([0x1f, 0x8b]))).toBe(false)
+
+    // And it should still extract to the original files
+    const tarFile = join(tmpdir(), `tar-uncompressed-${Date.now()}.tar`)
+    await writeFile(tarFile, archive)
+    const extractDir = join(tmpdir(), `tar-uncompressed-extract-${Date.now()}`)
+    await mkdir(extractDir, { recursive: true })
+    await tar.extract({ file: tarFile, cwd: extractDir })
+    expect((await readFile(join(extractDir, 'file1.txt'))).toString()).toBe(
+      'content1'
+    )
+    expect((await readFile(join(extractDir, 'file2.txt'))).toString()).toBe(
+      'content2'
+    )
+    await rm(tarFile, { force: true })
+    await rm(extractDir, { recursive: true, force: true })
+  })
+
   test('should respect ignore patterns', async () => {
     await writeFile(join(testDir, 'file1.txt'), 'content1')
     await writeFile(join(testDir, 'file2.txt'), 'content2')
@@ -146,7 +185,8 @@ describe('tarFileStream', () => {
       '*.txt',
       testDir,
       ['temp*', 'backup*'],
-      false
+      false,
+      true
     )
 
     const contents = await extractTarContents(stream)
@@ -165,7 +205,7 @@ describe('tarFileStream', () => {
     await writeFile(join(testDir, 'src', 'index.ts'), 'index content')
     await writeFile(join(nestedDir, 'Button.tsx'), 'button content')
 
-    const { stream } = await tarFileStream('src', testDir, [], false)
+    const { stream } = await tarFileStream('src', testDir, [], false, true)
 
     const contents = await extractTarContents(stream)
     const paths = Array.from(contents.keys())
@@ -187,7 +227,8 @@ describe('tarFileStream', () => {
       throw error
     }
 
-    const { stream } = await tarFileStream('*.txt', testDir, [], true)
+    // Test with resolveSymlinks=true
+    const { stream } = await tarFileStream('*.txt', testDir, [], true, true)
 
     const contents = await extractTarContents(stream)
     expect(contents.get('original.txt')?.toString()).toBe('original content')
@@ -208,7 +249,8 @@ describe('tarFileStream', () => {
       throw error
     }
 
-    const { stream } = await tarFileStream('*.txt', testDir, [], false)
+    // Test with resolveSymlinks=false
+    const { stream } = await tarFileStream('*.txt', testDir, [], false, true)
 
     const members = await getTarMembers(stream)
     expect(members.get('original.txt')?.type).toBe('File')

packages/python-sdk/e2b/template/consts.py

@@ -29,6 +29,12 @@
 """
 RESOLVE_SYMLINKS = False
 
+"""
+Default setting for whether to gzip files when copying them into the
+template. When True, the upload archive is gzipped before being uploaded.
+"""
+GZIP = True
+
 """
 Default timeout (in seconds) for uploading the build-context archive to the
 S3 presigned URL. Uploads of large archives can take far longer than the 60s

packages/python-sdk/e2b/template/dockerfile_parser.py

@@ -28,6 +28,7 @@ def copy(
         user: Optional[str] = None,
         mode: Optional[int] = None,
         resolve_symlinks: Optional[bool] = None,
+        gzip: Optional[bool] = None,
     ) -> "DockerfileParserInterface":
         """Handle COPY instruction."""
         ...