Contributing to OpenSandbox

Thank you for your interest in contributing to OpenSandbox! This guide will help you get started with contributing to the project, whether you're fixing bugs, adding features, improving documentation, or helping in other ways.

Code of Conduct
Getting Started
Development Environment Setup
Project Structure
Development Workflow
Coding Standards
Testing Guidelines
Submitting Contributions
Communication Channels

Code of Conduct

OpenSandbox adheres to a Code of Conduct that we expect all contributors to follow. Please read it before contributing to ensure a welcoming and inclusive environment for everyone.

Getting Started

Ways to Contribute

There are many ways to contribute to OpenSandbox:

Report Bugs: Submit detailed bug reports through GitHub Issues
Suggest Features: Propose new features or improvements
Write Code: Fix bugs, implement features, or improve performance
Improve Documentation: Enhance README files, write tutorials, or fix typos
Write Tests: Add test coverage or improve existing tests
Review Pull Requests: Help review and test others' contributions
Answer Questions: Help other users in GitHub Discussions or Issues

Before You Start

Search Existing Issues: Check if your bug report or feature request already exists
Check Roadmap: Review the project roadmap to see if your idea aligns with project goals
Discuss Major Changes: For significant changes, open an issue first or submit an OSEP to discuss your approach
Review Architecture: Read docs/architecture.md to understand the system design

Development Environment Setup

Prerequisites

Different components have different requirements:

For Server (Python)

Python 3.10+
uv - Python package manager (installation guide)
Docker - For running sandboxes locally

For execd (Go)

Go 1.24+
Make - Build automation (optional)
Docker - For building container images

For SDKs

Python SDK: Python 3.10+, uv
Java/Kotlin SDK: JDK 17+, Gradle

Quick Setup

Server Development

# Navigate to server directory
cd server

# Install dependencies
uv sync

# Copy example configuration
cp example.config.toml ~/.sandbox.toml

# Edit configuration for development
# Set log_level = "DEBUG" and api_key
nano ~/.sandbox.toml

# Run server
uv run python -m src.main

See server/DEVELOPMENT.md for detailed server development guide.

execd Development

# Navigate to execd directory
cd components/execd

# Download dependencies
go mod download

# Build execd
go build -o bin/execd .

# Run execd (requires Jupyter Server)
./bin/execd --jupyter-host=http://localhost:8888 --port=44772

See components/execd/DEVELOPMENT.md for detailed execd development guide.

SDK Development

Python SDK:

cd sdks/sandbox/python
uv sync
uv run pytest

Java/Kotlin SDK:

cd sdks/sandbox/kotlin
./gradlew build
./gradlew test

Project Structure

OpenSandbox/
├── sdks/                     # Multi-language SDKs
│   ├── code-interpreter/     # Code Interpreter SDK (Python, Kotlin)
│   └── sandbox/              # Sandbox base SDK (Python, Kotlin)
├── specs/                    # OpenAPI specifications
│   ├── execd-api.yaml        # Execution API spec
│   └── sandbox-lifecycle.yml # Lifecycle API spec
├── server/                   # Sandbox server (Python/FastAPI)
├── components/
│   └── execd/                # Execution daemon (Go/Beego)
├── sandboxes/                # Sandbox implementations
│   └── code-interpreter/     # Code Interpreter sandbox
├── examples/                 # Example integrations
├── docs/                     # Documentation
├── tests/                    # Cross-component tests
│   └── e2e/                  # End-to-end tests
└── scripts/                  # Build and utility scripts

Development Workflow

Enhancement Proposals (OSEP)

For major features, architectural changes, or modifications to the core API/security model, we follow the OSEP (OpenSandbox Enhancement Proposals) process.

Please read the OSEP README to understand when an OSEP is required and how to submit one. Small bug fixes and minor improvements do not require an OSEP.

Branching Strategy

main: Stable production branch
feature/[name]: New features
fix/[name]: Bug fixes
docs/[name]: Documentation updates
refactor/[name]: Code refactoring
test/[name]: Test additions or improvements

Creating a Feature Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/my-awesome-feature

# Make your changes
# ...

# Commit your changes
git add .
git commit -m "feat: add my awesome feature"

# Push to your fork
git push origin feature/my-awesome-feature

Commit Message Format

We follow Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, no logic change)
refactor: Code refactoring
test: Adding or updating tests
chore: Build process, dependencies, or tooling changes
perf: Performance improvements
ci: CI/CD changes

Examples:

feat(server): add Kubernetes runtime support
fix(execd): resolve memory leak in session cleanup
docs(sdk): add Python SDK usage examples
test(server): add integration tests for Docker runtime
refactor(sdk): simplify filesystem API

Making Changes

Write Clean Code: Follow project coding standards (see below)
Add Tests: Ensure your changes are covered by tests
Update Documentation: Update relevant documentation files
Test Locally: Run all tests and ensure they pass
Check Linting: Run linters and fix any issues

Coding Standards

Python (Server, Python SDKs)

Style Guide: Follow PEP 8
Formatter: Use ruff for formatting and linting
Type Hints: Always use type hints for function signatures
Docstrings: Use Google-style docstrings for public APIs

def create_sandbox(
    image: ImageSpec,
    timeout: timedelta,
    entrypoint: Optional[List[str]] = None
) -> Sandbox:
    """Create a new sandbox instance.

    Args:
        image: Container image specification
        timeout: Sandbox timeout duration
        entrypoint: Optional custom entrypoint command

    Returns:
        Created sandbox instance

    Raises:
        ValueError: If image or timeout is invalid
    """
    # Implementation

Running Linter:

cd server
uv run ruff check src tests
uv run ruff format src tests

Go (execd)

Style Guide: Follow Effective Go
Formatter: Use gofmt for formatting
Imports: Organize in three groups (stdlib, third-party, internal)
Error Handling: Always handle errors explicitly

// Good
result, err := someOperation()
if err != nil {
    logs.Error("operation failed: %v", err)
    return fmt.Errorf("failed to do something: %w", err)
}

// Bad - silent failure
result, _ := someOperation()

Running Formatter:

cd components/execd
gofmt -w .
# Or
make fmt

Java/Kotlin (Java/Kotlin SDKs)

Style Guide: Follow Kotlin Coding Conventions
Formatter: Use ktlint
Null Safety: Use Kotlin's null safety features

suspend fun createSandbox(
    image: ImageSpec,
    timeout: Duration,
    entrypoint: List<String>? = null
): Sandbox {
    // Implementation
}

General Guidelines

Naming Conventions:
- Functions/Methods: snake_case (Python), camelCase (Go, Kotlin)
- Classes: PascalCase (all languages)
- Constants: UPPER_SNAKE_CASE (all languages)
- Private members: _leading_underscore (Python), unexported (Go)
Comments: Write clear, concise comments explaining "why", not "what"
Error Messages: Provide actionable error messages with context
Logging: Use appropriate log levels (DEBUG, INFO, WARNING, ERROR)

Testing Guidelines

Test Coverage Requirements

Core Packages: Aim for >80% coverage
API Layer: Aim for >70% coverage
Utilities: Aim for >90% coverage

Writing Tests

Python Tests (pytest)

import pytest
from opensandbox import Sandbox

@pytest.mark.asyncio
async def test_create_sandbox():
    """Test sandbox creation with valid parameters."""
    sandbox = await Sandbox.create(
        image="python:3.11",
        timeout=timedelta(minutes=5)
    )
    assert sandbox.id is not None
    assert sandbox.status == SandboxStatus.PENDING
    await sandbox.kill()

@pytest.mark.asyncio
async def test_invalid_timeout():
    """Test sandbox creation fails with invalid timeout."""
    with pytest.raises(ValueError):
        await Sandbox.create(
            image="python:3.11",
            timeout=timedelta(seconds=-1)
        )

Running Tests:

cd server
uv run pytest
uv run pytest --cov=src --cov-report=html

Go Tests

func TestController_Execute_Python(t *testing.T) {
    ctrl := NewController("http://localhost:8888", "test-token")

    req := &ExecuteCodeRequest{
        Language: Python,
        Code:     "print('hello')",
    }

    err := ctrl.Execute(req)
    assert.NoError(t, err)
}

Running Tests:

cd components/execd
go test ./pkg/...
go test -v -cover ./pkg/...

Integration Tests

Integration tests require Docker:

# Server integration tests
cd server
uv run pytest tests/integration/

# E2E tests
cd tests/e2e/python
uv run pytest

Test Best Practices

Test Names: Use descriptive names that explain what is being tested
Arrange-Act-Assert: Structure tests clearly
Isolation: Each test should be independent
Mocking: Mock external dependencies appropriately
Cleanup: Always clean up resources (use fixtures, context managers)

Submitting Contributions

Pull Request Process

Create Feature Branch: Branch from main
Make Changes: Implement your feature or fix
Write Tests: Add comprehensive test coverage
Update Documentation: Update relevant docs
Test Locally: Ensure all tests pass
Run Linters: Fix any style issues
Commit Changes: Use conventional commit messages
Push to Fork: Push your branch to your fork
Create Pull Request: Submit PR with detailed description

Pull Request Template

When creating a PR, fill out the template:

# Summary

- What is changing and why?

# Testing

- [ ] Not run (explain why)
- [ ] Unit tests
- [ ] Integration tests
- [ ] e2e / manual verification

# Breaking Changes

- [ ] None
- [ ] Yes (describe impact and migration path)

# Checklist

- [ ] Linked Issue or clearly described motivation
- [ ] Added/updated docs (if needed)
- [ ] Added/updated tests (if needed)
- [ ] Security impact considered
- [ ] Backward compatibility considered

Pull Request Guidelines

Do:

Keep PRs focused and reasonably sized (< 500 lines if possible)
Write clear PR descriptions with motivation and context
Link related issues
Respond to review comments promptly
Update your PR based on feedback
Ensure CI passes before requesting review

Don't:

Mix multiple unrelated changes in one PR
Submit PRs with failing tests
Ignore code review feedback
Force push after reviews have started (unless necessary)
Include commented-out code or debug statements

Code Review Process

Automated Checks: CI runs tests, linters, and security scans
Maintainer Review: A maintainer reviews your code
Feedback Loop: Address review comments
Approval: Once approved, a maintainer will merge your PR
Cleanup: Delete your feature branch after merge

Communication Channels

GitHub Issues

Use GitHub Issues for:

Bug reports
Feature requests
Documentation improvements
Questions about implementation

Bug Report Template:

**Description**
A clear description of the bug.

**To Reproduce**
Steps to reproduce the behavior:

1. Create sandbox with...
2. Execute command...
3. See error

**Expected Behavior**
What you expected to happen.

**Environment**

- OpenSandbox version:
- Runtime (Docker/K8s):
- OS:
- Python/Go version:

**Additional Context**
Logs, screenshots, or other relevant information.

GitHub Discussions

Use GitHub Discussions for:

General questions
Design discussions
Brainstorming ideas
Community help

Getting Help

Issues: Technical problems or bugs
Discussions: Questions and community support
Email: For security issues, email conduct@opensandbox.io

Additional Resources

Documentation

Examples

Browse examples/ for real-world usage patterns:

Code Interpreter integration
AI Coding Agent integrations (Claude Code, Gemini CLI, etc.)
Browser automation (Chrome, Playwright)
Remote development (VS Code, Desktop)

External Resources

Acknowledgments

Thank you for contributing to OpenSandbox! Your contributions help make this project better for everyone in the AI and developer tools community.

If you have suggestions for improving this contributing guide, please open an issue or submit a pull request.

License

By contributing to OpenSandbox, you agree that your contributions will be licensed under the Apache 2.0 License.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History