Workspace Management

Every TestBase Container mounts a /workspace directory that mirrors the repository the agent is operating on. The workspace is the heart of the execution environment—it is where Codex reads and writes files, runs shell commands, and talks to git.

Storage model

Google Cloud Storage backing
Each container syncs to gs://<bucket>/<containerId>/workspace/. Uploads and downloads through the Files API operate directly on this bucket, so changes persist even when the container shuts down.
Two-way synchronization
entrypoint.sh pulls the latest contents from GCS during boot, then pushes updates back on graceful shutdown. File operations triggered via the Files API write immediately to GCS and become available to the running container on the next sync cycle.
Multi-container resilience
Because workspaces live in GCS, you can tear down a container and create a replacement pointing at the same logical project. Persistent containers simply keep the runtime alive between tasks.

Git requirements

The Codex CLI expects a git repository:

The workspace must already be a git repo or created from one.
When you upload files, include .git metadata if you want history to carry over.
computer-agents will initialize git automatically when creating a container if the source path already contains .git.

Managing files

Operation	Cloud SDK helper	REST endpoint
List directory	`cloud.listFiles(containerId, path)`	`GET /api/v1/containers/:id/files?path=/workspace`
Upload or overwrite	`cloud.uploadFile(containerId, path, content)`	`PUT /api/v1/containers/:id/files`
Download (Buffer response)	`cloud.downloadFile(containerId, path)`	`GET /api/v1/containers/:id/files/download?path=…`
Delete	`cloud.deleteFile(containerId, path)`	`DELETE /api/v1/containers/:id/files?path=…`

The SDK handles all serialization and authentication; you only need to pass the container ID returned by createCloudAgent or createContainer.

Best practices

Use project-relative paths
Always reference files from /workspace. Example: /workspace/src/index.ts. This keeps uploads portable and compatible with both local and cloud runners.
Batch uploads before execution
Upload dependency manifests, environment files, and seeding scripts before running the task so the agent starts with the right context.
Audit generated files
After execution, call listFiles and selectively downloadFile artifacts like test results or generated assets.
Clean up intentionally
deleteFile removes the object from GCS immediately. If you need audit history, prefer archiving files locally rather than deleting them from the workspace.
Watch storage growth
Persistent containers accumulate artefacts. Periodically prune logs or intermediate outputs via deleteFile to keep storage lean.

Workspace APIs are idempotent and safe to invoke repeatedly, making it easy to weave them into CI/CD flows or custom dashboards.