Skip to content

Basic framework fo agentcube#1

Merged
hzxuzhonghu merged 14 commits intovolcano-sh:mainfrom
YaoZengzeng:cube
Oct 25, 2025
Merged

Basic framework fo agentcube#1
hzxuzhonghu merged 14 commits intovolcano-sh:mainfrom
YaoZengzeng:cube

Conversation

@YaoZengzeng
Copy link
Copy Markdown
Member

No description provided.

hzxuzhonghu and others added 14 commits October 25, 2025 07:53
Signed-off-by: Zhonghu Xu <xuzhonghu@huawei.com>
Signed-off-by: Zhonghu Xu <xuzhonghu@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: LiZhenCheng9527 <lizhencheng6@huawei.com>
Signed-off-by: LiZhenCheng9527 <lizhencheng6@huawei.com>
Signed-off-by: Zhonghu Xu <xuzhonghu@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
Signed-off-by: YaoZengzeng <yaozengzeng@huawei.com>
@YaoZengzeng
Copy link
Copy Markdown
Member Author

@hzxuzhonghu ptal

@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello @YaoZengzeng, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request lays the groundwork for agentcube, a robust platform for managing ephemeral, isolated execution environments. It establishes a Go-based API server that orchestrates sandboxes using Kubernetes, defining a clear API for interaction. The system supports secure remote operations through SSH/SFTP tunneled over HTTP CONNECT, and comes with a client-side Python SDK to streamline development. Comprehensive build and deployment tooling, along with integration tests, ensure a solid starting point for the project.

Highlights

  • Core Framework Introduction: This pull request introduces the foundational framework for agentcube, a system designed to manage isolated sandbox environments. It includes a Go-based API server, Kubernetes integration, and a Python SDK.
  • Sandbox API Definition: A comprehensive OpenAPI specification (api-spec/sandbox-api-spec.yaml) is added, detailing endpoints for sandbox lifecycle management (create, list, get, delete, pause, resume), command execution, code execution, and file transfers.
  • Kubernetes Integration: The pico-apiserver is designed to run on Kubernetes, utilizing a SandboxReconciler controller to manage Sandbox Custom Resources (CRDs). Deployment manifests (k8s/pico-apiserver.yaml) are provided for easy setup.
  • Default Sandbox Image & SSH Tunneling: A default Python-based sandbox Docker image (images/sandbox/Dockerfile) is included, pre-configured with an SSH server. The API server supports SSH/SFTP over HTTP CONNECT tunnels for secure and efficient data plane operations.
  • Python SDK and Integration Tests: A Python SDK (sdk/sandbox_sessions_sdk.py) is provided for client interaction, complete with documentation and examples. Go-based integration tests (test-integration/client.go) validate SSH key-based authentication and file transfer functionalities.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request lays the foundational framework for the agentcube project, introducing the pico-apiserver, its associated Kubernetes configurations, Docker images, and a Python SDK. The overall structure is comprehensive, but there are several critical and high-severity issues related to security, correctness, and maintainability that need to be addressed. Key areas of concern include insecure defaults in the sandbox Docker image, placeholder authentication logic, potential memory leaks, and race conditions in the server logic. The review provides specific suggestions to harden the security posture, improve robustness, and align with best practices.

Comment on lines +33 to +39
// TODO: Implement actual JWT validation
// This should use jwt-go or similar library to validate the token
// Verify signature, expiration, claims, etc.
if !s.validateToken(token) {
respondError(w, http.StatusUnauthorized, "UNAUTHORIZED", "Invalid or expired token")
return
}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

The current JWT validation is a placeholder and is critically insecure. The validateToken function only checks if a token is non-empty, allowing any non-empty string to act as a valid authentication token. You must implement proper JWT validation, including signature verification and expiration checks, using a standard library like github.com/golang-jwt/jwt.

containers:
- name: pico-apiserver
image: pico-apiserver:latest
imagePullPolicy: IfNotPresent
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Using imagePullPolicy: IfNotPresent with the :latest tag is not recommended. If an image with the :latest tag already exists on a node, Kubernetes will not pull a newer version. To ensure the deployment always uses the most recent image, this should be changed to Always.

          imagePullPolicy: Always

# Secrets
*.pem
*.key
!**/tls.key
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The pattern !**/tls.key negates the previous *.key pattern, causing files named tls.key to be tracked by Git. Committing private key files to the repository is a major security risk. Unless these are non-sensitive test keys, this line should be removed to ensure all *.key files are ignored.

self.timeout = timeout
self.verify_ssl = verify_ssl
self.connect_path_template = connect_path_template
self.host_key_policy = host_key_policy or paramiko.AutoAddPolicy()
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The SandboxSSHClient defaults to using paramiko.AutoAddPolicy(), which automatically adds unknown host keys. This is insecure and makes the client vulnerable to Man-in-the-Middle (MITM) attacks. The default policy should be paramiko.RejectPolicy() to be secure by default. You can allow users to explicitly pass AutoAddPolicy for use in trusted environments, but it should not be the default.

Suggested change
self.host_key_policy = host_key_policy or paramiko.AutoAddPolicy()
self.host_key_policy = host_key_policy or paramiko.RejectPolicy()

Comment on lines +67 to +79
docker-build:
@echo "Building Docker image..."
docker build -t pico-apiserver:latest .

# Install to system
install: build
@echo "Installing pico-apiserver..."
sudo cp bin/pico-apiserver /usr/local/bin/

# Docker and Kubernetes targets
docker-build:
@echo "Building Docker image..."
docker build -t pico-apiserver:latest .
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

There are duplicate docker-build targets defined in the Makefile (lines 67 and 77). The second definition will override the first, making the first one redundant and potentially causing confusion. Please remove one of the definitions.

Comment on lines +570 to +572
type: string
description: MD5 checksum of file content
example: "5d41402abc4b2a76b9719d911017c592"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The checksum field uses MD5, which is considered cryptographically broken and should not be used for integrity checks where security is a concern. It is vulnerable to collision attacks. Please consider using a more secure hashing algorithm like SHA-256.

        checksum:
          type: string
          description: SHA-256 checksum of file content
          example: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Comment on lines +218 to +219
"200":
description: Sandbox deleted successfully
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For a successful DELETE operation that doesn't return a body, the 204 No Content status code is more conventional than 200 OK.

        "204":
          description: Sandbox deleted successfully

user: "john.doe"
project: "test-automation"
responses:
"200":
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For creating a new resource, the HTTP status code 201 Created is more appropriate than 200 OK. It clearly indicates that a new resource has been successfully created.

        "201":

Comment on lines +72 to +74
install: build
@echo "Installing pico-apiserver..."
sudo cp bin/pico-apiserver /usr/local/bin/
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The install target uses sudo, which can be problematic as it requires the user to have sudo privileges and can have unintended side effects. It's better to let the user decide when to use sudo. The common practice is to instruct users to run sudo make install if they need to install system-wide.

install: build
	@echo "Installing pico-apiserver to /usr/local/bin..."
	cp bin/pico-apiserver /usr/local/bin/

Comment on lines +28 to +29
RUN adduser -D -u 1000 apiserver
USER apiserver
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Running the container as a non-root user is a good security practice. However, the user apiserver is created without a specific group, which might lead to it being in the root group (GID 0) on some base images. It's better to explicitly create and use a non-root group.

RUN addgroup -S -g 1000 apiserver && adduser -S -u 1000 -G apiserver apiserver
USER apiserver

@hzxuzhonghu hzxuzhonghu merged commit 6b01523 into volcano-sh:main Oct 25, 2025
1 check passed
LiZhenCheng9527 referenced this pull request in LiZhenCheng9527/agentcube Oct 25, 2025
ListWatch sandbox and Provide notification for the sandbox running
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants